pharos_native/runtime/

mod.rs

#![allow(clippy::too_many_arguments)]

#[cfg(test)]
use pharos_runtime_docs::rustdoc::docs_cargo_executable_candidates;
use pharos_runtime_docs::rustdoc::docs_run_cargo_doc;

/// Exposes Architect webapp-owned agent worker services.
pub mod agent_architect;
/// Exposes the `agent_bridge` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::agent_bridge;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod agent_bridge;
/// Exposes Architect attachment and task-ingestion services.
pub mod agent_ingest;
#[cfg(not(target_os = "wasi"))]
/// Exposes optional Architect media extraction adapters and artifact readiness checks.
pub mod agent_media;
/// Exposes Architect provider-secret vault services.
pub mod agent_vault;
mod architect_chatgpt_http;
mod architect_http;
mod architect_import;
mod architect_preview_accounts;
mod architect_project_identity;
mod event_discovery;
mod outbound_url;
#[cfg(not(target_os = "wasi"))]
mod social_connections;
use architect_chatgpt_http::*;
use architect_http::*;
/// Exposes shared app scaffold helpers used by the CLI and agent bridge.
#[cfg(not(target_os = "wasi"))]
/// Exposes the `backup` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::backup;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod backup;
/// Exposes the `business` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::business;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod business;
/// Exposes the `cache` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::cache;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod cache;
/// Exposes the `cache_key` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::cache_key;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod cache_key;
/// Exposes the `connection` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::connection;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod connection;
/// Exposes the `database` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::database;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod database;
/// Exposes the `declarative` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::declarative;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod declarative;
/// Exposes the `docs` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::docs;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod docs;
/// Exposes the `dynamic` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::dynamic;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod dynamic;
/// Exposes the `feature_runtime` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::feature_runtime;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod feature_runtime;
/// Exposes the `features` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::features;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod features;
/// Exposes the `fs` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::fs;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod fs;
/// Exposes the `generated` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::generated;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod generated;
/// Exposes the `http` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::http;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod http;
/// Exposes the `job` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::job;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod job;
/// Exposes the `json_commands` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::json_commands;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod json_commands;
/// Exposes the `json_ops` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::json_ops;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod json_ops;
#[cfg(not(target_os = "wasi"))]
/// Exposes the `listener` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::listener;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod listener;
/// Exposes the `ops_bridge` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::ops_bridge;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod ops_bridge;
/// Framework-owned, app-neutral payment-provider lifecycle contracts.
pub mod payment_provider;
/// Exposes the `ui` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::ui;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod ui;

/// Exposes the `reference` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::reference;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod reference;
/// Exposes the `runtime_reports` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::runtime_reports;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod runtime_reports;
/// Exposes the `runtime_stack` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::runtime_stack;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod runtime_stack;
/// Exposes the `state_store` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::state_store;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod state_store;
/// Exposes the `support` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::support;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod support;
#[cfg(not(target_os = "wasi"))]
/// Exposes the `worker_pool` runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// use pharos_native::runtime::worker_pool;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for sibling modules in the same crate.
pub mod worker_pool;

use std::collections::{BTreeMap, BTreeSet};
use std::fs as stdfs;
use std::io::{Read, Seek, SeekFrom, Write};
use std::net::{Shutdown, TcpListener, TcpStream};
#[cfg(unix)]
use std::os::unix::net::{UnixListener, UnixStream};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, OnceLock, RwLock};
use std::thread;
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};

use pharos_runtime_architect::preview_style::{
    architect_preview_append_style_override, architect_preview_css_selector,
    architect_preview_merge_property_override, architect_preview_property_override,
    architect_preview_style_declarations, architect_preview_style_error_message,
};
use serde_json::{Map, Value};
use sha2::{Digest, Sha256};

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

pub type RuntimeStack = pharos_runtime_core::stack::RuntimeStack;
pub type RuntimeAppLoadFailure = pharos_runtime_core::stack::RuntimeAppLoadFailure;

/// Implementation status marker for the runtime module.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::MODULE_STATUS;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for the surrounding module surface.
pub const MODULE_STATUS: &str = "COMPLETE";
/// Version string embedded in the runtime stack contract.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::PHAROS_RUNTIME_STACK_VERSION;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for the surrounding module surface.
pub const PHAROS_RUNTIME_STACK_VERSION: &str = env!("CARGO_PKG_VERSION");
/// Version string embedded in the native runtime binary.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::PHAROS_VERSION;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for the surrounding module surface.
pub const PHAROS_VERSION: &str = env!("CARGO_PKG_VERSION");
/// Stable target identifier for the native host runtime.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::PHAROS_TARGET_ID;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for the surrounding module surface.
pub const PHAROS_TARGET_ID: &str = "native-host-target";

pub type FrameworkBuiltinResponse = pharos_runtime_core::builtin::FrameworkBuiltinResponse;

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
/// TLS policy enforced for PostgreSQL runtime connections.
///
/// # Variants
///
/// - `RustlsRequired`: Supported `PostgresTlsMode` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::PostgresTlsMode::RustlsRequired;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for constructors, helpers, and neighboring runtime types.
pub enum PostgresTlsMode {
    RustlsRequired,
}

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
/// Availability state for one runtime capability.
///
/// # Variants
///
/// - `Available`: Supported `CapabilityState` variant.
/// - `Pending`: Supported `CapabilityState` variant.
/// - `UnsupportedOnWasi`: Supported `CapabilityState` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::CapabilityState::Available;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for constructors, helpers, and neighboring runtime types.
pub enum CapabilityState {
    Available,
    Pending,
    UnsupportedOnWasi,
}

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
/// Advertised runtime capability scaffold for the current host build.
///
/// # Fields
///
/// - `sqlite`: Stored field on `RuntimeScaffold`.
/// - `postgresql`: Stored field on `RuntimeScaffold`.
/// - `smtp`: Stored field on `RuntimeScaffold`.
/// - `tls_mode`: Stored field on `RuntimeScaffold`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::runtime::RuntimeScaffold>();
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for constructors, helpers, and neighboring runtime types.
pub struct RuntimeScaffold {
    pub sqlite: CapabilityState,
    pub postgresql: CapabilityState,
    pub smtp: CapabilityState,
    pub tls_mode: PostgresTlsMode,
}

/// Advertised capability scaffold for the current native build.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::RUNTIME_CAPABILITY_STATUS;
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for the surrounding module surface.
pub const RUNTIME_CAPABILITY_STATUS: RuntimeScaffold = RuntimeScaffold {
    sqlite: if cfg!(target_os = "wasi") {
        CapabilityState::UnsupportedOnWasi
    } else {
        CapabilityState::Available
    },
    postgresql: if cfg!(target_os = "wasi") {
        CapabilityState::UnsupportedOnWasi
    } else {
        CapabilityState::Available
    },
    smtp: if cfg!(target_os = "wasi") {
        CapabilityState::UnsupportedOnWasi
    } else {
        CapabilityState::Available
    },
    tls_mode: PostgresTlsMode::RustlsRequired,
};

/// Returns the runtime capability scaffold exposed by the native host.
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::runtime_capability_status`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_capability_status();
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_capability_status() -> &'static RuntimeScaffold {
    &RUNTIME_CAPABILITY_STATUS
}

/// Returns whether a CLI/runtime verb is supported by the native host.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::runtime::runtime_verb_supported`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::runtime_verb_supported`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_verb_supported(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_verb_supported(verb: &str) -> bool {
    matches!(
        verb,
        "build" | "status" | "verify" | "run" | "probe" | "smoke" | "doctor"
    )
}

/// Maps a runtime verb to its stable report identifier.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::runtime::runtime_report_id_for_verb`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::runtime_report_id_for_verb`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_report_id_for_verb(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_report_id_for_verb(verb: &str) -> &'static str {
    match verb {
        "build" | "verify" => "pharos-local-app-build-v1",
        "status" => "pharos-status-v1",
        "run" | "probe" | "smoke" => "pharos-local-app-runtime-v1",
        "doctor" => "pharos-doctor-v1",
        _ => "pharos-local-app-runtime-v1",
    }
}

/// Reads manifest JSON.
fn read_manifest_json(path: &Path) -> Result<Value, &'static str> {
    let text = stdfs::read_to_string(path).map_err(|_| "manifest missing")?;
    serde_json::from_str(&text).map_err(|_| "manifest invalid")
}

/// Reads source manifest value.
fn read_source_manifest_value(app_root: &Path) -> Result<Value, &'static str> {
    let yaml_path = app_root.join("pharos.app.yml");
    if yaml_path.exists() {
        let yaml_text = stdfs::read_to_string(&yaml_path).map_err(|_| "manifest missing")?;
        return declarative::yaml_compile_to_json(&yaml_text).ok_or("manifest invalid");
    }

    read_manifest_json(&app_root.join("pharos.app.json"))
}

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

/// Performs JSON runtime string.
fn json_runtime_string(value: &Value, key: &str) -> Option<String> {
    value
        .get("runtime")
        .and_then(Value::as_object)
        .and_then(|runtime| runtime.get(key))
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
}

/// Performs JSON artifact string.
fn json_artifact_string(value: &Value, key: &str) -> Option<String> {
    value
        .get("artifact")
        .and_then(Value::as_object)
        .and_then(|artifact| artifact.get(key))
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
}

/// Performs path last segment.
fn path_last_segment(path: &Path) -> Option<String> {
    pharos_runtime_core::stack::path_last_segment(path)
}

/// Performs runtime framework webhook endpoint ID.
fn runtime_framework_webhook_endpoint_id(path: &str) -> Option<String> {
    dynamic::framework_webhook_endpoint_id(path)
}

/// Performs runtime integration fixture path.
fn runtime_integration_fixture_path(app: &AppRuntime) -> Option<PathBuf> {
    let app_root = Path::new(app.app_root.as_deref()?.trim());
    if app_root.as_os_str().is_empty() {
        return None;
    }
    let manifest = read_manifest_json(&app_root.join("pharos.app.json")).ok()?;
    let relative = manifest
        .get("contracts")
        .and_then(Value::as_object)
        .and_then(|contracts| contracts.get("integration_contract"))
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())?;
    let path = Path::new(relative);
    Some(if path.is_absolute() {
        path.to_path_buf()
    } else {
        app_root.join(path)
    })
}

/// Performs runtime app declares framework webhook endpoint.
fn runtime_app_declares_framework_webhook_endpoint(app: &AppRuntime, endpoint_id: &str) -> bool {
    if endpoint_id.is_empty() || app.host_profile.as_deref() != Some("dynamic-app") {
        return false;
    }
    let Some(fixture_path) = runtime_integration_fixture_path(app) else {
        return false;
    };
    let Ok(text) = stdfs::read_to_string(fixture_path) else {
        return false;
    };
    let Ok(value) = serde_json::from_str::<Value>(&text) else {
        return false;
    };
    dynamic::find_webhook_endpoint(&value, endpoint_id).is_some()
}

/// Performs runtime framework webhook response.
fn runtime_framework_webhook_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    endpoint_id: &str,
) -> Vec<u8> {
    if request.method != "POST" {
        return http_text_response(405, "Method Not Allowed", "method not allowed\n");
    }
    let Some(payload) = dynamic::request_body_text(request)
        .filter(|body| body.len() <= 1_048_576 && serde_json::from_str::<Value>(body).is_ok())
    else {
        return http_json_response(
            400,
            "Bad Request",
            r#"{"error":"invalid JSON payload"}"#,
            &request.method,
        );
    };
    let Some(integration_root) = runtime_integration_fixture_path(app)
        .and_then(|path| stdfs::read_to_string(path).ok())
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
    else {
        return http_json_response(
            500,
            "Internal Server Error",
            r#"{"error":"integration contract unavailable"}"#,
            &request.method,
        );
    };
    let Some(endpoint) = dynamic::find_webhook_endpoint(&integration_root, endpoint_id) else {
        return http_text_response(404, "Not Found", "not found\n");
    };
    let verified = dynamic::webhook_request_signature_valid(endpoint, request, &payload);
    let persisted = if app_uses_file_backed_runtime_state(app) {
        app.state_path.as_deref().is_some_and(|state_path| {
            let state_path = Path::new(state_path);
            let Ok(_guard) = state_store::StateMutationGuard::acquire(state_path) else {
                return false;
            };
            dynamic::append_webhook_receipt(
                state_path,
                endpoint_id,
                if verified { "verified" } else { "rejected" },
                &payload,
            ) == 0
        })
    } else {
        (|| {
            let store = database::runtime_logical_app_store(app).ok()?;
            pharos_runtime_database::webhook::append_webhook_receipt(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                endpoint_id,
                verified,
                &payload,
            )
            .ok()
        })()
        .is_some()
    };
    if !persisted {
        return http_json_response(
            503,
            "Service Unavailable",
            r#"{"error":"receipt persistence unavailable"}"#,
            &request.method,
        );
    }
    if verified {
        http_json_response(202, "Accepted", r#"{"status":"accepted"}"#, &request.method)
    } else {
        http_json_response(
            401,
            "Unauthorized",
            r#"{"error":"signature verification failed"}"#,
            &request.method,
        )
    }
}

/// Performs infer repo root from app root.
fn infer_repo_root_from_app_root(app_root: &Path) -> Option<PathBuf> {
    let apps_dir = app_root.parent()?;
    if apps_dir.file_name().and_then(|value| value.to_str()) != Some("apps") {
        return None;
    }
    apps_dir.parent().map(Path::to_path_buf)
}

/// Resolves build dir for runtime loading.
fn resolve_build_dir_for_runtime_loading(
    app_root: &Path,
    build_dir: &str,
    repo_root: Option<&Path>,
) -> PathBuf {
    let path = Path::new(build_dir);
    if path.is_absolute() {
        return path.to_path_buf();
    }
    if let Some(repo_root) = repo_root {
        return repo_root.join(path);
    }
    if let Some(inferred_repo_root) = infer_repo_root_from_app_root(app_root) {
        return inferred_repo_root.join(path);
    }
    path.to_path_buf()
}

/// Loads one app runtime from a built artifact tree.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::load_app_runtime_from_artifact`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::load_app_runtime_from_artifact`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::load_app_runtime_from_artifact`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::load_app_runtime_from_artifact(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn load_app_runtime_from_artifact(artifact_dir: &Path) -> Result<AppRuntime, &'static str> {
    let manifest_path = artifact_dir.join("pharos.app.json");
    let manifest = read_manifest_json(&manifest_path)?;
    if manifest
        .get("artifact")
        .and_then(|value| value.get("ownership_manifest"))
        .and_then(Value::as_str)
        .is_some()
        && !verify_generated_ownership_manifest(artifact_dir)
    {
        return Err("generated artifact ownership verification failed");
    }
    let application_ir = match pharos_runtime_core::application_ir::compile_application_ir(
        artifact_dir,
        &manifest,
    ) {
        Ok(application_ir) => application_ir,
        Err(error) => {
            eprintln!("application contract compilation failed: {error:?}");
            return Err("invalid application contract");
        }
    };
    let mut app = AppRuntime {
        application_ir: Some(std::sync::Arc::new(application_ir)),
        artifact_dir: Some(artifact_dir.to_string_lossy().into_owned()),
        app_id: json_string(&manifest, "app_id"),
        app_root: Some(".".to_owned()),
        build_dir: artifact_dir
            .parent()
            .map(|path| path.to_string_lossy().into_owned()),
        host_profile: json_runtime_string(&manifest, "host_profile"),
        state_path: json_runtime_string(&manifest, "state_path"),
        base_path: json_runtime_string(&manifest, "base_path").or_else(|| Some(String::new())),
        log_path: json_runtime_string(&manifest, "log_path"),
        log_format: json_runtime_string(&manifest, "log_format")
            .or_else(|| Some("service".to_owned())),
        error_report_path: json_runtime_string(&manifest, "error_report_path")
            .or_else(|| Some(String::new())),
        log_level: json_runtime_string(&manifest, "log_level").or_else(|| Some("WARN".to_owned())),
        trusted_proxy_cidrs: json_runtime_string(&manifest, "trusted_proxy_cidrs"),
        ..AppRuntime::default()
    };

    if let Some(app_root) = app.app_root.as_deref()
        && !app_root.is_empty()
        && !Path::new(app_root).is_absolute()
    {
        app.app_root = Some(artifact_dir.join(app_root).to_string_lossy().into_owned());
    }

    if app.app_id.is_none()
        && let Some(app_root) = app.app_root.as_deref()
    {
        let app_manifest_path = Path::new(app_root).join("pharos.app.json");
        if let Ok(app_manifest) = read_manifest_json(&app_manifest_path) {
            app.app_id = json_string(&app_manifest, "app_id");
        }
    }

    if app.app_id.is_none() {
        app.app_id = path_last_segment(artifact_dir);
    }

    let host_profile = app
        .host_profile
        .as_deref()
        .filter(|value| !value.is_empty())
        .ok_or("missing host_profile")?;
    let app_id_present = app
        .app_id
        .as_deref()
        .filter(|value| !value.is_empty())
        .is_some();
    let build_dir_present = app
        .build_dir
        .as_deref()
        .filter(|value| !value.is_empty())
        .is_some();
    if !app_id_present || !build_dir_present {
        return Err("missing runtime identity");
    }
    if !matches!(host_profile, "static-pages" | "dynamic-app") {
        return Err("unsupported host_profile");
    }

    Ok(app)
}

/// Builds an inspection report for one app artifact tree.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::inspect_app_artifact_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::inspect_app_artifact_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::inspect_app_artifact_json`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::inspect_app_artifact_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::inspect_app_artifact_json(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn inspect_app_artifact_json(artifact_dir: &Path) -> Result<String, &'static str> {
    let app = load_app_runtime_from_artifact(artifact_dir)?;
    let ir = app
        .application_ir
        .as_ref()
        .ok_or("application IR missing")?;
    let routes = ir
        .routes
        .values()
        .map(|route| {
            serde_json::json!({
                "route_id": route.id.as_str(),
                "path": route.path,
                "kind": route.kind,
                "auth_gate": route.auth_gate,
                "policy_gate": route.policy_id.as_ref().map(|id| id.as_str()).unwrap_or_default(),
                "security": {
                    "csrf_mode": route.security.csrf_mode,
                    "trusted_origin_policy": route.security.trusted_origin_policy,
                    "tenant_scope": route.security.tenant_scope,
                    "rate_limit_policy": route.security.rate_limit_policy,
                    "capability_policy": route.security.capability_policy,
                },
                "source": {
                    "path": route.source.path,
                    "pointer": route.source.pointer,
                    "line": route.source.line,
                    "column": route.source.column,
                },
            })
        })
        .collect::<Vec<_>>();
    let actions = ir
        .actions
        .values()
        .map(|action| {
            serde_json::json!({
                "action_id": action.id.as_str(),
                "effects": {
                    "reads": action.effects.reads,
                    "writes": action.effects.writes,
                    "emits": action.effects.emits,
                    "enqueues": action.effects.enqueues,
                    "external_calls": action.effects.external_calls,
                    "cross_tenant": action.effects.cross_tenant,
                },
                "source": {
                    "path": action.source.path,
                    "pointer": action.source.pointer,
                    "line": action.source.line,
                    "column": action.source.column,
                },
            })
        })
        .collect::<Vec<_>>();
    serde_json::to_string_pretty(&serde_json::json!({
        "schema": "pharos.contract-inspection.v1",
        "application_ir_schema": ir.version,
        "contract_version": pharos_runtime_core::application_ir::CONTRACT_VERSION,
        "app_id": ir.app_id.as_str(),
        "contract_sha256": ir.contract_digest,
        "routes": routes,
        "actions": actions,
        "resource_budgets": {
            "max_response_bytes": app.resource_budgets.max_response_bytes,
            "max_query_result_bytes": app.resource_budgets.max_query_result_bytes,
            "max_report_bytes": app.resource_budgets.max_report_bytes,
            "max_state_section_items": app.resource_budgets.max_state_section_items,
            "max_workflow_effects": app.resource_budgets.max_workflow_effects,
            "max_jobs_per_poll": app.resource_budgets.max_jobs_per_poll,
        },
        "troubleshooting": {
            "contract": "inspect the source path and pointer reported for the failing declaration",
            "security": "compare the effective route security posture with the owning routes contract",
            "runtime": "inspect the effective resource budgets and app runtime configuration",
        },
    }))
    .map_err(|_| "inspection encode failed")
}

/// Builds a performance-oriented inspection report for one app artifact tree.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::runtime::inspect_app_performance_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::inspect_app_performance_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::inspect_app_performance_json`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::inspect_app_performance_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::inspect_app_performance_json(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn inspect_app_performance_json(artifact_dir: &Path) -> Result<String, &'static str> {
    const WARMUP_ITERATIONS: usize = 2_000;
    const SAMPLE_ITERATIONS: usize = 20_000;
    const SAMPLE_COUNT: usize = 5;
    const MAX_NANOSECONDS_PER_LOOKUP: u128 = 250_000;

    let app = load_app_runtime_from_artifact(artifact_dir)?;
    let routes = app
        .application_ir
        .as_ref()
        .map(|ir| {
            ir.routes
                .values()
                .map(|route| {
                    let method = if route.kind == "page" { "GET" } else { "POST" };
                    let path = route
                        .path
                        .split('/')
                        .map(|segment| {
                            if segment.starts_with(':')
                                || (segment.starts_with('{') && segment.ends_with('}'))
                            {
                                "benchmark"
                            } else {
                                segment
                            }
                        })
                        .collect::<Vec<_>>()
                        .join("/");
                    (method, path)
                })
                .collect::<Vec<_>>()
        })
        .filter(|routes| !routes.is_empty())
        .ok_or("performance inspection requires compiled routes")?;

    for index in 0..WARMUP_ITERATIONS {
        let (method, path) = &routes[index % routes.len()];
        std::hint::black_box(matched_app_route(&app, method, path));
    }

    let mut samples = Vec::with_capacity(SAMPLE_COUNT);
    let mut matched = 0usize;
    for sample in 0..SAMPLE_COUNT {
        let started = Instant::now();
        for index in 0..SAMPLE_ITERATIONS {
            let (method, path) = &routes[(sample * SAMPLE_ITERATIONS + index) % routes.len()];
            matched = matched.saturating_add(
                std::hint::black_box(matched_app_route(&app, method, path)).is_some() as usize,
            );
        }
        samples.push(started.elapsed().as_nanos());
    }
    if matched != SAMPLE_COUNT * SAMPLE_ITERATIONS {
        return Err("performance route corpus did not resolve");
    }
    let total_nanoseconds = samples.iter().copied().sum::<u128>();
    let lookup_count = (SAMPLE_COUNT * SAMPLE_ITERATIONS) as u128;
    let mean_nanoseconds = total_nanoseconds / lookup_count.max(1);
    let maximum_sample_nanoseconds = samples.iter().copied().max().unwrap_or(0);
    let maximum_sample_nanoseconds_per_lookup =
        maximum_sample_nanoseconds / SAMPLE_ITERATIONS as u128;
    if maximum_sample_nanoseconds_per_lookup > MAX_NANOSECONDS_PER_LOOKUP {
        return Err("route matching performance budget exceeded");
    }
    let throughput_per_second = lookup_count
        .saturating_mul(1_000_000_000)
        .checked_div(total_nanoseconds)
        .unwrap_or(u128::MAX);
    let configured_working_set_budget_bytes = app
        .resource_budgets
        .max_response_bytes
        .saturating_add(app.resource_budgets.max_query_result_bytes)
        .saturating_add(app.resource_budgets.max_report_bytes)
        .saturating_add(
            app.resource_budgets
                .max_state_section_items
                .saturating_mul(4_096),
        );
    serde_json::to_string_pretty(&serde_json::json!({
        "schema": "pharos.performance-evidence.v1",
        "status": "within_budget",
        "environment": {
            "os": std::env::consts::OS,
            "architecture": std::env::consts::ARCH,
        },
        "runtime_identity": runtime_build_identity_value(&app),
        "app_contract_sha256": app.application_ir.as_ref().map(|ir| ir.contract_digest.as_str()).unwrap_or_default(),
        "database_mode": "not_exercised_route_matcher",
        "warmup_iterations": WARMUP_ITERATIONS,
        "sample_count": SAMPLE_COUNT,
        "iterations_per_sample": SAMPLE_ITERATIONS,
        "sample_elapsed_nanoseconds": samples,
        "mean_nanoseconds_per_lookup": mean_nanoseconds,
        "maximum_sample_nanoseconds_per_lookup": maximum_sample_nanoseconds_per_lookup,
        "maximum_nanoseconds_per_lookup_budget": MAX_NANOSECONDS_PER_LOOKUP,
        "throughput_lookups_per_second": throughput_per_second,
        "configured_working_set_budget_bytes": configured_working_set_budget_bytes,
    }))
    .map_err(|_| "performance evidence encode failed")
}

/// Initializes missing file-backed runtime state from an app-owned declarative seed.
///
/// This runs after configuration finalization so packaged, source, single-app, and
/// shared-server loading all use the effective state path. Existing state is never
/// overwritten, including when multiple loaders race to initialize the same app.
fn initialize_missing_app_runtime_state(app: &AppRuntime) -> Result<(), &'static str> {
    const MAX_INITIAL_STATE_BYTES: u64 = 8 * 1024 * 1024;

    if app_uses_relational_runtime_authority(app) {
        return Ok(());
    }

    let artifact_dir = app
        .artifact_dir
        .as_deref()
        .filter(|value| !value.is_empty())
        .ok_or("missing artifact_dir")?;
    let seed_path = Path::new(artifact_dir).join("data/live/runtime-state.json");
    let seed_metadata = match stdfs::symlink_metadata(&seed_path) {
        Ok(metadata) => metadata,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
        Err(_) => return Err("runtime state seed metadata unreadable"),
    };
    if !seed_metadata.is_file()
        || seed_metadata.file_type().is_symlink()
        || seed_metadata.len() > MAX_INITIAL_STATE_BYTES
    {
        return Err("runtime state seed must be a bounded regular file");
    }
    let seed = stdfs::read(&seed_path).map_err(|_| "runtime state seed unreadable")?;
    let seed_root = serde_json::from_slice::<Value>(&seed)
        .map_err(|_| "runtime state seed must be valid JSON")?;
    if seed_root
        .as_object()
        .and_then(|object| object.get("schema"))
        .and_then(Value::as_str)
        .is_none_or(str::is_empty)
    {
        return Err("runtime state seed must declare a schema");
    }

    let state_path = app
        .state_path
        .as_deref()
        .filter(|value| !value.is_empty())
        .map(Path::new)
        .ok_or("runtime state seed requires state_path")?;
    if !state_path.is_absolute() {
        return Err("runtime state path must be absolute after finalization");
    }
    match stdfs::symlink_metadata(state_path) {
        Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => return Ok(()),
        Ok(_) => return Err("runtime state destination must be a regular file"),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
        Err(_) => return Err("runtime state destination metadata unreadable"),
    }

    let parent = state_path
        .parent()
        .filter(|path| !path.as_os_str().is_empty())
        .ok_or("runtime state destination parent missing")?;
    stdfs::create_dir_all(parent).map_err(|_| "runtime state destination parent unavailable")?;
    let parent_metadata = stdfs::symlink_metadata(parent)
        .map_err(|_| "runtime state destination parent metadata unreadable")?;
    if !parent_metadata.is_dir() || parent_metadata.file_type().is_symlink() {
        return Err("runtime state destination parent must be a directory");
    }

    let mut open_options = stdfs::OpenOptions::new();
    open_options.write(true).create_new(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        open_options.mode(0o640);
    }
    let mut state_file = match open_options.open(state_path) {
        Ok(file) => file,
        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
            let metadata = stdfs::symlink_metadata(state_path)
                .map_err(|_| "runtime state destination metadata unreadable")?;
            return if metadata.is_file() && !metadata.file_type().is_symlink() {
                Ok(())
            } else {
                Err("runtime state destination must be a regular file")
            };
        }
        Err(_) => return Err("runtime state destination could not be created"),
    };
    let initialization_result = (|| -> std::io::Result<()> {
        state_file.write_all(&seed)?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            stdfs::set_permissions(state_path, stdfs::Permissions::from_mode(0o640))?;
        }
        state_file.sync_all()
    })();
    if initialization_result.is_err() {
        drop(state_file);
        let _ = stdfs::remove_file(state_path);
        return Err("runtime state seed initialization failed");
    }
    Ok(())
}

/// Returns whether a packaged artifact root matches the expected app identity.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::packaged_artifact_root_matches`].
/// - `target_id`: Input consumed by [`crate::runtime::packaged_artifact_root_matches`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::packaged_artifact_root_matches`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::packaged_artifact_root_matches(std::path::Path::new("apps/dev_docs"), "dev_docs");
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn packaged_artifact_root_matches(app_root: &Path, target_id: &str) -> bool {
    if app_root.as_os_str().is_empty() || target_id.is_empty() {
        return false;
    }
    let manifest_path = app_root.join("pharos.app.json");
    let Ok(manifest) = read_manifest_json(&manifest_path) else {
        return false;
    };

    // A source app may carry the same artifact metadata in its manifest. The
    // app-owned config and launcher are the authoritative source-tree marker;
    // never treat that tree as an already-built artifact.
    if app_root.join("app.conf").is_file() && app_root.join("start.sh").is_file() {
        return false;
    }

    let is_artifact = json_string(&manifest, "app_id").as_deref() == Some(target_id)
        && json_runtime_string(&manifest, "build_artifact_dir").as_deref() == Some(".")
        && json_artifact_string(&manifest, "schema").as_deref() == Some("pharos.app.artifact.v1")
        && json_artifact_string(&manifest, "app_root").as_deref() == Some(".")
        && json_artifact_string(&manifest, "artifact_dir").as_deref() == Some(".");
    if is_artifact {
        return true;
    }

    false
}

/// Checks whether required runtime config files are present for an app.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::app_runtime_conf_required_present`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::app_runtime_conf_required_present`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::app_runtime_conf_required_present(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn app_runtime_conf_required_present(app_root: &Path) -> bool {
    config::app_local_conf_path(app_root).is_some()
}

fn app_uses_relational_runtime_authority(app: &AppRuntime) -> bool {
    if app.host_profile.as_deref() == Some("dynamic-app") {
        return true;
    }
    [app.app_root.as_deref(), app.artifact_dir.as_deref()]
        .into_iter()
        .flatten()
        .map(Path::new)
        .any(database::relational_runtime_authority_enabled)
}

fn app_uses_file_backed_runtime_state(app: &AppRuntime) -> bool {
    app.state_path
        .as_deref()
        .is_some_and(|value| !value.is_empty())
        && !app_uses_relational_runtime_authority(app)
}

fn append_optional_file_fingerprint(digest: &mut Sha256, path: Option<&Path>) {
    let Some(path) = path else {
        digest.update(b"missing");
        digest.update([0]);
        return;
    };
    digest.update(path.to_string_lossy().as_bytes());
    digest.update([0]);
    if let Some(fingerprint) = metadata_fingerprint_for_path(path) {
        digest.update(fingerprint.as_bytes());
    } else {
        digest.update(b"missing");
    }
    digest.update([0]);
}

/// Keys verification by the logical contract, configured data source, and adapter-owned ledger.
fn verify_app_migration_state_cache_key(
    app: &AppRuntime,
    app_root: &Path,
    runtime_conf: Option<&Path>,
) -> Option<String> {
    let app_id = app.app_id.as_deref()?;
    let contract_root = app
        .artifact_dir
        .as_deref()
        .map(Path::new)
        .unwrap_or(app_root);
    let contract = database::selected_logical_contract(contract_root, app_id).ok()??;
    let config = database::load_cli_backend_config(app_root, runtime_conf, Some(app_id))?;
    let adapter = database::operations::resolve(&config).ok()?;
    let ledger = adapter.migration_ledger(&config, app_id).ok()?;
    let source = serde_json::json!({
        "schema": "pharos.logical-migration-startup-cache.v2",
        "contract": contract,
        "ledger": ledger,
        "backend": config.backend,
        "host": config.host,
        "port": config.port,
        "database": config.database,
        "user": config.user,
        "local_path": config.sqlite_path,
        "socket_path": config.socket_path,
        "options": config.options,
    });
    let mut digest = Sha256::new();
    digest.update(serde_json::to_vec(&source).ok()?);
    append_optional_file_fingerprint(&mut digest, runtime_conf);
    append_optional_file_fingerprint(
        &mut digest,
        config::app_local_conf_path(app_root).as_deref(),
    );
    Some(
        digest
            .finalize()
            .iter()
            .map(|byte| format!("{byte:02x}"))
            .collect(),
    )
}

fn app_state_cache_sibling_path(app: &AppRuntime, suffix: &str) -> Option<PathBuf> {
    let state_path = app
        .state_path
        .as_deref()
        .filter(|value| !value.is_empty())
        .map(Path::new)?;
    let app_id = app
        .app_id
        .as_deref()
        .filter(|value| !value.is_empty())
        .unwrap_or("app");
    Some(
        state_path
            .parent()?
            .join(format!(".pharos-{app_id}-{suffix}.json")),
    )
}

fn migration_state_cache_path(app: &AppRuntime) -> Option<PathBuf> {
    app_state_cache_sibling_path(app, "migration-startup-cache")
}

fn cached_verified_migration_state(app: &AppRuntime, cache_key: &str) -> bool {
    let Some(path) = migration_state_cache_path(app) else {
        return false;
    };
    stdfs::read_to_string(path)
        .ok()
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
        .is_some_and(|root| {
            root.get("schema").and_then(Value::as_str) == Some("pharos.migration-startup-cache.v1")
                && root.get("status").and_then(Value::as_str) == Some("verified")
                && root.get("cache_key").and_then(Value::as_str) == Some(cache_key)
        })
}

fn write_verified_migration_state_cache(app: &AppRuntime, cache_key: &str) {
    let Some(path) = migration_state_cache_path(app) else {
        return;
    };
    let Some(parent) = path.parent() else {
        return;
    };
    if stdfs::create_dir_all(parent).is_err() {
        return;
    }
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|value| value.as_secs())
        .unwrap_or_default();
    let document = serde_json::json!({
        "schema": "pharos.migration-startup-cache.v1",
        "status": "verified",
        "cache_key": cache_key,
        "verified_at_unix": now,
    });
    if let Ok(encoded) = serde_json::to_vec_pretty(&document) {
        let _ = stdfs::write(path, encoded);
    }
}

/// Verifies the manifest-selected logical migration contract without exporting app data.
fn verify_app_migration_state(app: &AppRuntime) -> Result<(), &'static str> {
    let Some(app_root) = app.app_root.as_deref().map(Path::new) else {
        return Ok(());
    };
    if json_commands::manifest_database_contract_path(app_root).is_none() {
        return Ok(());
    }
    let runtime_conf = app.runtime_conf_path.as_deref().map(Path::new);
    let app_id = app
        .app_id
        .as_deref()
        .ok_or("database app identity unavailable")?;
    let contract_root = app
        .artifact_dir
        .as_deref()
        .map(Path::new)
        .unwrap_or(app_root);
    let contract = database::selected_logical_contract(contract_root, app_id)
        .map_err(|_| "logical database contract invalid")?
        .ok_or("logical database contract required")?;
    let config = database::load_cli_backend_config(app_root, runtime_conf, Some(app_id))
        .ok_or("database configuration unavailable")?;
    let adapter =
        database::operations::resolve(&config).map_err(|_| "database backend unavailable")?;
    let cache_key = verify_app_migration_state_cache_key(app, app_root, runtime_conf);
    if cache_key
        .as_deref()
        .is_some_and(|key| cached_verified_migration_state(app, key))
    {
        adapter
            .ready(&config, &contract.schema)
            .map_err(|_| "logical database schema unavailable")?;
        return Ok(());
    }
    adapter
        .verify_contract(&config, &contract)
        .map_err(|error| {
            eprintln!("logical database verification failed for {app_id}: {error:?}");
            "logical database contract verification failed"
        })?;
    if let Some(key) = cache_key.as_deref() {
        write_verified_migration_state_cache(app, key);
    }
    Ok(())
}

/// Loads one packaged artifact into an app runtime view.
///
/// # Parameters
///
/// - `config_record`: Parsed runtime configuration entry for the app being loaded.
/// - `artifact_root`: Built artifact directory that owns the packaged app files.
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::load_packaged_artifact`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::load_packaged_artifact`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::load_packaged_artifact(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn load_packaged_artifact(
    config_record: &ServeConfig,
    artifact_root: &Path,
) -> Result<(AppRuntime, String), &'static str> {
    pharos_runtime_core::stack::load_packaged_artifact_with_service(
        &RootRuntimeAppLoadService,
        config_record,
        artifact_root,
    )
}

/// Resolves the effective runtime build-directory override.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::runtime::runtime_build_dir_override`].
/// - `app_root`: Input consumed by [`crate::runtime::runtime_build_dir_override`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::runtime_build_dir_override`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_build_dir_override(todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_build_dir_override(config: &ServeConfig, app_root: &Path) -> Option<String> {
    if let Some(value) = config
        .build_dir
        .as_deref()
        .filter(|value| !value.is_empty())
    {
        return config::effective_app_build_dir(app_root, Some(value));
    }
    let repo_dist = app_root
        .parent()
        .filter(|parent| parent.file_name().and_then(|name| name.to_str()) == Some("apps"))
        .and_then(Path::parent)
        .map(|root| root.join("dist"));
    repo_dist
        .or_else(|| config::effective_app_build_dir(app_root, None).map(PathBuf::from))
        .map(|path| path.to_string_lossy().into_owned())
}

/// Prepares one app artifact tree for runtime loading.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::prepare_app_artifact`].
/// - `app_id`: Input consumed by [`crate::runtime::prepare_app_artifact`].
/// - `build_dir_override`: Input consumed by [`crate::runtime::prepare_app_artifact`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::prepare_app_artifact`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::prepare_app_artifact`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::prepare_app_artifact(std::path::Path::new("apps/dev_docs"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn prepare_app_artifact(
    app_root: &Path,
    app_id: &str,
    build_dir_override: Option<&str>,
) -> Result<String, i32> {
    if app_root.as_os_str().is_empty() || app_id.is_empty() {
        return Err(64);
    }
    if !config::app_local_conf_path(app_root).is_some() {
        return Err(66);
    }
    let build_dir = config::effective_app_build_dir(app_root, build_dir_override).ok_or(69)?;
    let artifact_dir =
        config::effective_app_artifact_dir(app_root, Path::new(&build_dir), app_id).ok_or(69)?;
    Path::new(&artifact_dir)
        .is_dir()
        .then_some(artifact_dir)
        .ok_or(66)
}

/// Reports whether runtime config is missing for one app.
///
/// # Parameters
///
/// - `config`: Input consumed by [`crate::runtime::log_runtime_app_config_missing`].
/// - `app_root`: Input consumed by [`crate::runtime::log_runtime_app_config_missing`].
/// - `app_id_hint`: Input consumed by [`crate::runtime::log_runtime_app_config_missing`].
///
/// # Returns
///
/// Returns after [`crate::runtime::log_runtime_app_config_missing`] applies its in-place effect.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::log_runtime_app_config_missing`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::log_runtime_app_config_missing(todo!(), std::path::Path::new("apps/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn log_runtime_app_config_missing(
    config: &ServeConfig,
    app_root: &Path,
    app_id_hint: Option<&str>,
) {
    let Some(log_path) = config.log_path.as_deref().filter(|value| !value.is_empty()) else {
        return;
    };
    let message = format!(
        "app configuration missing: app_id={} app_root={}\n",
        app_id_hint.unwrap_or("unknown"),
        app_root.display()
    );
    if message.len() > 4096 {
        return;
    }
    if let Some(parent) = Path::new(log_path).parent()
        && stdfs::create_dir_all(parent).is_err()
    {
        eprintln!(
            "runtime diagnostic log directory unavailable: {}",
            parent.display()
        );
        return;
    }
    let mut existing = stdfs::read_to_string(log_path).unwrap_or_default();
    if existing.len().saturating_add(message.len()) <= 64 * 1024 {
        existing.push_str(&message);
        if fs::write_binary_file(Path::new(log_path), existing.as_bytes(), 0o640).is_err() {
            eprintln!("runtime diagnostic log unavailable: {log_path}");
        }
    }
}

/// Loads runtime state for one directly targeted app.
///
/// # Parameters
///
/// - `config_record`: Input consumed by [`crate::runtime::load_app_runtime_for_single_app_direct`].
/// - `repo_root`: Input consumed by [`crate::runtime::load_app_runtime_for_single_app_direct`].
/// - `binary_dir`: Input consumed by [`crate::runtime::load_app_runtime_for_single_app_direct`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::load_app_runtime_for_single_app_direct`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::load_app_runtime_for_single_app_direct`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::load_app_runtime_for_single_app_direct(todo!(), std::path::Path::new("."), std::path::Path::new("bin"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn load_app_runtime_for_single_app_direct(
    config_record: &ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<AppRuntime, &'static str> {
    pharos_runtime_core::stack::load_app_runtime_for_single_app_direct_with_service(
        &RootRuntimeAppLoadService,
        config_record,
        repo_root,
        binary_dir,
    )
}

/// Resolves the directory that contains runtime apps.
///
/// # Parameters
///
/// - `conf_path`: Input consumed by [`crate::runtime::runtime_apps_dir`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::runtime_apps_dir`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_apps_dir(std::path::Path::new("app.conf"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_apps_dir(conf_path: Option<&Path>) -> Option<String> {
    let current_dir = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
    pharos_runtime_core::stack::runtime_apps_dir(conf_path, &current_dir)
}

/// Performs runtime loaded app context.
fn runtime_loaded_app_context(app: &AppRuntime) -> String {
    let mount = app.base_path.as_deref().unwrap_or_default();
    let context = mount.strip_prefix('/').unwrap_or(mount);
    if context.is_empty() {
        app.app_id.clone().unwrap_or_default()
    } else {
        context.to_owned()
    }
}

/// Builds the startup banner lines for the native runtime.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::runtime::runtime_log_banner_lines`].
/// - `config_record`: Input consumed by [`crate::runtime::runtime_log_banner_lines`].
/// - `load_ms`: Input consumed by [`crate::runtime::runtime_log_banner_lines`].
/// - `timestamp`: Input consumed by [`crate::runtime::runtime_log_banner_lines`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::runtime_log_banner_lines`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::runtime_log_banner_lines`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_log_banner_lines(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_log_banner_lines(
    stack: &RuntimeStack,
    config_record: &ServeConfig,
    load_ms: i64,
    timestamp: &str,
) -> Vec<String> {
    let loaded_apps = stack
        .apps
        .iter()
        .map(runtime_loaded_app_context)
        .filter(|context| !context.is_empty())
        .collect::<Vec<_>>()
        .join(",");
    let listening_on = config_record
        .socket_path
        .as_deref()
        .filter(|value| !value.is_empty())
        .or_else(|| {
            stack
                .socket_path
                .as_deref()
                .filter(|value| !value.is_empty())
        })
        .or_else(|| {
            config_record
                .host
                .as_deref()
                .filter(|value| !value.is_empty())
        })
        .or_else(|| stack.host.as_deref().filter(|value| !value.is_empty()))
        .unwrap_or("127.0.0.1");
    let contract_identities = stack
        .apps
        .iter()
        .map(|app| {
            format!(
                "{}:{}",
                app.app_id.as_deref().unwrap_or("app"),
                app.application_ir
                    .as_ref()
                    .map(|ir| ir.contract_digest.as_str())
                    .unwrap_or("unrecorded")
            )
        })
        .collect::<Vec<_>>()
        .join(",");

    let mut lines = vec![
        format!("{timestamp} INFO Pharos {PHAROS_RUNTIME_STACK_VERSION} threaded: true"),
        format!(
            "{timestamp} INFO build_identity source_revision={} cargo_lock_sha256={} app_contracts={contract_identities}",
            option_env!("PHAROS_SOURCE_REVISION").unwrap_or("unrecorded"),
            option_env!("PHAROS_CARGO_LOCK_SHA256").unwrap_or("unrecorded"),
        ),
        format!("{timestamp} INFO app_count: {}", stack.apps.len()),
        format!("{timestamp} INFO loaded_apps: {loaded_apps}"),
        format!("{timestamp} STATUS listening_on: {listening_on} started in: {load_ms}ms"),
    ];
    if !stack.failed_apps.is_empty() {
        let failed_apps = stack
            .failed_apps
            .iter()
            .map(|app| {
                format!(
                    "{}:{}",
                    if app.app_id.is_empty() {
                        app.app_root.as_str()
                    } else {
                        app.app_id.as_str()
                    },
                    app.error
                )
            })
            .collect::<Vec<_>>()
            .join(",");
        lines.push(format!(
            "{timestamp} WARN failed_app_count: {} quarantined_apps: {failed_apps}",
            stack.failed_apps.len()
        ));
    }
    lines
}

/// Performs runtime app summary value.
fn runtime_app_summary_value(app: &AppRuntime) -> Value {
    serde_json::json!({
        "app_id": app.app_id.clone().unwrap_or_default(),
        "mount_path": app.base_path.clone().unwrap_or_default(),
        "app_root": app.app_root.clone().unwrap_or_default(),
        "build_dir": app.build_dir.clone().unwrap_or_default(),
        "state_path": app.state_path.clone().unwrap_or_default(),
        "log_path": app.log_path.clone().unwrap_or_default(),
        "log_format": app.log_format.clone().unwrap_or_else(|| "service".to_owned()),
        "error_report_path": app.error_report_path.clone().unwrap_or_default(),
        "log_level": app.log_level.clone().unwrap_or_else(|| "WARN".to_owned()),
        "host_profile": app.host_profile.clone().unwrap_or_else(|| "dynamic-app".to_owned()),
        "runtime_conf_path": app.runtime_conf_path.clone().unwrap_or_default(),
        "backend": app_runtime_backend_summary_value(app),
        "runtime_identity": runtime_build_identity_value(app),
    })
}

/// Performs runtime failed app summary value.
fn runtime_failed_app_summary_value(app: &RuntimeAppLoadFailure) -> Value {
    serde_json::json!({
        "app_id": app.app_id,
        "mount_path": app.mount_path,
        "app_root": app.app_root,
        "artifact_dir": app.artifact_dir,
        "error": app.error,
    })
}

/// Returns a lowercase SHA-256 digest without an external encoder.
fn sha256_hex(bytes: &[u8]) -> String {
    pharos_runtime_core::support::sha256_hex(bytes)
}

/// Computes a secret-free fingerprint of effective runtime behavior.
fn runtime_config_fingerprint(app: &AppRuntime) -> String {
    let value = serde_json::json!({
        "app_id": app.app_id.as_deref().unwrap_or_default(),
        "mount": app.base_path.as_deref().unwrap_or_default(),
        "host_profile": app.host_profile.as_deref().unwrap_or_default(),
        "queue_enabled": app.queue_enabled,
        "queue_poll_interval_ms": app.queue_poll_interval_ms,
        "queue_max_attempts": app.queue_max_attempts,
        "queue_retry_seconds": app.queue_retry_seconds,
        "resource_budgets": {
            "max_response_bytes": app.resource_budgets.max_response_bytes,
            "max_query_result_bytes": app.resource_budgets.max_query_result_bytes,
            "max_report_bytes": app.resource_budgets.max_report_bytes,
            "max_state_section_items": app.resource_budgets.max_state_section_items,
            "max_workflow_effects": app.resource_budgets.max_workflow_effects,
            "max_jobs_per_poll": app.resource_budgets.max_jobs_per_poll,
            "integration_connect_timeout_ms": app.resource_budgets.integration_connect_timeout_ms,
            "integration_operation_timeout_ms": app.resource_budgets.integration_operation_timeout_ms,
            "integration_max_response_bytes": app.resource_budgets.integration_max_response_bytes,
        },
    });
    sha256_hex(value.to_string().as_bytes())
}

/// Joins binary, source, dependency, configuration, and app-contract identity.
fn runtime_build_identity_value(app: &AppRuntime) -> Value {
    serde_json::json!({
        "schema": "pharos.runtime-identity.v1",
        "runtime_version": env!("CARGO_PKG_VERSION"),
        "source_revision": option_env!("PHAROS_SOURCE_REVISION").unwrap_or("unrecorded"),
        "cargo_lock_sha256": option_env!("PHAROS_CARGO_LOCK_SHA256").unwrap_or("unrecorded"),
        "configuration_sha256": runtime_config_fingerprint(app),
        "application_ir_schema": pharos_runtime_core::application_ir::APPLICATION_IR_VERSION,
        "app_contract_sha256": app.application_ir.as_ref().map(|ir| ir.contract_digest.as_str()).unwrap_or("unrecorded"),
    })
}

/// Performs runtime default environment.
fn runtime_default_environment(app: &AppRuntime) -> String {
    let Some(app_root) = app.app_root.as_deref().filter(|value| !value.is_empty()) else {
        return "development".to_owned();
    };
    cache::dynamic_config_allowlist_value(
        Path::new(app_root),
        app.runtime_conf_path.as_deref().map(Path::new),
        "environment",
    )
    .filter(|value| !value.is_empty())
    .unwrap_or_else(|| "development".to_owned())
}

/// Warms the bounded allowlisted configuration cache for one mounted app request.
fn warm_runtime_config_allowlist(app: &AppRuntime) {
    let Some(app_root) = app.app_root.as_deref().filter(|value| !value.is_empty()) else {
        return;
    };
    let app_root = Path::new(app_root);
    let runtime_conf = app.runtime_conf_path.as_deref().map(Path::new);
    for key in ["environment", "base_path", "base_url"] {
        let _ = cache::dynamic_config_allowlist_value(app_root, runtime_conf, key);
    }
}

/// Performs runtime default backend.
fn runtime_default_backend(app: &AppRuntime) -> String {
    let Some(app_root) = app.app_root.as_deref().filter(|value| !value.is_empty()) else {
        return "sqlite".to_owned();
    };
    cache::dynamic_config_allowlist_value(
        Path::new(app_root),
        app.runtime_conf_path.as_deref().map(Path::new),
        "db_backend",
    )
    .filter(|value| !value.is_empty())
    .unwrap_or_else(|| "sqlite".to_owned())
}

/// Builds a backend summary for one loaded app runtime.
pub(super) fn app_runtime_backend_summary_value(app: &AppRuntime) -> Value {
    let Some(_) = app.app_root.as_deref().filter(|value| !value.is_empty()) else {
        return serde_json::json!({
            "db_backend": "",
            "db_ready": false,
        });
    };
    let backend = runtime_default_backend(app);
    let ready = database::runtime_database_ready(app).unwrap_or(false);
    serde_json::json!({
        "db_backend": backend,
        "db_ready": ready,
    })
}

/// Performs environment valid.
fn environment_valid(environment: &str) -> bool {
    matches!(
        environment,
        "development" | "staging" | "production" | "test"
    )
}

/// Performs output path check.
fn output_path_check(path: Option<&str>, field: &str, allow_not_configured: bool) -> Value {
    let status = match path {
        Some("") | None if allow_not_configured => "not_configured",
        Some("") | None => "missing",
        Some(path) => {
            let parent_exists = Path::new(path)
                .parent()
                .is_some_and(|parent| parent.exists() || parent.as_os_str().is_empty());
            if parent_exists {
                "ok"
            } else {
                "missing_parent_dir"
            }
        }
    };
    serde_json::json!({
        "field": field,
        "path": path.unwrap_or_default(),
        "status": status,
    })
}

/// Performs database check JSON.
fn db_check_json(app: &AppRuntime, backend: &str) -> Value {
    let backend_config = app
        .app_root
        .as_deref()
        .filter(|value| !value.is_empty())
        .and_then(|app_root| {
            database::load_cli_backend_config(
                Path::new(app_root),
                app.runtime_conf_path.as_deref().map(Path::new),
                app.app_id.as_deref(),
            )
        });
    let db_path = backend_config
        .as_ref()
        .and_then(|config| config.sqlite_path.as_ref())
        .map(|path| path.to_string_lossy().into_owned())
        .unwrap_or_default();
    let status = match backend_config.as_ref() {
        Some(config)
            if config.backend == backend && database::operations::resolve(config).is_ok() =>
        {
            match config.sqlite_path.as_deref() {
                Some(path) if path.as_os_str().is_empty() => "incomplete",
                Some(path)
                    if path.parent().is_none_or(|parent| {
                        !parent.exists() && !parent.as_os_str().is_empty()
                    }) =>
                {
                    "missing_parent_dir"
                }
                _ => "ok",
            }
        }
        _ => "invalid",
    };
    serde_json::json!({
        "backend": backend,
        "db_path": db_path,
        "status": status,
    })
}

/// Builds app config report local JSON.
fn build_app_config_report_local_json(app: &AppRuntime) -> Value {
    let environment = runtime_default_environment(app);
    let backend = runtime_default_backend(app);
    let db_checks = db_check_json(app, &backend);
    let log_check = output_path_check(app.log_path.as_deref(), "app_log_path", false);
    let error_check = output_path_check(
        app.error_report_path.as_deref(),
        "app_error_report_path",
        true,
    );
    let db_ok = db_checks
        .get("status")
        .and_then(Value::as_str)
        .is_some_and(|status| status == "ok");
    let log_ok = log_check
        .get("status")
        .and_then(Value::as_str)
        .is_some_and(|status| status == "ok");
    let error_ok = error_check
        .get("status")
        .and_then(Value::as_str)
        .is_some_and(|status| matches!(status, "ok" | "not_configured"));
    let status = if environment_valid(&environment) && db_ok && log_ok && error_ok {
        "ok"
    } else {
        "invalid"
    };

    serde_json::json!({
        "environment": environment,
        "backend": backend,
        "environment_valid": environment_valid(&runtime_default_environment(app)),
        "log_path": app.log_path.clone().unwrap_or_default(),
        "error_report_path": app.error_report_path.clone().unwrap_or_default(),
        "queue_enabled": app.queue_enabled,
        "queue_poll_interval_ms": app.queue_poll_interval_ms,
        "queue_max_attempts": app.queue_max_attempts,
        "queue_retry_seconds": app.queue_retry_seconds,
        "required_env_refs": [],
        "secret_env_refs": [],
        "required_env_checks": [],
        "secret_env_checks": [],
        "db_checks": db_checks,
        "log_checks": [log_check, error_check],
        "issues": [],
        "status": status,
    })
}

/// Builds app doctor report JSON.
fn build_app_doctor_report_json(
    artifact_dir: &str,
    app: &AppRuntime,
) -> Result<String, &'static str> {
    let config_report = build_app_config_report_local_json(app);
    let build_verify_report = serde_json::from_str::<Value>(&app_runtime_report_json(
        "pharos-local-app-build-v1",
        "verify",
        artifact_dir,
        app,
    )?)
    .map_err(|_| "report encode failed")?;
    let backend = runtime_default_backend(app);
    let migrate_ready = verify_app_migration_state(app).is_ok()
        && database::runtime_database_ready(app).unwrap_or(false);
    let migrate_verify_status = if migrate_ready {
        "verified"
    } else {
        "verification_failed"
    };
    let migrate_verify_error = if migrate_ready {
        Value::Null
    } else {
        Value::String("database readiness verification failed".to_owned())
    };
    let overall_status = if config_report
        .get("status")
        .and_then(Value::as_str)
        .is_some_and(|status| status == "ok")
        && migrate_verify_status == "verified"
    {
        "ok"
    } else {
        "needs_attention"
    };

    let report = serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-doctor-v1",
        "target_kind": "app",
        "target_id": app.app_id.clone().unwrap_or_default(),
        "backend": backend,
        "status": overall_status,
        "runtime_summary": runtime_app_summary_value(app),
        "config": config_report,
        "migrate_verify_status": migrate_verify_status,
        "build_verify_status": "ok",
        "migrate_verify_error": migrate_verify_error,
        "build_verify_error": Value::Null,
        "migrate_verify_report": Value::Null,
        "build_verify_report": build_verify_report,
    }))
    .map_err(|_| "report encode failed")?;
    (report.len() <= app.resource_budgets.max_report_bytes)
        .then_some(report)
        .ok_or("report resource budget exceeded")
}

/// Writes report file.
fn write_report_file(path: &Path, content: &str) -> Result<(), &'static str> {
    if let Some(parent) = path.parent() {
        stdfs::create_dir_all(parent).map_err(|_| "report write failed")?;
    }
    fs::write_binary_file(path, content.as_bytes(), 0o640).map_err(|_| "report write failed")
}

/// Performs website report path.
fn website_report_path(build_dir: &Path, verb: &str, target_id: &str) -> PathBuf {
    build_dir
        .join("reports")
        .join(format!("{verb}-website-{target_id}.json"))
}

/// Performs path has runtime component.
fn path_has_runtime_component(path: &Path) -> bool {
    path.components()
        .any(|component| component.as_os_str() == "runtime")
}

/// Performs runtime fingerprint target.
fn runtime_fingerprint_target(path: &Path) -> bool {
    path.file_name()
        .and_then(|value| value.to_str())
        .is_some_and(|name| matches!(name, "pharos.app.json" | "app.conf"))
        || path_has_runtime_component(path)
}

/// Collects runtime fingerprint files.
fn collect_runtime_fingerprint_files(
    root: &Path,
    depth: usize,
    max_depth: usize,
    files: &mut Vec<PathBuf>,
) -> Result<(), &'static str> {
    let directory = match stdfs::read_dir(root) {
        Ok(directory) => directory,
        Err(_) => return Ok(()),
    };
    for entry in directory.flatten() {
        let path = entry.path();
        if path.is_dir() {
            if depth < max_depth {
                collect_runtime_fingerprint_files(&path, depth + 1, max_depth, files)?;
            }
        } else if runtime_fingerprint_target(&path) {
            files.push(path);
        }
    }
    Ok(())
}

/// Builds a stable fingerprint for the currently loaded runtime apps.
///
/// # Parameters
///
/// - `apps_dir`: Input consumed by [`crate::runtime::runtime_apps_fingerprint`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_apps_fingerprint`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_apps_fingerprint`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::runtime_apps_fingerprint`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_apps_fingerprint(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_apps_fingerprint(apps_dir: &Path) -> Result<Option<String>, &'static str> {
    if apps_dir.as_os_str().is_empty() {
        return Ok(None);
    }
    let mut files = Vec::new();
    collect_runtime_fingerprint_files(apps_dir, 0, 2, &mut files)?;
    if files.is_empty() {
        return Ok(None);
    }
    files.sort();
    let mut hasher = Sha256::new();
    for path in files {
        let content = stdfs::read_to_string(&path).map_err(|_| "apps_dir unreadable")?;
        hasher.update(content.as_bytes());
    }
    let digest = hasher.finalize();
    let hex = digest
        .iter()
        .map(|byte| format!("{byte:02x}"))
        .collect::<String>();
    Ok(Some(hex))
}

/// Returns whether the runtime stack should be reloaded.
///
/// # Parameters
///
/// - `apps_dir`: Input consumed by [`crate::runtime::runtime_stack_refresh_required`].
/// - `previous_fingerprint`: Input consumed by [`crate::runtime::runtime_stack_refresh_required`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::runtime_stack_refresh_required`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::runtime_stack_refresh_required`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_stack_refresh_required(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_stack_refresh_required(
    apps_dir: &Path,
    previous_fingerprint: Option<&str>,
) -> Result<bool, &'static str> {
    let Some(next_fingerprint) = runtime_apps_fingerprint(apps_dir)? else {
        return Ok(false);
    };
    Ok(previous_fingerprint.is_none_or(|previous| previous != next_fingerprint))
}

/// Normalizes dynamic route parameters for deterministic collision comparison.
/// Joins an application mount and route path into one owned HTTP namespace.
fn mounted_route_pattern(mount: &str, route: &str) -> String {
    pharos_runtime_core::route::mounted_route_pattern(mount, route)
}

/// Rejects duplicate ownership claims before the runtime binds a listener.
fn validate_runtime_stack_ownership(apps: &[AppRuntime]) -> Result<(), &'static str> {
    let mut identifiers = BTreeMap::new();
    let mut owned_paths: Vec<(PathBuf, &str)> = Vec::new();
    let mut routes = BTreeMap::new();
    let mut mounts: Vec<(&str, &str)> = Vec::new();
    for app in apps {
        let app_id = app.app_id.as_deref().ok_or("runtime app id missing")?;
        if identifiers.insert(app_id, app_id).is_some() {
            return Err("runtime app id collision");
        }
        let mount = app.base_path.as_deref().unwrap_or_default();
        for (other_mount, _) in &mounts {
            let first = mount.trim_end_matches('/');
            let second = other_mount.trim_end_matches('/');
            if first == second
                || (!second.is_empty()
                    && first
                        .strip_prefix(second)
                        .is_some_and(|tail| tail.starts_with('/')))
                || (!first.is_empty()
                    && second
                        .strip_prefix(first)
                        .is_some_and(|tail| tail.starts_with('/')))
            {
                return Err("runtime base path collision");
            }
        }
        mounts.push((mount, app_id));
        let db_path = app
            .app_root
            .as_deref()
            .map(|app_root| {
                database::app_local_database_artifact_path(
                    Path::new(app_root),
                    app.runtime_conf_path.as_deref().map(Path::new),
                    app_id,
                )
            })
            .transpose()
            .map_err(|_| "runtime database artifact ownership unavailable")?
            .flatten();
        for candidate in [
            app.artifact_dir.as_deref(),
            app.state_path.as_deref(),
            app.log_path.as_deref(),
        ]
        .into_iter()
        .flatten()
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
        .chain(db_path)
        {
            for (owned, owner) in &owned_paths {
                if owner != &app_id
                    && (candidate == *owned
                        || candidate.starts_with(owned)
                        || owned.starts_with(&candidate))
                {
                    return Err("runtime filesystem ownership collision");
                }
            }
            owned_paths.push((candidate, app_id));
        }
        let application_ir = app
            .application_ir
            .as_ref()
            .ok_or("runtime application IR missing")?;
        for route in application_ir.routes.values() {
            let pattern = mounted_route_pattern(mount, &route.path);
            let key = format!("{} {pattern}", route.kind);
            if routes.insert(key, app_id).is_some() {
                return Err("runtime route ownership collision");
            }
        }
    }
    Ok(())
}

fn startup_timing_enabled() -> bool {
    std::env::var("PHAROS_STARTUP_TIMING").ok().as_deref() == Some("1")
}

fn log_startup_app_timing(
    app_id: &str,
    artifact_dir: &Path,
    load_ms: u128,
    finalize_ms: u128,
    state_ms: u128,
    verify_ms: u128,
    total_ms: u128,
) {
    if startup_timing_enabled() {
        eprintln!(
            "startup_timing app={} artifact={} load_ms={} finalize_ms={} state_ms={} verify_ms={} total_ms={}",
            app_id,
            artifact_dir.display(),
            load_ms,
            finalize_ms,
            state_ms,
            verify_ms,
            total_ms
        );
    }
}

#[derive(Clone, Copy)]
struct RootRuntimeAppLoadService;

impl pharos_runtime_core::stack::RuntimeAppLoadService for RootRuntimeAppLoadService {
    fn read_source_manifest_value(&self, app_root: &Path) -> Result<Value, &'static str> {
        read_source_manifest_value(app_root)
    }

    fn packaged_artifact_root_matches(&self, app_root: &Path, target_id: &str) -> bool {
        packaged_artifact_root_matches(app_root, target_id)
    }

    fn app_runtime_conf_required_present(&self, app_root: &Path) -> bool {
        app_runtime_conf_required_present(app_root)
    }

    fn resolve_build_dir_for_runtime_loading(
        &self,
        app_root: &Path,
        build_dir: &str,
        repo_root: Option<&Path>,
    ) -> PathBuf {
        resolve_build_dir_for_runtime_loading(app_root, build_dir, repo_root)
    }

    fn load_app_runtime_from_artifact(
        &self,
        artifact_dir: &Path,
    ) -> Result<AppRuntime, &'static str> {
        load_app_runtime_from_artifact(artifact_dir)
    }

    fn initialize_missing_app_runtime_state(&self, app: &AppRuntime) -> Result<(), &'static str> {
        initialize_missing_app_runtime_state(app)
    }

    fn verify_app_migration_state(&self, app: &AppRuntime) -> Result<(), &'static str> {
        verify_app_migration_state(app)
    }

    fn log_startup_app_timing(&self, timing: pharos_runtime_core::stack::RuntimeAppStartupTiming) {
        log_startup_app_timing(
            &timing.app_id,
            &timing.artifact_dir,
            timing.load_ms,
            timing.finalize_ms,
            timing.state_ms,
            timing.verify_ms,
            timing.total_ms,
        );
    }
}

/// Loads the complete runtime stack from the current runtime root.
///
/// # Parameters
///
/// - `config_record`: Input consumed by [`crate::runtime::load_runtime_stack_direct`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::load_runtime_stack_direct`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::load_runtime_stack_direct`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::load_runtime_stack_direct`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::load_runtime_stack_direct(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn load_runtime_stack_direct(
    config_record: &ServeConfig,
) -> Result<RuntimeStack, &'static str> {
    let current_dir = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
    let load_config =
        pharos_runtime_core::stack::resolve_runtime_stack_load_config(config_record, &current_dir)?;
    pharos_runtime_core::stack::load_runtime_stack_from_apps_dir_with_service(
        &load_config.apps_dir_path,
        load_config.host,
        load_config.port,
        load_config.socket_path,
        load_config.effective_config,
        RootRuntimeAppLoadService,
        validate_runtime_stack_ownership,
    )
}

/// Performs app runtime report JSON.
fn app_runtime_report_json(
    report_id: &str,
    verb: &str,
    artifact_dir: &str,
    app: &AppRuntime,
) -> Result<String, &'static str> {
    let summary = runtime_app_summary_value(app);
    let mut payload = serde_json::Map::new();
    payload.insert("report_id".to_owned(), Value::String(report_id.to_owned()));
    payload.insert("verb".to_owned(), Value::String(verb.to_owned()));
    payload.insert("target_kind".to_owned(), Value::String("app".to_owned()));
    payload.insert(
        "target_id".to_owned(),
        Value::String(app.app_id.clone().unwrap_or_else(|| "app".to_owned())),
    );
    payload.insert(
        "status".to_owned(),
        Value::String(if verb == "build" { "built" } else { "ok" }.to_owned()),
    );
    payload.insert(
        "artifact_dir".to_owned(),
        Value::String(artifact_dir.to_owned()),
    );
    payload.insert(
        "state_path".to_owned(),
        Value::String(app.state_path.clone().unwrap_or_default()),
    );
    payload.insert(
        "base_path".to_owned(),
        Value::String(app.base_path.clone().unwrap_or_default()),
    );
    payload.insert(
        "log_path".to_owned(),
        Value::String(app.log_path.clone().unwrap_or_default()),
    );
    payload.insert(
        "log_format".to_owned(),
        Value::String(
            app.log_format
                .clone()
                .unwrap_or_else(|| "service".to_owned()),
        ),
    );
    payload.insert(
        "error_report_path".to_owned(),
        Value::String(app.error_report_path.clone().unwrap_or_default()),
    );
    payload.insert(
        "log_level".to_owned(),
        Value::String(app.log_level.clone().unwrap_or_else(|| "WARN".to_owned())),
    );
    payload.insert(
        "host_profile".to_owned(),
        Value::String(app.host_profile.clone().unwrap_or_default()),
    );
    payload.insert(
        "runtime_conf_path".to_owned(),
        Value::String(app.runtime_conf_path.clone().unwrap_or_default()),
    );
    payload.insert(
        "runtime_launcher".to_owned(),
        Value::Bool(matches!(verb, "run" | "probe" | "smoke")),
    );
    payload.insert(
        "host_target".to_owned(),
        Value::String("native-host-target".to_owned()),
    );
    payload.insert(
        "host_mode".to_owned(),
        Value::String("native-host-target".to_owned()),
    );
    payload.insert(
        "generated_by".to_owned(),
        Value::String("pharos-native-runtime".to_owned()),
    );
    payload.insert("runtime_summary".to_owned(), summary);
    let report =
        serde_json::to_string(&Value::Object(payload)).map_err(|_| "report encode failed")?;
    (report.len() <= app.resource_budgets.max_report_bytes)
        .then_some(report)
        .ok_or("report resource budget exceeded")
}

/// Builds the JSON report returned by runtime build flows.
///
/// # Parameters
///
/// - `target_id`: Input consumed by [`crate::runtime::build_runtime_build_report_json`].
/// - `conf_path`: Input consumed by [`crate::runtime::build_runtime_build_report_json`].
/// - `apps_dir`: Input consumed by [`crate::runtime::build_runtime_build_report_json`].
/// - `app_count`: Input consumed by [`crate::runtime::build_runtime_build_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::build_runtime_build_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::build_runtime_build_report_json`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::build_runtime_build_report_json("dev_docs", std::path::Path::new("app.conf"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn build_runtime_build_report_json(
    target_id: &str,
    conf_path: Option<&str>,
    apps_dir: &str,
    app_count: usize,
) -> Result<String, &'static str> {
    serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-runtime-build-v1",
        "target_kind": "runtime",
        "target_id": target_id,
        "status": "built",
        "app_count": app_count,
        "config_path": conf_path.unwrap_or_default(),
        "apps_dir": apps_dir,
    }))
    .map_err(|_| "report encode failed")
}

/// Finds the mounted app that matches a request path.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::runtime::runtime_match_app`].
/// - `path`: Input consumed by [`crate::runtime::runtime_match_app`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::runtime_match_app`] 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::runtime_match_app`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_match_app(todo!(), std::path::Path::new("fixture.json"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
struct RootRuntimeRequestService;

impl pharos_runtime_core::request::RuntimeRequestService for RootRuntimeRequestService {
    fn route_match_lookup(&self, target: &str) -> Option<String> {
        cache::route_match_lookup(target)
    }

    fn route_match_store(&self, target: &str, app_id: &str) {
        cache::route_match_store(target, app_id);
    }

    fn framework_webhook_endpoint_id(&self, target: &str) -> Option<String> {
        runtime_framework_webhook_endpoint_id(target)
    }

    fn app_declares_framework_webhook_endpoint(&self, app: &AppRuntime, endpoint_id: &str) -> bool {
        runtime_app_declares_framework_webhook_endpoint(app, endpoint_id)
    }
}

pub fn runtime_match_app<'a>(stack: &'a RuntimeStack, path: &str) -> Option<&'a AppRuntime> {
    pharos_runtime_core::request::runtime_match_app(stack, path, &RootRuntimeRequestService)
}

/// Performs runtime match failed app.
fn runtime_match_failed_app<'a>(
    stack: &'a RuntimeStack,
    path: &str,
) -> Option<&'a RuntimeAppLoadFailure> {
    pharos_runtime_core::route::matched_failed_app(stack, |candidates| {
        pharos_runtime_core::best_mount_index(path, candidates)
    })
}

/// Performs runtime failed app response.
fn runtime_failed_app_response(app: &RuntimeAppLoadFailure, method: &str) -> Vec<u8> {
    http_json_response(
        503,
        "Service Unavailable",
        &serde_json::json!({
            "schema": "pharos.error.v1",
            "error": {
                "code": "dependency_unavailable",
                "message": "app bundle unavailable",
                "retryable": true,
                "correlation_id": "",
                "details": {
                    "app_id": app.app_id,
                    "mount_path": app.mount_path,
                    "app_root": app.app_root,
                    "artifact_dir": app.artifact_dir,
                    "reason": app.error,
                }
            }
        })
        .to_string(),
        method,
    )
}

/// Runs a readiness probe against one loaded app runtime.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::app_runtime_probe_ready`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::app_runtime_probe_ready`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::app_runtime_probe_ready(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn app_runtime_probe_ready(app: &AppRuntime) -> bool {
    pharos_runtime_core::readiness::app_runtime_probe_ready(
        app,
        app_uses_relational_runtime_authority(app),
    )
}

/// Runs a readiness probe across the loaded runtime stack.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::runtime::runtime_stack_probe_ready`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::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::runtime::runtime_stack_probe_ready`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::runtime_stack_probe_ready(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn runtime_stack_probe_ready(stack: &RuntimeStack) -> bool {
    pharos_runtime_core::readiness::runtime_stack_probe_ready(
        stack.apps.iter(),
        stack.failed_apps.len(),
        app_runtime_probe_ready,
    )
}

/// Builds the response for a framework-owned route.
///
/// # Parameters
///
/// - `method`: Input consumed by [`crate::runtime::framework_builtin_response`].
/// - `target`: Input consumed by [`crate::runtime::framework_builtin_response`].
/// - `app`: Input consumed by [`crate::runtime::framework_builtin_response`].
/// - `stack`: Input consumed by [`crate::runtime::framework_builtin_response`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::framework_builtin_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::framework_builtin_response`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::framework_builtin_response(todo!(), "/", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn framework_builtin_response(
    method: &str,
    target: &str,
    app: Option<&AppRuntime>,
    stack: Option<&RuntimeStack>,
) -> Option<FrameworkBuiltinResponse> {
    pharos_runtime_core::builtin::framework_builtin_response(
        method,
        target,
        app,
        stack,
        PHAROS_VERSION,
        PHAROS_TARGET_ID,
        app_runtime_probe_ready,
        runtime_stack_probe_ready,
    )
}

/// Performs HTTP status line.
fn http_status_line(status_code: u16, status_text: &str) -> String {
    format!("HTTP/1.1 {status_code} {status_text}\r\n")
}

fn http_reason_phrase(status_code: u16) -> &'static str {
    match status_code {
        200 => "OK",
        201 => "Created",
        202 => "Accepted",
        204 => "No Content",
        302 => "Found",
        303 => "See Other",
        400 => "Bad Request",
        401 => "Unauthorized",
        403 => "Forbidden",
        404 => "Not Found",
        405 => "Method Not Allowed",
        409 => "Conflict",
        413 => "Payload Too Large",
        422 => "Unprocessable Entity",
        424 => "Failed Dependency",
        429 => "Too Many Requests",
        500 => "Internal Server Error",
        502 => "Bad Gateway",
        503 => "Service Unavailable",
        504 => "Gateway Timeout",
        _ => "Internal Server Error",
    }
}

/// Performs HTTP text response.
fn http_text_response(status_code: u16, status_text: &str, body: &str) -> Vec<u8> {
    if status_code >= 400 {
        let code = pharos_runtime_core::error::ErrorCode::from_http_status(status_code);
        let envelope = pharos_runtime_core::error::envelope(code, body.trim(), None).to_string();
        return http_json_response(status_code, status_text, &envelope, "GET");
    }
    let mut response = String::new();
    response.push_str(&http_status_line(status_code, status_text));
    response.push_str("Content-Type: text/plain; charset=utf-8\r\n");
    response.push_str(&format!("Content-Length: {}\r\n", body.len()));
    response.push_str("Connection: close\r\n\r\n");
    response.push_str(body);
    response.into_bytes()
}

/// Extracts bounded public validation context without copying arbitrary failure payload fields.
fn public_http_validation_details(parsed: &Value) -> Option<Value> {
    if parsed.get("schema").and_then(Value::as_str) != Some("pharos.validation.report.v1") {
        return None;
    }
    let errors = parsed
        .get("errors")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter_map(Value::as_str)
        .take(32)
        .map(|error| error.chars().take(128).collect::<String>())
        .map(Value::String)
        .collect::<Vec<_>>();
    let mut details = serde_json::Map::from_iter([(
        "schema".to_owned(),
        Value::String("pharos.validation.report.v1".to_owned()),
    )]);
    if !errors.is_empty() {
        details.insert("errors".to_owned(), Value::Array(errors));
    }
    for array_name in ["field_errors", "form_errors"] {
        if let Some(entries) = parsed.get(array_name).and_then(Value::as_array) {
            let filtered = entries
                .iter()
                .filter_map(Value::as_object)
                .take(16)
                .map(|entry| {
                    let mut filtered = serde_json::Map::new();
                    for key in ["field_id", "rule_id", "code", "message"] {
                        if let Some(value) = entry
                            .get(key)
                            .and_then(Value::as_str)
                            .filter(|value| value.len() <= 256)
                        {
                            filtered.insert(key.to_owned(), Value::String(value.to_owned()));
                        }
                    }
                    Value::Object(filtered)
                })
                .collect::<Vec<_>>();
            if !filtered.is_empty() {
                details.insert(array_name.to_owned(), Value::Array(filtered));
            }
        }
    }
    for key in ["action_id", "report_id", "surface_id", "form_id"] {
        if let Some(value) = parsed
            .get(key)
            .and_then(Value::as_str)
            .filter(|value| value.len() <= 128)
        {
            details.insert(key.to_owned(), Value::String(value.to_owned()));
        }
    }
    Some(Value::Object(details))
}

/// Returns a bounded validation report for one route-level request admission failure.
fn route_request_validation_report(route: &Value, code: &str, message: &str) -> String {
    let mut root = serde_json::Map::new();
    root.insert(
        "schema".to_owned(),
        Value::String("pharos.validation.report.v1".to_owned()),
    );
    root.insert(
        "report_id".to_owned(),
        Value::String("pharos.validation.report.v1".to_owned()),
    );
    if let Some(action_id) = route.get("action_id").and_then(Value::as_str) {
        root.insert("action_id".to_owned(), Value::String(action_id.to_owned()));
    }
    root.insert(
        "errors".to_owned(),
        Value::Array(vec![Value::String(code.to_owned())]),
    );
    root.insert(
        "form_errors".to_owned(),
        Value::Array(vec![Value::Object(serde_json::Map::from_iter([
            ("rule_id".to_owned(), Value::String(code.to_owned())),
            ("code".to_owned(), Value::String(code.to_owned())),
            ("message".to_owned(), Value::String(message.to_owned())),
        ]))]),
    );
    root.insert("field_errors".to_owned(), Value::Array(Vec::new()));
    Value::Object(root).to_string()
}

/// Enforces narrow route-level request admission hooks before action execution.
fn route_request_hook_failure(
    route: &Value,
    request: &http::HttpRequest,
) -> Option<(u16, &'static str, String)> {
    let hooks = route.get("request_hooks").and_then(Value::as_array)?;
    for hook in hooks {
        let hook_id = hook
            .as_str()
            .or_else(|| hook.get("hook_id").and_then(Value::as_str))?;
        match hook_id {
            "json_body_required"
                if !request
                    .content_type
                    .as_deref()
                    .is_some_and(|value| value.starts_with("application/json")) =>
            {
                return Some((
                    415,
                    "Unsupported Media Type",
                    route_request_validation_report(
                        route,
                        "json_content_type_required",
                        "This route requires an application/json request body.",
                    ),
                ));
            }
            "form_body_required"
                if !request.content_type.as_deref().is_some_and(|value| {
                    value.starts_with("application/x-www-form-urlencoded")
                }) =>
            {
                return Some((
                    415,
                    "Unsupported Media Type",
                    route_request_validation_report(
                        route,
                        "form_content_type_required",
                        "This route requires an application/x-www-form-urlencoded request body.",
                    ),
                ));
            }
            _ => {}
        }
    }
    None
}

/// Performs route request middleware failure.
fn route_request_middleware_failure(
    route: &Value,
    request: &http::HttpRequest,
) -> Option<(u16, &'static str, String)> {
    let middlewares = route.get("middleware").and_then(Value::as_array)?;
    for middleware in middlewares {
        if middleware.get("phase").and_then(Value::as_str) != Some("request") {
            continue;
        }
        let kind = middleware
            .get("kind")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let (actual_value, default_status, default_code, default_message) = match kind {
            "require_header" => (
                middleware
                    .get("header")
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                    .and_then(|header_name| dynamic::request_header_value(request, header_name)),
                428_u16,
                "middleware_header_required",
                "A required request header is missing or invalid.",
            ),
            "require_query_param" => (
                middleware
                    .get("param")
                    .or_else(|| middleware.get("field"))
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                    .and_then(|param| dynamic::request_query_value(request, param)),
                422_u16,
                "middleware_query_param_required",
                "A required query parameter is missing or invalid.",
            ),
            "require_form_field" => (
                middleware
                    .get("field")
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                    .and_then(|field| dynamic::request_form_value(request, field)),
                422_u16,
                "middleware_form_field_required",
                "A required form field is missing or invalid.",
            ),
            _ => continue,
        };
        let required_value = middleware
            .get("equals")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty());
        let satisfied = match (actual_value.as_deref(), required_value) {
            (Some(actual), Some(expected)) => actual == expected,
            (Some(_), None) => true,
            _ => false,
        };
        if !satisfied {
            let status = middleware
                .get("status_code")
                .and_then(Value::as_u64)
                .unwrap_or(default_status as u64) as u16;
            let status_text = http::http_status_text(status);
            let code = middleware
                .get("error_code")
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty())
                .unwrap_or(default_code);
            let message = middleware
                .get("message")
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty())
                .unwrap_or(default_message);
            return Some((
                status,
                status_text,
                route_request_validation_report(route, code, message),
            ));
        }
    }
    None
}

/// Performs HTTP response insert header.
fn http_response_insert_header(mut response: Vec<u8>, name: &str, value: &str) -> Vec<u8> {
    if name.is_empty() || value.contains(['\r', '\n']) || name.contains(['\r', '\n', ':']) {
        return response;
    }
    let Some(separator) = response.windows(2).position(|window| window == b"\r\n") else {
        return response;
    };
    let mut observed =
        Vec::with_capacity(response.len().saturating_add(name.len() + value.len() + 4));
    observed.extend_from_slice(&response[..separator + 2]);
    observed.extend_from_slice(format!("{name}: {value}\r\n").as_bytes());
    observed.extend_from_slice(&response[separator + 2..]);
    response.clear();
    observed
}

/// Performs apply route response middleware.
fn apply_route_response_middleware(
    route: &Value,
    request: &http::HttpRequest,
    response: Vec<u8>,
) -> Vec<u8> {
    let mut response = response;
    let Some(middlewares) = route.get("middleware").and_then(Value::as_array) else {
        return response;
    };
    for middleware in middlewares {
        if middleware.get("phase").and_then(Value::as_str) != Some("response") {
            continue;
        }
        let kind = middleware
            .get("kind")
            .and_then(Value::as_str)
            .unwrap_or_default();
        match kind {
            "set_header" => {
                let Some(name) = middleware
                    .get("name")
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                else {
                    continue;
                };
                let value = middleware
                    .get("value")
                    .and_then(Value::as_str)
                    .unwrap_or_default();
                response = http_response_insert_header(response, name, value);
            }
            "mirror_request_header" => {
                let Some(name) = middleware
                    .get("name")
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                else {
                    continue;
                };
                let source_header = middleware
                    .get("from_request_header")
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                    .unwrap_or(name);
                let value =
                    dynamic::request_header_value(request, source_header).unwrap_or_else(|| {
                        middleware
                            .get("default_value")
                            .and_then(Value::as_str)
                            .unwrap_or_default()
                            .to_owned()
                    });
                response = http_response_insert_header(response, name, &value);
            }
            "mirror_query_param" => {
                let Some(name) = middleware
                    .get("name")
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty())
                else {
                    continue;
                };
                let source_param = middleware
                    .get("from_query_param")
                    .or_else(|| middleware.get("param"))
                    .and_then(Value::as_str)
                    .filter(|value| !value.is_empty());
                let value = source_param
                    .and_then(|param| dynamic::request_query_value(request, param))
                    .unwrap_or_else(|| {
                        middleware
                            .get("default_value")
                            .and_then(Value::as_str)
                            .unwrap_or_default()
                            .to_owned()
                    });
                response = http_response_insert_header(response, name, &value);
            }
            _ => {}
        }
    }
    response
}

/// Returns the canonical response for a JSON-only action reached with the wrong content type.
fn json_content_type_required_response(action_id: &str, method: &str) -> Vec<u8> {
    http_json_response(
        415,
        "Unsupported Media Type",
        &serde_json::json!({
            "schema": "pharos.validation.report.v1",
            "report_id": "pharos.validation.report.v1",
            "action_id": action_id,
            "errors": ["json_content_type_required"],
            "field_errors": [],
            "form_errors": [{
                "rule_id": "json_content_type_required",
                "code": "json_content_type_required",
                "message": "This route requires an application/json request body."
            }]
        })
        .to_string(),
        method,
    )
}

/// Builds a readable summary from already filtered public validation details.
fn public_http_validation_message(details: &Value) -> Option<String> {
    let entries = details
        .get("field_errors")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .chain(
            details
                .get("form_errors")
                .and_then(Value::as_array)
                .into_iter()
                .flatten(),
        );
    let messages = entries
        .filter_map(|entry| {
            let message = entry.get("message")?.as_str()?.trim();
            if message.is_empty() {
                return None;
            }
            let field = entry
                .get("field_id")
                .and_then(Value::as_str)
                .unwrap_or("")
                .trim();
            Some(if field.is_empty() {
                message.to_owned()
            } else {
                format!("{field}: {message}")
            })
        })
        .take(8)
        .collect::<Vec<_>>();
    (!messages.is_empty()).then(|| messages.join("; "))
}

/// Normalizes every JSON failure into the stable public error envelope.
fn canonical_http_error_body(status_code: u16, status_text: &str, body: &str) -> String {
    let parsed = serde_json::from_str::<Value>(body).ok();
    let validation_details = parsed.as_ref().and_then(public_http_validation_details);
    let existing_error = parsed.as_ref().and_then(|value| value.get("error"));
    let message = existing_error
        .and_then(|error| error.get("message"))
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
        .or_else(|| {
            parsed
                .as_ref()
                .and_then(|value| value.get("message"))
                .and_then(Value::as_str)
                .map(ToOwned::to_owned)
        })
        .or_else(|| {
            existing_error
                .and_then(Value::as_str)
                .map(ToOwned::to_owned)
        })
        .or_else(|| {
            validation_details
                .as_ref()
                .and_then(public_http_validation_message)
        })
        .or_else(|| {
            parsed
                .as_ref()
                .and_then(|value| value.get("errors"))
                .and_then(Value::as_array)
                .map(|errors| {
                    errors
                        .iter()
                        .filter_map(Value::as_str)
                        .collect::<Vec<_>>()
                        .join(", ")
                })
                .filter(|message| !message.is_empty())
        })
        .filter(|message| !message.is_empty())
        .unwrap_or_else(|| status_text.to_owned())
        .chars()
        .take(1_024)
        .collect::<String>();
    let code = pharos_runtime_core::error::ErrorCode::from_http_status(status_code);
    let mut envelope = pharos_runtime_core::error::envelope(code, &message, None);
    if let (Some(details), Some(error)) = (
        validation_details,
        envelope.get_mut("error").and_then(Value::as_object_mut),
    ) {
        error.insert("details".to_owned(), details);
    }
    envelope.to_string()
}

/// Performs HTTP JSON response.
fn http_json_response(status_code: u16, status_text: &str, body: &str, method: &str) -> Vec<u8> {
    let canonical_body;
    let body = if status_code >= 400 {
        canonical_body = canonical_http_error_body(status_code, status_text, body);
        canonical_body.as_str()
    } else {
        body
    };
    let mut response = String::new();
    response.push_str(&http_status_line(status_code, status_text));
    response.push_str("Content-Type: application/json; charset=utf-8\r\n");
    response.push_str(&format!("Content-Length: {}\r\n", body.len()));
    response.push_str("Connection: close\r\n\r\n");
    if method != "HEAD" {
        response.push_str(body);
    }
    response.into_bytes()
}

/// Performs HTTP HTML response.
fn http_html_response(status_code: u16, status_text: &str, body: &str, method: &str) -> Vec<u8> {
    let response = dynamic::write_html_response(status_code, status_text, body, None);
    if method == "HEAD"
        && let Some((headers, _)) = response.split_once("\r\n\r\n")
    {
        return format!("{headers}\r\n\r\n").into_bytes();
    }
    response.into_bytes()
}

fn http_html_response_with_headers(
    status_code: u16,
    status_text: &str,
    body: &str,
    method: &str,
    extra_headers: &str,
) -> Vec<u8> {
    let response = dynamic::write_html_response_with_headers(
        status_code,
        status_text,
        body,
        None,
        extra_headers,
    );
    if method == "HEAD"
        && let Some((headers, _)) = response.split_once("\r\n\r\n")
    {
        return format!("{headers}\r\n\r\n").into_bytes();
    }
    response.into_bytes()
}

fn http_download_response(
    body: &[u8],
    content_type: &str,
    filename: &str,
    method: &str,
) -> Vec<u8> {
    let safe_filename = filename
        .chars()
        .filter(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '.' | '-' | '_'))
        .take(180)
        .collect::<String>();
    let filename = if safe_filename.is_empty() {
        "download.bin"
    } else {
        safe_filename.as_str()
    };
    let headers = format!(
        "HTTP/1.1 200 OK\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\nContent-Disposition: attachment; filename=\"{filename}\"\r\nX-Content-Type-Options: nosniff\r\nCache-Control: no-store\r\nConnection: close\r\n\r\n",
        body.len()
    );
    if method == "HEAD" {
        return headers.into_bytes();
    }
    let mut response = headers.into_bytes();
    response.extend_from_slice(body);
    response
}

/// Performs HTTP HTML response with CSRF.
fn http_html_response_with_csrf(
    status_code: u16,
    status_text: &str,
    body: &str,
    method: &str,
    csrf_token: Option<&str>,
) -> Vec<u8> {
    let response = dynamic::write_html_response(status_code, status_text, body, csrf_token);
    if method == "HEAD"
        && let Some((headers, _)) = response.split_once("\r\n\r\n")
    {
        return format!("{headers}\r\n\r\n").into_bytes();
    }
    response.into_bytes()
}

/// Performs HTTP route redirect.
fn http_route_redirect(location: &str) -> Vec<u8> {
    let safe_location = location.replace(['\r', '\n', '"'], "");
    let mut response = String::new();
    response.push_str(&http_status_line(303, "See Other"));
    response.push_str(&format!("Location: {safe_location}\r\n"));
    response.push_str("Content-Length: 0\r\nConnection: close\r\n\r\n");
    response.into_bytes()
}

/// Performs an HTMX-compatible redirect response.
fn http_hx_redirect(location: &str) -> Vec<u8> {
    let safe_location = location.replace(['\r', '\n', '"'], "");
    let mut response = String::new();
    response.push_str(&http_status_line(200, "OK"));
    response.push_str(&format!("HX-Redirect: {safe_location}\r\n"));
    response.push_str("Content-Length: 0\r\nConnection: close\r\n\r\n");
    response.into_bytes()
}

/// Performs a redirect response that preserves enhanced-form navigation.
fn http_route_redirect_for_request(request: &http::HttpRequest, location: &str) -> Vec<u8> {
    if dynamic::request_is_hx(Some(request)) {
        http_hx_redirect(location)
    } else {
        http_route_redirect(location)
    }
}

/// Performs app fragment response.
fn app_fragment_response(
    app: &AppRuntime,
    relative_path: &str,
    params: Value,
    method: &str,
) -> Vec<u8> {
    let body = app
        .artifact_dir
        .as_deref()
        .and_then(|root| json_commands::render_app_fragment_from_doc(root, relative_path, &params));
    match body {
        Some(body) => http_html_response(200, "OK", &body, method),
        None => http_text_response(
            500,
            "Internal Server Error",
            "declared app response failed to render\n",
        ),
    }
}

fn payment_provider_feedback_response(app: &AppRuntime, message_key: &str) -> Vec<u8> {
    let Some(app_root) = app.app_root.as_deref().map(Path::new) else {
        return http_text_response(
            500,
            "Internal Server Error",
            "payment provider feedback unavailable\n",
        );
    };
    let message = payment_provider::payment_provider_copy_value(app_root, message_key)
        .unwrap_or_else(|| message_key.to_owned());
    payment_provider_feedback_message_response(app, &message)
}

fn payment_provider_feedback_message_response(app: &AppRuntime, message: &str) -> Vec<u8> {
    let params = serde_json::json!({
        "payment_provider_feedback_message": message,
    });
    app_fragment_response(
        app,
        "templates/fragments/payment_provider_feedback.html",
        params,
        "GET",
    )
}

/// Performs HTTP route redirect with session.
fn http_route_redirect_with_session(
    app: &AppRuntime,
    location: &str,
    request_target: &str,
    request: &http::HttpRequest,
    session_token: &str,
) -> Vec<u8> {
    let safe_location = location.replace(['\r', '\n', '"'], "");
    let request_path = request_target.split('?').next().unwrap_or("/");
    let inferred_base = request_path
        .strip_suffix(&safe_location)
        .filter(|prefix| !prefix.is_empty())
        .map(|prefix| prefix.trim_end_matches('/'));
    let scoped_location = app
        .base_path
        .as_deref()
        .filter(|base| !base.is_empty() && *base != "/")
        .map(|base| base.trim_end_matches('/').to_owned())
        .or_else(|| inferred_base.map(ToOwned::to_owned))
        .map(|base| {
            if safe_location == base || safe_location.starts_with(&format!("{base}/")) {
                safe_location.clone()
            } else {
                format!("{base}{safe_location}")
            }
        })
        .unwrap_or(safe_location);
    format!(
        "{}Location: {scoped_location}\r\n{}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
        http_status_line(303, "See Other"),
        dynamic::session_cookie_header(app, Some(request), Some(session_token), false)
    )
    .into_bytes()
}

/// Returns the scoped login path for one mounted application.
fn app_login_location(app: &AppRuntime) -> String {
    app.base_path
        .as_deref()
        .filter(|value| !value.is_empty() && *value != "/")
        .map(|base| format!("{}/accounts/login/", base.trim_end_matches('/')))
        .unwrap_or_else(|| "/accounts/login/".to_owned())
}

/// Returns one application-scoped internal path below the mounted base path.
fn app_scope_path(app: &AppRuntime, path: &str) -> String {
    match app
        .base_path
        .as_deref()
        .filter(|base| !base.is_empty() && *base != "/")
    {
        Some(base) if path == "/" => base.trim_end_matches('/').to_owned(),
        Some(base) if !path.starts_with(base) => format!("{}{}", base.trim_end_matches('/'), path),
        _ => path.to_owned(),
    }
}

/// Returns one redirect-safe internal next path or the provided fallback.
fn app_safe_next_path(app: &AppRuntime, candidate: &str, fallback: &str) -> String {
    let trimmed = candidate.trim();
    if trimmed.is_empty()
        || !trimmed.starts_with('/')
        || trimmed.starts_with("//")
        || trimmed.contains(['\r', '\n'])
    {
        return fallback.to_owned();
    }
    let path_only = trimmed.split('?').next().unwrap_or(trimmed);
    match app
        .base_path
        .as_deref()
        .filter(|base| !base.is_empty() && *base != "/")
    {
        Some(base) => {
            let scoped = base.trim_end_matches('/');
            if path_only == scoped || path_only.starts_with(&format!("{scoped}/")) {
                trimmed.to_owned()
            } else {
                fallback.to_owned()
            }
        }
        None => trimmed.to_owned(),
    }
}

fn runtime_parse_yaml_file(path: &Path) -> Option<Value> {
    pharos_runtime_core::yaml::parse_yaml_file(path)
}

fn runtime_load_yaml_or_json_value(base_dir: &Path, basename: &str) -> Option<Value> {
    if basename.is_empty() {
        return None;
    }
    let yaml_path = base_dir.join(format!("{basename}.yml"));
    if yaml_path.exists() {
        return runtime_parse_yaml_file(&yaml_path);
    }
    let json_path = base_dir.join(format!("{basename}.json"));
    serde_json::from_str(&stdfs::read_to_string(json_path).ok()?).ok()
}

fn app_manifest_value(app: &AppRuntime) -> Option<Value> {
    app.artifact_dir
        .as_deref()
        .and_then(|path| runtime_load_yaml_or_json_value(Path::new(path), "pharos.app"))
        .or_else(|| {
            app.app_root
                .as_deref()
                .and_then(|path| runtime_load_yaml_or_json_value(Path::new(path), "pharos.app"))
        })
}

fn declared_login_path_is_safe(path: &str) -> bool {
    let trimmed = path.trim();
    !trimmed.is_empty()
        && trimmed.len() <= 512
        && trimmed.starts_with('/')
        && !trimmed.starts_with("//")
        && !trimmed.contains(['\r', '\n'])
}

fn declared_post_login_role_landing(manifest: &Value, roles: &[String]) -> Option<(String, bool)> {
    manifest
        .get("auth")?
        .get("post_login_redirects")?
        .as_array()?
        .iter()
        .find_map(|entry| {
            let role = entry.get("role")?.as_str()?;
            let path = entry.get("path")?.as_str()?;
            (roles.iter().any(|candidate| candidate == role) && declared_login_path_is_safe(path))
                .then(|| {
                    (
                        path.trim().to_owned(),
                        entry
                            .get("override_next")
                            .and_then(Value::as_bool)
                            .unwrap_or(false),
                    )
                })
        })
}

fn app_post_login_role_landing_path(
    app: &AppRuntime,
    actor_id: i64,
    fallback: &str,
) -> Result<(String, bool), pharos_runtime_database::operations::DatabaseError> {
    let roles = feature_runtime::actor_roles(app, actor_id)?;
    Ok(app_manifest_value(app)
        .and_then(|manifest| declared_post_login_role_landing(&manifest, &roles))
        .map(|(path, override_next)| (app_scope_path(app, &path), override_next))
        .unwrap_or_else(|| (fallback.to_owned(), false)))
}

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

    #[test]
    fn forced_owner_landing_is_explicit_and_role_scoped() {
        let manifest = serde_json::json!({"auth":{"post_login_redirects":[{"role":"store_owner","path":"/owner","override_next":true}]}});
        assert_eq!(
            declared_post_login_role_landing(&manifest, &["store_owner".to_owned()]),
            Some(("/owner".to_owned(), true))
        );
        assert_eq!(
            declared_post_login_role_landing(&manifest, &["customer".to_owned()]),
            None
        );
        let legacy = serde_json::json!({"auth":{"post_login_redirects":[{"role":"store_owner","path":"/owner"}]}});
        assert_eq!(
            declared_post_login_role_landing(&legacy, &["store_owner".to_owned()]),
            Some(("/owner".to_owned(), false))
        );
        for path in [
            "//example.com",
            "https://example.com",
            "/owner\r\nLocation:bad",
        ] {
            let invalid = serde_json::json!({"auth":{"post_login_redirects":[{"role":"store_owner","path":path,"override_next":true}]}});
            assert_eq!(
                declared_post_login_role_landing(&invalid, &["store_owner".to_owned()]),
                None
            );
        }
    }
}

/// Builds one login redirect that preserves an internal post-authentication path.
fn app_login_redirect(app: &AppRuntime, next_path: &str) -> Vec<u8> {
    let safe_next = next_path.replace(['\r', '\n', '"'], "");
    http_route_redirect(&format!("{}?next={safe_next}", app_login_location(app)))
}

/// Performs HTTP route redirect clear session.
fn http_route_redirect_clear_session(
    app: &AppRuntime,
    request: &http::HttpRequest,
    location: &str,
) -> Vec<u8> {
    let safe_location = location.replace(['\r', '\n', '"'], "");
    format!(
        "{}Location: {safe_location}\r\n{}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
        http_status_line(303, "See Other"),
        dynamic::session_cookie_header(app, Some(request), None, true)
    )
    .into_bytes()
}

/// Maps the shared database failure set to stable HTTP errors without driver details.
fn database_error_response(error: pharos_runtime_database::operations::DatabaseError) -> Vec<u8> {
    use pharos_runtime_database::operations::DatabaseError;
    let (status, message) = match error {
        DatabaseError::InvalidInput => (422, "invalid database input\n"),
        DatabaseError::InvalidContract => (422, "invalid database contract\n"),
        DatabaseError::MissingRecord => (404, "database record not found\n"),
        DatabaseError::AccessDenied => (403, "database access denied\n"),
        DatabaseError::Conflict => (409, "database conflict\n"),
        DatabaseError::Busy => (503, "database temporarily busy\n"),
        DatabaseError::CapacityExceeded => (503, "database capacity exceeded\n"),
        DatabaseError::Unsupported => (503, "database capability unavailable\n"),
        DatabaseError::Unavailable => (503, "database unavailable\n"),
        DatabaseError::StorageFailure => (503, "database operation failed\n"),
    };
    http_text_response(status, http::http_status_text(status), message)
}

/// Performs native session token hash.
fn native_session_token_hash(app: &AppRuntime, token: &str) -> Option<String> {
    pharos_runtime_security::native_session_token_hash(
        app.app_id.as_deref().unwrap_or_default(),
        token,
    )
}

/// Performs app mount prefix.
fn app_mount_prefix(app: &AppRuntime, request_target: &str, relative_path: &str) -> String {
    if let Some(base) = app
        .base_path
        .as_deref()
        .filter(|value| !value.is_empty() && *value != "/")
    {
        return base.trim_end_matches('/').to_owned();
    }
    let request_path = request_target.split('?').next().unwrap_or("/");
    request_path
        .strip_suffix(relative_path)
        .filter(|prefix| !prefix.is_empty())
        .map(|prefix| prefix.trim_end_matches('/').to_owned())
        .unwrap_or_default()
}

/// Isolates session and role caches by the configured data authority as well as
/// app identity. Changing a namespace cannot reuse another database's admission.
fn app_security_cache_scope(
    app: &AppRuntime,
) -> Result<String, pharos_runtime_database::operations::DatabaseError> {
    let app_id = app
        .app_id
        .as_deref()
        .ok_or(pharos_runtime_database::operations::DatabaseError::InvalidContract)?;
    let authority = if app_uses_file_backed_runtime_state(app) {
        serde_json::json!({"document": app.state_path.as_deref().ok_or(pharos_runtime_database::operations::DatabaseError::InvalidContract)?})
    } else {
        let config = database::checked_backend_config(
            Path::new(
                app.app_root
                    .as_deref()
                    .ok_or(pharos_runtime_database::operations::DatabaseError::InvalidContract)?,
            ),
            app.runtime_conf_path.as_deref().map(Path::new),
            Some(app_id),
        )?;
        serde_json::to_value(
            config
                .settings()
                .map_err(|_| pharos_runtime_database::operations::DatabaseError::InvalidContract)?,
        )
        .map_err(|_| pharos_runtime_database::operations::DatabaseError::InvalidContract)?
    };
    let bytes = serde_json::to_vec(&serde_json::json!({"app_id": app_id, "authority": authority}))
        .map_err(|_| pharos_runtime_database::operations::DatabaseError::InvalidContract)?;
    Ok(dynamic::hex_digest(&Sha256::digest(bytes)))
}

/// Performs active session user ID.
fn active_session_user_id(
    app: &AppRuntime,
    cookie: Option<&str>,
) -> Result<i64, pharos_runtime_database::operations::DatabaseError> {
    let Some(token) =
        cookie.and_then(|value| dynamic::dynamic_cookie_value(value, "pharos_session"))
    else {
        return Ok(0);
    };
    let Some(token_hash) = native_session_token_hash(app, &token) else {
        return Ok(0);
    };
    let session_store = if app_uses_file_backed_runtime_state(app) {
        None
    } else {
        if !app_uses_relational_runtime_authority(app) {
            return Ok(0);
        }
        let store = checked_app_database_operations(app)?;
        if !store
            .schema
            .entities
            .iter()
            .any(|entity| entity.name == "auth_session")
        {
            return Ok(0);
        }
        Some(store)
    };
    let cache_scope = app_security_cache_scope(app)?;
    let app_id = cache_scope.as_str();
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|value| value.as_secs())
        .unwrap_or(u64::MAX);
    if let Some(user_id) =
        pharos_runtime_security::local_session_cache_lookup(app_id, &token_hash, now)
    {
        return Ok(user_id);
    }
    if let Some(record) = cache::session_cache_lookup(app_id, &token_hash, now) {
        pharos_runtime_security::local_session_cache_store(
            app_id,
            record.user_id,
            &token_hash,
            record.expires_at_epoch,
            now,
        );
        return Ok(record.user_id);
    }
    let now_timestamp = current_timestamp_utc();
    if let Some(store) = session_store {
        let Some(record) =
            store
                .adapter
                .active_session(&store.config, &store.schema, &token_hash, now)?
        else {
            return Ok(0);
        };
        pharos_runtime_security::local_session_cache_store(
            app_id,
            record.user_id,
            &token_hash,
            record.expires_at_epoch,
            now,
        );
        cache::session_cache_store(app_id, record.user_id, &token_hash, record.expires_at_epoch);
        return Ok(record.user_id);
    }
    Ok(app
        .state_path
        .as_deref()
        .filter(|_| app_uses_file_backed_runtime_state(app))
        .and_then(|state_path| {
            let root = stdfs::read_to_string(state_path).ok()?;
            let root = serde_json::from_str::<Value>(&root).ok()?;
            root.get("sessions")?.as_array()?.iter().find_map(|row| {
                (row.get("session_token_hash").and_then(Value::as_str) == Some(token_hash.as_str())
                    && row.get("app_id").and_then(Value::as_str) == app.app_id.as_deref()
                    && row.get("revoked_at").is_none_or(|value| value.is_null())
                    && row
                        .get("expires_at")
                        .and_then(Value::as_str)
                        .is_some_and(|expires| {
                            expires
                                .parse::<u64>()
                                .map_or(expires > now_timestamp.as_str(), |expires| expires > now)
                        }))
                .then(|| row.get("user_id").and_then(Value::as_i64))
                .flatten()
            })
        })
        .unwrap_or(0))
}

/// Performs login error response with status.
fn login_error_response_with_status(
    app: &AppRuntime,
    request: &http::HttpRequest,
    message: &str,
    status_code: u16,
    status_text: &str,
) -> Vec<u8> {
    let target = request.target.as_str();
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    let relative_target = app_relative_target(app, target);
    let relative_path = relative_target.split('?').next().unwrap_or("/");
    let html = matched_app_route(app, "GET", relative_path)
        .filter(|route| route.get("page_id").and_then(Value::as_str) == Some("login"))
        .and_then(|route| {
            if route.get("feature_id").and_then(Value::as_str).is_some() {
                feature_runtime::render_feature_page_html_with_error(
                    app,
                    &route,
                    &relative_target,
                    0,
                    false,
                    &csrf_token,
                    Some(message),
                )
                .ok()
            } else {
                app_route_page_html(
                    app,
                    &route,
                    &relative_target,
                    0,
                    false,
                    0,
                    Some(message),
                    &csrf_token,
                )
            }
        })
        .or_else(|| {
            let route = serde_json::json!({"page_id":"login"});
            app_route_page_html(
                app,
                &route,
                &relative_target,
                0,
                false,
                0,
                Some(message),
                &csrf_token,
            )
        });
    let Some(html) = html else {
        return http_text_response(
            500,
            "Internal Server Error",
            "declared login route failed to render\n",
        );
    };
    http_html_response_with_csrf(
        status_code,
        status_text,
        &html,
        request.method.as_str(),
        Some(&csrf_token),
    )
}

/// Performs login error response.
fn login_error_response(app: &AppRuntime, request: &http::HttpRequest, message: &str) -> Vec<u8> {
    login_error_response_with_status(app, request, message, 422, "Unprocessable Entity")
}

/// Performs HTTP static response.
fn http_static_response(response: artifact_server::StaticResponse, method: &str) -> Vec<u8> {
    let mut headers = String::new();
    headers.push_str(&http_status_line(
        response.status_code,
        response.status_text,
    ));
    headers.push_str("Content-Type: ");
    headers.push_str(response.content_type);
    headers.push_str("\r\n");
    headers.push_str(&format!("Content-Length: {}\r\n", response.content_length));
    headers.push_str("Connection: close\r\n\r\n");
    if method == "HEAD" {
        return headers.into_bytes();
    }
    let mut bytes = headers.into_bytes();
    bytes.extend_from_slice(&response.body);
    bytes
}

/// Reads HTTP request.
fn read_http_request<R: Read>(stream: &mut R) -> Result<http::HttpRequest, &'static str> {
    let mut buffer = Vec::with_capacity(1024);
    let mut chunk = [0u8; 1024];
    let header_end;
    loop {
        let read = match stream.read(&mut chunk) {
            Ok(read) => read,
            Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
            Err(error)
                if buffer.is_empty()
                    && matches!(
                        error.kind(),
                        std::io::ErrorKind::TimedOut | std::io::ErrorKind::WouldBlock
                    ) =>
            {
                // Browsers open speculative connections before navigation.
                // No request bytes means there is no request to reject.
                return Err("request connection closed");
            }
            Err(_) => return Err("request parse failed"),
        };
        if read == 0 {
            return Err("request connection closed");
        }
        buffer.extend_from_slice(&chunk[..read]);
        if let Some(end) = buffer.windows(4).position(|window| window == b"\r\n\r\n") {
            header_end = end + 4;
            break;
        }
        if let Some(end) = buffer.windows(2).position(|window| window == b"\n\n") {
            header_end = end + 2;
            break;
        }
        if buffer.len() > http::PHAROS_HTTP_MAX_HEADER_BYTES {
            return Err("request parse failed");
        }
    }
    let parsed = http::parse_http_request(&buffer[..header_end])?;
    let mut request = http::HttpRequest {
        method: parsed.method,
        target: parsed.target,
        headers: parsed
            .headers
            .iter()
            .map(|(name, value)| format!("{name}: {value}"))
            .collect::<Vec<_>>()
            .join("\r\n"),
        ..Default::default()
    };
    let mut content_length = 0i64;
    let mut chunked = false;
    for (name, value) in &parsed.headers {
        http::apply_known_header(&mut request, name, value, &mut content_length, &mut chunked);
    }
    if content_length < 0 {
        return Err("invalid request body length");
    }
    let body_limit = if request
        .content_type
        .as_deref()
        .is_some_and(|value| value.to_ascii_lowercase().starts_with("multipart/"))
    {
        http::PHAROS_HTTP_MAX_MULTIPART_BODY_BYTES
    } else {
        http::PHAROS_HTTP_MAX_BODY_BYTES
    };
    if chunked {
        let mut cursor = header_end;
        let mut body = Vec::new();
        loop {
            while buffer[cursor..].windows(2).all(|window| window != b"\r\n") {
                let read = stream
                    .read(&mut chunk)
                    .map_err(|_| "chunked body read failed")?;
                if read == 0 {
                    return Err("chunked body truncated");
                }
                buffer.extend_from_slice(&chunk[..read]);
            }
            let line_end = buffer[cursor..]
                .windows(2)
                .position(|window| window == b"\r\n")
                .ok_or("chunk size missing")?
                + cursor;
            let size_text =
                std::str::from_utf8(&buffer[cursor..line_end]).map_err(|_| "chunk size invalid")?;
            let size =
                usize::from_str_radix(size_text.trim(), 16).map_err(|_| "chunk size invalid")?;
            cursor = line_end + 2;
            if size == 0 {
                request.body = body;
                request.body_len = request.body.len();
                request.is_multipart = request
                    .content_type
                    .as_deref()
                    .is_some_and(|value| value.to_ascii_lowercase().starts_with("multipart/"));
                return Ok(request);
            }
            if body.len().saturating_add(size) > body_limit {
                return Err("chunked body exceeds its limit");
            }
            while buffer.len() < cursor.saturating_add(size).saturating_add(2) {
                let read = stream
                    .read(&mut chunk)
                    .map_err(|_| "chunked body read failed")?;
                if read == 0 {
                    return Err("chunked body truncated");
                }
                buffer.extend_from_slice(&chunk[..read]);
            }
            body.extend_from_slice(&buffer[cursor..cursor + size]);
            if &buffer[cursor + size..cursor + size + 2] != b"\r\n" {
                return Err("chunk terminator missing");
            }
            cursor += size + 2;
        }
    }
    let body_len = usize::try_from(content_length).map_err(|_| "request body length invalid")?;
    if body_len > body_limit {
        return Err("request body exceeds its limit");
    }
    while buffer.len() < header_end + body_len {
        let read = stream
            .read(&mut chunk)
            .map_err(|_| "request body read failed")?;
        if read == 0 {
            return Err("request body truncated");
        }
        buffer.extend_from_slice(&chunk[..read]);
    }
    request.body = buffer[header_end..header_end + body_len].to_vec();
    request.body_len = body_len;
    request.is_multipart = request
        .content_type
        .as_deref()
        .is_some_and(|value| value.to_ascii_lowercase().starts_with("multipart/"));
    Ok(request)
}

/// Performs current timestamp utc.
fn current_timestamp_utc() -> String {
    pharos_runtime_core::time::current_timestamp_utc()
}

/// Performs timestamp after seconds utc.
fn timestamp_after_seconds_utc(additional_seconds: u64) -> String {
    pharos_runtime_core::time::timestamp_after_seconds_utc(additional_seconds)
}

/// Formats epoch seconds through the shared runtime timestamp helper.
fn chrono_like_timestamp(seconds: u64) -> String {
    pharos_runtime_core::time::timestamp_from_epoch_seconds(seconds)
}

/// Parses one bounded runtime timestamp from epoch seconds or UTC text.
fn runtime_timestamp_seconds(timestamp_text: &str) -> Option<u64> {
    let text = timestamp_text.trim();
    if text.is_empty() {
        return None;
    }
    if text.bytes().all(|byte| byte.is_ascii_digit()) {
        return text.parse::<u64>().ok();
    }
    runtime_timestamp_seconds_utc_text(text)
}

/// Performs runtime timestamp seconds utc text.
fn runtime_timestamp_seconds_utc_text(text: &str) -> Option<u64> {
    let (date_text, time_text, offset_seconds) =
        if let Some((date_text, time_text)) = text.split_once('T') {
            let (time_text, offset_seconds) = if let Some(time_text) = time_text.strip_suffix('Z') {
                (time_text, 0_i64)
            } else {
                let sign_index = time_text.rfind(['+', '-'])?;
                let (time_text, offset_text) = time_text.split_at(sign_index);
                (time_text, runtime_timestamp_offset_seconds(offset_text)?)
            };
            (date_text, time_text, offset_seconds)
        } else if let Some((date_text, time_text)) = text.split_once(' ') {
            (date_text, time_text, 0_i64)
        } else {
            return None;
        };
    let (year, month, day) = runtime_timestamp_parse_date(date_text)?;
    let (hour, minute, second) = runtime_timestamp_parse_time(time_text)?;
    let days = runtime_days_from_civil(year, month, day)?;
    let seconds = days
        .checked_mul(86_400)?
        .checked_add(i64::from(hour) * 3_600)?
        .checked_add(i64::from(minute) * 60)?
        .checked_add(i64::from(second))?
        .checked_sub(offset_seconds)?;
    u64::try_from(seconds).ok()
}

/// Performs runtime timestamp parse date.
fn runtime_timestamp_parse_date(text: &str) -> Option<(i64, u32, u32)> {
    let mut parts = text.split('-');
    let year = parts.next()?.parse::<i64>().ok()?;
    let month = parts.next()?.parse::<u32>().ok()?;
    let day = parts.next()?.parse::<u32>().ok()?;
    if parts.next().is_some() {
        return None;
    }
    (1..=12).contains(&month).then_some((year, month, day))
}

/// Performs runtime timestamp parse time.
fn runtime_timestamp_parse_time(text: &str) -> Option<(u32, u32, u32)> {
    let mut parts = text.split(':');
    let hour = parts.next()?.parse::<u32>().ok()?;
    let minute = parts.next()?.parse::<u32>().ok()?;
    let second_text = parts.next()?;
    if parts.next().is_some() {
        return None;
    }
    let second_text = second_text
        .split_once('.')
        .map(|(value, _)| value)
        .unwrap_or(second_text);
    let second = second_text.parse::<u32>().ok()?;
    (hour < 24 && minute < 60 && second < 60).then_some((hour, minute, second))
}

/// Performs runtime timestamp offset seconds.
fn runtime_timestamp_offset_seconds(text: &str) -> Option<i64> {
    if text.len() != 6 {
        return None;
    }
    let sign = match text.as_bytes().first().copied()? {
        b'+' => 1_i64,
        b'-' => -1_i64,
        _ => return None,
    };
    if text.as_bytes().get(3).copied()? != b':' {
        return None;
    }
    let hour = text.get(1..3)?.parse::<i64>().ok()?;
    let minute = text.get(4..6)?.parse::<i64>().ok()?;
    if hour >= 24 || minute >= 60 {
        return None;
    }
    Some(sign * (hour * 3_600 + minute * 60))
}

/// Performs runtime days from civil.
fn runtime_days_from_civil(year: i64, month: u32, day: u32) -> Option<i64> {
    let max_day = match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        2 if runtime_is_leap_year(year) => 29,
        2 => 28,
        _ => return None,
    };
    if day == 0 || day > max_day {
        return None;
    }
    let month = i64::from(month);
    let day = i64::from(day);
    let year = year - i64::from(month <= 2);
    let era = if year >= 0 { year } else { year - 399 } / 400;
    let yoe = year - era * 400;
    let mp = month + if month > 2 { -3 } else { 9 };
    let doy = (153 * mp + 2) / 5 + day - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    Some(era * 146_097 + doe - 719_468)
}

/// Performs runtime is leap year.
fn runtime_is_leap_year(year: i64) -> bool {
    (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
}

/// Emits runtime log banner.
fn emit_runtime_log_banner(stack: &RuntimeStack, config_record: &ServeConfig, load_ms: i64) {
    let timestamp = current_timestamp_utc();
    for line in runtime_log_banner_lines(stack, config_record, load_ms, &timestamp) {
        println!("{line}");
    }
}

enum RuntimeListener {
    Tcp(TcpListener),
    #[cfg(unix)]
    Unix(UnixListener, PathBuf),
}

impl RuntimeListener {
    /// Performs accept.
    fn accept(&self) -> std::io::Result<AcceptedConnection> {
        match self {
            Self::Tcp(listener) => listener
                .accept()
                .map(|(stream, _)| AcceptedConnection::Tcp(stream)),
            #[cfg(unix)]
            Self::Unix(listener, _) => listener
                .accept()
                .map(|(stream, _)| AcceptedConnection::Unix(stream)),
        }
    }

    /// Performs local endpoint.
    fn local_endpoint(&self) -> String {
        match self {
            Self::Tcp(listener) => listener
                .local_addr()
                .map(|addr| addr.to_string())
                .unwrap_or_else(|_| "127.0.0.1:7323".to_owned()),
            #[cfg(unix)]
            Self::Unix(_, path) => path.to_string_lossy().into_owned(),
        }
    }
}

impl Drop for RuntimeListener {
    /// Performs drop.
    fn drop(&mut self) {
        #[cfg(unix)]
        if let Self::Unix(_, path) = self {
            let _ = stdfs::remove_file(path);
        }
    }
}

enum AcceptedConnection {
    Tcp(TcpStream),
    #[cfg(unix)]
    Unix(UnixStream),
}

impl AcceptedConnection {
    /// Sets timeouts.
    fn set_timeouts(&self) {
        // Allow multipart uploads and local smoke clients enough time to
        // finish a bounded request without turning a slow body read into a
        // misleading HTTP 400 response.
        let timeout = Some(Duration::from_secs(10));
        match self {
            Self::Tcp(stream) => {
                let _ = stream.set_nonblocking(false);
                let _ = stream.set_read_timeout(timeout);
                let _ = stream.set_write_timeout(timeout);
            }
            #[cfg(unix)]
            Self::Unix(stream) => {
                let _ = stream.set_nonblocking(false);
                let _ = stream.set_read_timeout(timeout);
                let _ = stream.set_write_timeout(timeout);
            }
        }
    }

    /// Performs shutdown.
    fn shutdown(&self) {
        match self {
            Self::Tcp(stream) => {
                let _ = stream.shutdown(Shutdown::Both);
            }
            #[cfg(unix)]
            Self::Unix(stream) => {
                let _ = stream.shutdown(Shutdown::Both);
            }
        }
    }

    /// Reads request.
    fn read_request(&mut self) -> Result<http::HttpRequest, &'static str> {
        match self {
            Self::Tcp(stream) => read_http_request(stream),
            #[cfg(unix)]
            Self::Unix(stream) => read_http_request(stream),
        }
    }

    /// Writes all.
    fn write_all(&mut self, response: &[u8]) {
        match self {
            Self::Tcp(stream) => {
                let _ = stream.write_all(response);
                let _ = stream.flush();
            }
            #[cfg(unix)]
            Self::Unix(stream) => {
                let _ = stream.write_all(response);
                let _ = stream.flush();
            }
        }
    }

    /// Writes a validated file slice without buffering the representation in memory.
    fn write_stream(&mut self, response: &artifact_server::StreamResponse, method: &str) {
        match self {
            Self::Tcp(stream) => write_stream_response(stream, response, method),
            #[cfg(unix)]
            Self::Unix(stream) => write_stream_response(stream, response, method),
        }
    }
}

/// Copies one selected file range to an accepted connection with a fixed-size buffer.
fn write_stream_response<W: Write>(
    stream: &mut W,
    response: &artifact_server::StreamResponse,
    method: &str,
) {
    let content_range = if response.status_code == 206 {
        format!(
            "Content-Range: bytes {}-{}/{}\r\n",
            response.offset,
            response.offset + response.content_length.saturating_sub(1),
            response.complete_length
        )
    } else {
        String::new()
    };
    let headers = format!(
        "HTTP/1.1 {} {}\r\nContent-Type: {}\r\nContent-Length: {}\r\nAccept-Ranges: bytes\r\nETag: {}\r\nCache-Control: {}\r\nX-Content-Type-Options: nosniff\r\n{}{}Connection: close\r\n\r\n",
        response.status_code,
        response.status_text,
        response.content_type,
        response.content_length,
        response.etag,
        response.cache_control,
        content_range,
        response
            .content_disposition
            .as_ref()
            .map(|value| format!("Content-Disposition: {value}\r\n"))
            .unwrap_or_default(),
    );
    if stream.write_all(headers.as_bytes()).is_err() || method == "HEAD" {
        return;
    }
    let Ok(mut file) = stdfs::File::open(&response.file_path) else {
        return;
    };
    if file.seek(SeekFrom::Start(response.offset)).is_err() {
        return;
    }
    let mut remaining = response.content_length;
    let mut buffer = [0u8; 64 * 1024];
    while remaining > 0 {
        let count = usize::try_from(remaining.min(buffer.len() as u64)).unwrap_or(buffer.len());
        let Ok(read) = file.read(&mut buffer[..count]) else {
            return;
        };
        if read == 0 || stream.write_all(&buffer[..read]).is_err() {
            return;
        }
        remaining = remaining.saturating_sub(read as u64);
    }
    let _ = stream.flush();
}

/// Encodes a streaming selection error including the required unsatisfied range header.
fn http_stream_error(error: artifact_server::StreamError, method: &str) -> Vec<u8> {
    let mut response = http_static_response(error.response, method);
    if let Some(length) = error.unsatisfied_length
        && let Some(separator) = response.windows(2).position(|window| window == b"\r\n")
    {
        let header = format!("Content-Range: bytes */{length}\r\nAccept-Ranges: bytes\r\n");
        response.splice(separator + 2..separator + 2, header.bytes());
    }
    response
}

/// Opens runtime listener.
fn open_runtime_listener(
    config_record: &ServeConfig,
    stack: &RuntimeStack,
) -> Result<RuntimeListener, &'static str> {
    if let Some(socket_path) = config_record
        .socket_path
        .as_deref()
        .filter(|value| !value.is_empty())
        .or_else(|| {
            stack
                .socket_path
                .as_deref()
                .filter(|value| !value.is_empty())
        })
    {
        #[cfg(unix)]
        {
            let path = PathBuf::from(socket_path);
            if let Some(parent) = path.parent() {
                stdfs::create_dir_all(parent).map_err(|_| "failed to open listener")?;
            }
            if path.exists() {
                stdfs::remove_file(&path).map_err(|_| "failed to open listener")?;
            }
            let listener = UnixListener::bind(&path).map_err(|_| "failed to open listener")?;
            listener
                .set_nonblocking(true)
                .map_err(|_| "failed to open listener")?;
            return Ok(RuntimeListener::Unix(listener, path));
        }
        #[cfg(not(unix))]
        {
            let _ = socket_path;
            return Err("unix socket runtime serve not supported on this target");
        }
    }

    let host = config_record
        .host
        .as_deref()
        .filter(|value| !value.is_empty())
        .or_else(|| stack.host.as_deref().filter(|value| !value.is_empty()))
        .unwrap_or("127.0.0.1");
    let port = config_record
        .port
        .as_deref()
        .filter(|value| !value.is_empty())
        .or_else(|| stack.port.as_deref().filter(|value| !value.is_empty()))
        .unwrap_or("7323");
    let listener =
        TcpListener::bind(format!("{host}:{port}")).map_err(|_| "failed to open listener")?;
    listener
        .set_nonblocking(true)
        .map_err(|_| "failed to open listener")?;
    Ok(RuntimeListener::Tcp(listener))
}

/// Returns whether business availability create path.
fn is_business_availability_create_path(path: &str) -> bool {
    path.starts_with("/businesses/")
        && !path.contains("/technicians/")
        && path.ends_with("/availability/new/")
}

/// Resolves the most specific declarative route for a request method and path.
fn matched_app_route(app: &AppRuntime, method: &str, path: &str) -> Option<Value> {
    pharos_runtime_core::route::matched_app_route_value(app, method, path)
}

/// Rejects browser mutations whose Origin does not match the request Host.
fn trusted_browser_origin(request: &http::HttpRequest) -> bool {
    let origin = request.headers.lines().find_map(|line| {
        let (name, value) = line.split_once(':')?;
        name.trim()
            .eq_ignore_ascii_case("origin")
            .then_some(value.trim())
    });
    let Some(origin) = origin else {
        return true;
    };
    let host = request.headers.lines().find_map(|line| {
        let (name, value) = line.split_once(':')?;
        name.trim()
            .eq_ignore_ascii_case("host")
            .then_some(value.trim())
    });
    host.is_some_and(|host| {
        origin
            .strip_prefix("https://")
            .or_else(|| origin.strip_prefix("http://"))
            .and_then(|authority| authority.split('/').next())
            .is_some_and(|authority| authority.eq_ignore_ascii_case(host))
    })
}

/// Enforces actor ownership for app-declared payment-provider resources and
/// legacy business/appointment resource paths.
fn actor_owns_mutation_resource(
    app: &AppRuntime,
    path: &str,
    actor_id: i64,
) -> Result<bool, pharos_runtime_database::operations::DatabaseError> {
    let resource_path = path.strip_prefix("/api").unwrap_or(path);
    if !app_uses_file_backed_runtime_state(app) {
        if let Some(slug) = resource_path
            .strip_prefix("/businesses/")
            .and_then(|value| value.split('/').next())
        {
            if slug == "new" {
                return Ok(actor_id > 0);
            }
            let store = checked_app_database_operations(app)?;
            return pharos_runtime_business::actor_manages_business(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                actor_id,
                slug,
            );
        }
        if let Some(appointment_id) = resource_path
            .strip_prefix("/appointments/")
            .and_then(|value| value.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())
        {
            let store = checked_app_database_operations(app)?;
            return pharos_runtime_business::actor_owns_appointment(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                actor_id,
                appointment_id,
            );
        }
        if resource_path.starts_with("/appointments/") {
            return Ok(false);
        }
        return Ok(true);
    }
    let Some(state_path) = app.state_path.as_deref() else {
        return Ok(true);
    };
    let Some(root) = stdfs::read_to_string(state_path)
        .ok()
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
    else {
        return Ok(false);
    };
    if app
        .app_root
        .as_deref()
        .and_then(|app_root| {
            payment_provider::payment_provider_owner_route_value(Path::new(app_root), resource_path)
        })
        .is_some()
    {
        return Ok(app
            .app_root
            .as_deref()
            .and_then(|app_root| {
                payment_provider::actor_owns_declared_payment_provider_route(
                    &root,
                    Path::new(app_root),
                    resource_path,
                    actor_id,
                )
                .ok()
            })
            .unwrap_or(false));
    }
    if let Some(slug) = resource_path
        .strip_prefix("/businesses/")
        .and_then(|value| value.split('/').next())
    {
        if slug == "new" {
            return Ok(true);
        }
        let business_id = root
            .get("businesses")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.iter().find(|row| {
                    row.get("slug").and_then(Value::as_str) == Some(slug)
                        || row.get("id").and_then(Value::as_i64) == slug.parse::<i64>().ok()
                })
            })
            .and_then(|row| row.get("id").and_then(Value::as_i64));
        return Ok(business_id
            .is_some_and(|id| business::dynamic_user_manages_business(&root, actor_id, id)));
    }
    if let Some(appointment_id) = resource_path
        .strip_prefix("/appointments/")
        .and_then(|value| value.split('/').next())
        .and_then(|value| value.parse::<i64>().ok())
    {
        return Ok(root
            .get("appointments")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.iter()
                    .find(|row| row.get("id").and_then(Value::as_i64) == Some(appointment_id))
            })
            .is_some_and(|row| {
                row.get("user_id").and_then(Value::as_i64) == Some(actor_id)
                    || row
                        .get("business_id")
                        .and_then(Value::as_i64)
                        .is_some_and(|business_id| {
                            business::dynamic_user_manages_business(&root, actor_id, business_id)
                        })
            }));
    }
    Ok(true)
}

/// Resolves actor roles and verifies the route capability against the compiled policy contract.
fn actor_has_route_policy(
    app: &AppRuntime,
    actor_id: i64,
    capability: &str,
) -> Result<bool, pharos_runtime_database::operations::DatabaseError> {
    if capability == "public"
        && app
            .application_ir
            .as_ref()
            .is_some_and(|ir| ir.policies.len() == 1)
    {
        return Ok(true);
    }
    let Some(application_ir) = app.application_ir.as_ref() else {
        return Ok(false);
    };
    let mut roles = vec!["anonymous".to_owned()];
    if actor_id > 0 {
        roles.push("authenticated_user".to_owned());
    }
    if actor_id > 0
        && app_uses_file_backed_runtime_state(app)
        && let Some(state_path) = app.state_path.as_deref()
        && let Some(root) = stdfs::read_to_string(state_path)
            .ok()
            .and_then(|text| serde_json::from_str::<Value>(&text).ok())
    {
        if let Some(account_type) = root
            .get("users")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.iter()
                    .find(|row| row.get("id").and_then(Value::as_i64) == Some(actor_id))
            })
            .and_then(|row| row.get("account_type").and_then(Value::as_str))
        {
            roles.push(account_type.to_owned());
        }
        roles.extend(
            root.get("tenant_memberships")
                .and_then(Value::as_array)
                .into_iter()
                .flatten()
                .filter(|row| {
                    row.get("user_id").and_then(Value::as_i64) == Some(actor_id)
                        && row.get("membership_status").and_then(Value::as_str) == Some("active")
                })
                .filter_map(|row| {
                    row.get("role_id")
                        .and_then(Value::as_str)
                        .map(ToOwned::to_owned)
                }),
        );
    }
    if actor_id > 0 {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|value| value.as_secs())
            .unwrap_or(u64::MAX);
        let cache_scope = app_security_cache_scope(app)?;
        let app_id = cache_scope.as_str();
        let backend_roles =
            match pharos_runtime_security::local_role_cache_lookup(app_id, actor_id, now) {
                Some(roles) => roles,
                None => {
                    let mut loaded = feature_runtime::actor_roles(app, actor_id)?;
                    if !app_uses_file_backed_runtime_state(app) {
                        let store = checked_app_database_operations(app)?;
                        if store
                            .schema
                            .entities
                            .iter()
                            .any(|entity| entity.name == "tenant_membership")
                        {
                            loaded.extend(pharos_runtime_business::actor_tenant_roles(
                                store.adapter.as_ref(),
                                &store.config,
                                &store.schema,
                                actor_id,
                            )?);
                        }
                    }
                    loaded.sort();
                    loaded.dedup();
                    pharos_runtime_security::local_role_cache_store(app_id, actor_id, &loaded, now);
                    loaded
                }
            };
        roles.extend(backend_roles);
        roles.sort();
        roles.dedup();
    }
    Ok(application_ir
        .role_capability_edges
        .iter()
        .any(|(role, granted)| {
            granted.as_str() == capability
                && roles.iter().any(|actor_role| actor_role == role.as_str())
        }))
}

/// Converts validated booking form time fields to canonical 24-hour `HH:MM` storage.
fn normalized_booking_time(direct: &str, hour: &str, minute: &str, period: &str) -> Option<String> {
    if !direct.trim().is_empty() {
        let (hour, minute) = direct.trim().split_once(':')?;
        let hour = hour.parse::<u8>().ok()?;
        let minute = minute.parse::<u8>().ok()?;
        return (hour < 24 && minute < 60).then(|| format!("{hour:02}:{minute:02}"));
    }
    let hour = hour.trim().parse::<u8>().ok()?;
    let minute = minute.trim().parse::<u8>().ok()?;
    if !(1..=12).contains(&hour) || minute >= 60 {
        return None;
    }
    let hour = match period.trim().to_ascii_uppercase().as_str() {
        "AM" => hour % 12,
        "PM" => hour % 12 + 12,
        _ => return None,
    };
    Some(format!("{hour:02}:{minute:02}"))
}

/// Applies the single pre-dispatch authorization boundary for every mutation.
fn authorize_app_mutation(
    app: &AppRuntime,
    request: &http::HttpRequest,
    path: &str,
) -> Result<(), Vec<u8>> {
    let Some(route) = matched_app_route(app, &request.method, path) else {
        return Err(http_text_response(404, "Not Found", "undeclared action\n"));
    };
    let security = route
        .get("effective_security")
        .and_then(Value::as_object)
        .ok_or_else(|| http_text_response(403, "Forbidden", "route security unavailable\n"))?;
    let csrf_required = security
        .get("csrf_mode")
        .and_then(Value::as_str)
        .is_some_and(|mode| matches!(mode, "required" | "mutation_required"));
    let trusted_origin_required = security
        .get("trusted_origin_policy")
        .and_then(Value::as_str)
        .is_some_and(|mode| matches!(mode, "required" | "mutation_required"));
    if (trusted_origin_required && !trusted_browser_origin(request))
        || (csrf_required
            && !dynamic::csrf_request_valid(
                request,
                dynamic::request_body_text(request).as_deref(),
            ))
    {
        return Err(http_text_response(
            403,
            "Forbidden",
            "Security verification failed\n",
        ));
    }
    let auth_gate = route
        .get("auth_gate")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let policy_gate = route
        .get("policy_gate")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let capability_policy = security
        .get("capability_policy")
        .and_then(Value::as_str)
        .unwrap_or_default();
    if capability_policy == "policy_gate" && policy_gate.is_empty() {
        return Err(http_text_response(403, "Forbidden", "policy required\n"));
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return Err(database_error_response(error)),
    };
    if auth_gate == "session_required" && actor_id <= 0 {
        let next_path = route
            .get("action_id")
            .and_then(Value::as_str)
            .and_then(|action_id| feature_runtime::action_fallback_redirect(app, action_id).ok())
            .map(|redirect| app_scope_path(app, &redirect))
            .unwrap_or_else(|| path.to_owned());
        return Err(app_login_redirect(app, &next_path));
    }
    if capability_policy == "policy_gate"
        && !match actor_has_route_policy(app, actor_id, policy_gate) {
            Ok(value) => value,
            Err(error) => return Err(database_error_response(error)),
        }
    {
        return Err(http_text_response(403, "Forbidden", "capability denied\n"));
    }
    let tenant_scope = security
        .get("tenant_scope")
        .and_then(Value::as_str)
        .unwrap_or_default();
    if tenant_scope == "policy_bound"
        && actor_id > 0
        && !match actor_owns_mutation_resource(app, path, actor_id) {
            Ok(value) => value,
            Err(error) => return Err(database_error_response(error)),
        }
    {
        return Err(http_text_response(
            403,
            "Forbidden",
            "resource access denied\n",
        ));
    }
    let rate_limit_policy = security
        .get("rate_limit_policy")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let (maximum, window_seconds) = match rate_limit_policy {
        "runtime_default" => {
            if route.get("action_id").and_then(Value::as_str) == Some("login") {
                (10, 300)
            } else {
                (120, 60)
            }
        }
        _ => {
            return Err(http_text_response(
                503,
                "Service Unavailable",
                "rate-limit policy unavailable\n",
            ));
        }
    };
    let bucket_key = if route.get("action_id").and_then(Value::as_str) == Some("login") {
        dynamic::request_form_value(request, "username")
            .map(|value| value.trim().to_ascii_lowercase())
            .filter(|value| !value.is_empty())
            .unwrap_or_else(|| "anonymous".to_owned())
    } else if actor_id > 0 {
        format!("actor:{actor_id}")
    } else {
        "anonymous".to_owned()
    };
    let policy_key = format!(
        "{}:{}",
        rate_limit_policy,
        route
            .get("route_id")
            .and_then(Value::as_str)
            .unwrap_or("unknown")
    );
    if !app_uses_file_backed_runtime_state(app) {
        let store = checked_app_database_operations(app).map_err(database_error_response)?;
        return match store.adapter.admit_rate_limited_request(
            &store.config,
            &policy_key,
            &bucket_key,
            maximum,
            window_seconds,
        ) {
            Ok(true) => Ok(()),
            Ok(false) => Err(http_text_response(
                429,
                "Too Many Requests",
                "rate limit exceeded\n",
            )),
            Err(error) => Err(database_error_response(error)),
        };
    }
    match dynamic::admit_rate_limited_request_runtime_local(
        app,
        &policy_key,
        &bucket_key,
        maximum,
        window_seconds,
    ) {
        Ok(true) => {}
        Ok(false) => {
            return Err(http_text_response(
                429,
                "Too Many Requests",
                "rate limit exceeded\n",
            ));
        }
        Err(_) => {
            return Err(http_text_response(
                503,
                "Service Unavailable",
                "rate-limit state unavailable\n",
            ));
        }
    }
    Ok(())
}

/// Performs app static fragment.
fn app_static_fragment(artifact_root: &Path, relative_path: &str) -> Option<String> {
    json_commands::render_app_fragment_from_doc(
        artifact_root.to_string_lossy().as_ref(),
        relative_path,
        &Value::Object(serde_json::Map::new()),
    )
}

/// Performs app select option.
fn app_select_option(
    artifact_root: &Path,
    value: &str,
    label: &str,
    selected: bool,
) -> Option<String> {
    json_commands::render_app_fragment_from_doc(
        artifact_root.to_string_lossy().as_ref(),
        "templates/shared/fragments/select_option.html",
        &serde_json::json!({
            "option_value": value,
            "option_label": label,
            "selected_attr": if selected { " selected" } else { "" },
        }),
    )
}

/// Renders one app-owned UI fragment with an explicit parameter document.
fn app_ui_fragment(artifact_root: &Path, fragment_name: &str, params: Value) -> Option<String> {
    json_commands::render_app_fragment_from_doc(
        artifact_root.to_string_lossy().as_ref(),
        fragment_name,
        &params,
    )
}

/// Renders one canonical input control owned by the selected app bundle.
fn app_ui_input(
    artifact_root: &Path,
    id: &str,
    input_type: &str,
    name: &str,
    label: &str,
    label_class: &str,
    class_name: &str,
    value: &str,
    attributes_html: &str,
) -> Option<String> {
    app_ui_fragment(
        artifact_root,
        "templates/shared/fragments/ui_input.html",
        serde_json::json!({
            "id": id,
            "input_type": input_type,
            "name": name,
            "label": label,
            "label_class": label_class,
            "class_name": class_name,
            "value": value,
            "attributes_html": attributes_html,
            "help_html": "",
        }),
    )
}

/// Renders one canonical button control owned by the selected app bundle.
fn app_ui_button(
    artifact_root: &Path,
    id: &str,
    button_type: &str,
    class_name: &str,
    attributes_html: &str,
    content_html: &str,
) -> Option<String> {
    app_ui_fragment(
        artifact_root,
        "templates/shared/fragments/ui_button.html",
        serde_json::json!({
            "id": id,
            "button_type": button_type,
            "class_name": class_name,
            "attributes_html": attributes_html,
            "content_html": content_html,
        }),
    )
}

/// Renders one canonical select control owned by the selected app bundle.
fn app_ui_select(
    artifact_root: &Path,
    id: &str,
    name: &str,
    label: &str,
    label_class: &str,
    class_name: &str,
    attributes_html: &str,
    options_html: &str,
) -> Option<String> {
    app_ui_fragment(
        artifact_root,
        "templates/shared/fragments/ui_select.html",
        serde_json::json!({
            "id": id,
            "name": name,
            "label": label,
            "label_class": label_class,
            "class_name": class_name,
            "attributes_html": attributes_html,
            "options_html": options_html,
            "help_html": "",
        }),
    )
}

/// Renders one canonical hidden input owned by the selected app bundle.
fn app_ui_hidden_input(
    artifact_root: &Path,
    id: &str,
    name: &str,
    value: &str,
    attributes_html: &str,
) -> Option<String> {
    app_ui_fragment(
        artifact_root,
        "templates/shared/fragments/ui_hidden_input.html",
        serde_json::json!({
            "id": id,
            "name": name,
            "value": value,
            "attributes_html": attributes_html,
        }),
    )
}

/// Renders one canonical textarea control owned by the selected app bundle.
fn app_ui_textarea(
    artifact_root: &Path,
    id: &str,
    name: &str,
    label: &str,
    label_class: &str,
    class_name: &str,
    value: &str,
    attributes_html: &str,
) -> Option<String> {
    app_ui_fragment(
        artifact_root,
        "templates/shared/fragments/ui_textarea.html",
        serde_json::json!({
            "id": id,
            "name": name,
            "label": label,
            "label_class": label_class,
            "class_name": class_name,
            "value": value,
            "attributes_html": attributes_html,
            "help_html": "",
        }),
    )
}

/// Populates canonical controls for static app pages without embedding authored markup in Rust.
fn populate_static_page_ui_params(
    artifact_root: &Path,
    page_id: &str,
    params: &mut serde_json::Map<String, Value>,
) -> Option<()> {
    let value = |name: &str| {
        params
            .get(name)
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_owned()
    };
    let service_name = value("service_name");
    let service_cost = value("service_cost");
    let service_duration = value("service_duration");
    let service_description = value("service_description");
    let service_primary_color = value("service_primary_color");
    let service_sort_options_html = value("service_sort_options_html");
    let booking_option_count = value("booking_option_count");
    let day_options = value("day_options");
    let start_time = value("start_time");
    let end_time = value("end_time");
    let delete_path = value("delete_path");
    let job_status_filter = value("status_filter");
    let job_search_query = value("search_query");
    let profile_full_name = value("full_name");
    let profile_phone_number = value("phone_number");
    let profile_address = value("address");
    let selected_payment_preference = value("selected_payment_preference");
    let mut insert = |name: &str, html: Option<String>| -> Option<()> {
        params.insert(name.to_owned(), Value::String(html?));
        Some(())
    };
    match page_id {
        "login" => {
            insert(
                "login_username_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "login_username",
                    "text",
                    "username",
                    "Username",
                    "",
                    "form-control",
                    "",
                    " autocomplete=\"username\" required",
                ),
            )?;
            insert(
                "login_password_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "login_password",
                    "password",
                    "password",
                    "Password",
                    "",
                    "form-control",
                    "",
                    " autocomplete=\"current-password\" required",
                ),
            )?;
            insert(
                "login_submit_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "login-submit",
                    "submit",
                    "btn btn-primary",
                    " style=\"width:100%\"",
                    "Log In",
                ),
            )?;
        }
        "password_reset_request" => {
            insert(
                "id_reset_email_ui_html",
                app_ui_input(
                    artifact_root,
                    "reset_email",
                    "email",
                    "email",
                    "Email",
                    "",
                    "form-control",
                    "",
                    " autocomplete=\"email\" required",
                ),
            )?;
            insert(
                "password_reset_request_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "password-reset-submit",
                    "submit",
                    "btn btn-primary",
                    " style=\"width:100%\"",
                    "Send reset link",
                ),
            )?;
        }
        "password_reset_complete" => {
            insert(
                "id_reset_password_ui_html",
                app_ui_input(
                    artifact_root,
                    "reset_password",
                    "password",
                    "password",
                    "New password",
                    "",
                    "form-control",
                    "",
                    " autocomplete=\"new-password\" required",
                ),
            )?;
            insert(
                "id_reset_password_confirm_ui_html",
                app_ui_input(
                    artifact_root,
                    "reset_password_confirm",
                    "password",
                    "password_confirm",
                    "Confirm password",
                    "",
                    "form-control",
                    "",
                    " autocomplete=\"new-password\" required",
                ),
            )?;
            insert(
                "password_reset_complete_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "password-reset-complete-submit",
                    "submit",
                    "btn btn-primary",
                    " style=\"width:100%\"",
                    "Update password",
                ),
            )?;
        }
        "register" => {
            let controls = [
                (
                    "id_username_ui_html",
                    "register_username",
                    "text",
                    "username",
                    "Username",
                    " autocomplete=\"username\" required",
                ),
                (
                    "id_email_ui_html",
                    "register_email",
                    "email",
                    "email",
                    "Email",
                    " autocomplete=\"email\" required",
                ),
                (
                    "id_full_name_ui_html",
                    "register_full_name",
                    "text",
                    "full_name",
                    "Full name",
                    " autocomplete=\"name\" required",
                ),
                (
                    "id_phone_number_ui_html",
                    "register_phone_number",
                    "text",
                    "phone_number",
                    "Phone",
                    " autocomplete=\"tel\"",
                ),
                (
                    "id_password_ui_html",
                    "register_password",
                    "password",
                    "password",
                    "Password",
                    " autocomplete=\"new-password\" required",
                ),
                (
                    "id_password_confirm_ui_html",
                    "register_password_confirm",
                    "password",
                    "password_confirm",
                    "Confirm password",
                    " autocomplete=\"new-password\" required",
                ),
            ];
            for (param, id, input_type, name, label, attributes) in controls {
                insert(
                    param,
                    app_ui_input(
                        artifact_root,
                        id,
                        input_type,
                        name,
                        label,
                        "",
                        "form-control",
                        "",
                        attributes,
                    ),
                )?;
            }
            let options = [
                app_select_option(artifact_root, "business_customer", "Customer", true)?,
                app_select_option(artifact_root, "business_owner", "Business owner", false)?,
            ]
            .join("");
            insert(
                "id_account_type_ui_html",
                app_ui_select(
                    artifact_root,
                    "register_account_type",
                    "account_type",
                    "Account type",
                    "",
                    "form-control",
                    "",
                    &options,
                ),
            )?;
            insert(
                "register_submit_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "register-submit",
                    "submit",
                    "btn btn-primary",
                    " style=\"width:100%\"",
                    "Create Account",
                ),
            )?;
        }
        "job_queue_list" => {
            let options_html = [
                ("", "All statuses"),
                ("queued", "queued"),
                ("running", "running"),
                ("succeeded", "succeeded"),
                ("failed", "failed"),
                ("cancelled", "cancelled"),
            ]
            .iter()
            .map(|(option_value, label)| {
                app_select_option(
                    artifact_root,
                    option_value,
                    label,
                    job_status_filter == *option_value,
                )
            })
            .collect::<Option<Vec<_>>>()?
            .join("");
            insert(
                "job_status_filter_select_ui_html",
                app_ui_select(
                    artifact_root,
                    "job-status-filter",
                    "status",
                    "Status",
                    "sr-only",
                    "form-control",
                    "",
                    &options_html,
                ),
            )?;
            insert(
                "job_search_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "job-search",
                    "search",
                    "q",
                    "Search jobs",
                    "sr-only",
                    "form-control",
                    &job_search_query,
                    " placeholder=\"Search job or handler id\" autocomplete=\"off\" maxlength=\"160\"",
                ),
            )?;
            insert(
                "job_filter_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "job-filter",
                    "submit",
                    "btn btn-primary",
                    "",
                    "Filter",
                ),
            )?;
        }
        "booking_form" => {
            insert(
                "booking_title_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "booking_title",
                    "text",
                    "title",
                    "Title",
                    "",
                    "",
                    "",
                    " required",
                ),
            )?;
            insert(
                "booking_date_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "booking_date",
                    "date",
                    "date",
                    "Date",
                    "",
                    "",
                    "",
                    " required",
                ),
            )?;
            insert(
                "booking_time_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "booking_time",
                    "time",
                    "time",
                    "Time",
                    "",
                    "",
                    "",
                    " required",
                ),
            )?;
            insert(
                "booking_create_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "booking-create",
                    "submit",
                    "",
                    "",
                    "Create Booking",
                ),
            )?;
        }
        "qr_upload" => {
            insert(
                "qr_image_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "qr_image",
                    "file",
                    "qr_image",
                    "Upload QR image",
                    "sr-only",
                    "sr-only business-edit-hidden-input",
                    "",
                    " accept=\"image/*\" data-file-input-label=\"qr-upload-file-name\"",
                ),
            )?;
            insert(
                "qr_image_path_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "qr_image_path",
                    "text",
                    "qr_image_path",
                    "Local image path",
                    "",
                    "form-control",
                    "",
                    " placeholder=\"/absolute/path/to/qr.png\"",
                ),
            )?;
            insert(
                "qr_payload_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "qr_payload",
                    "text",
                    "qr_payload",
                    "Fallback QR payload",
                    "",
                    "form-control",
                    "",
                    " placeholder=\"lotus-studio\"",
                ),
            )?;
            insert(
                "qr_upload_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "qr-upload",
                    "submit",
                    "btn btn-primary btn-icon btn-icon-lg",
                    " title=\"Upload and Scan\" aria-label=\"Upload and Scan\"",
                    "Upload and Scan",
                ),
            )?;
            insert(
                "qr_clear_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "qr-clear",
                    "reset",
                    "btn btn-secondary btn-icon btn-icon-lg",
                    " title=\"Clear\" aria-label=\"Clear\"",
                    "Clear",
                ),
            )?;
        }
        "profile" => {
            for (param, id, name, label, current_value) in [
                (
                    "profile_full_name_input_ui_html",
                    "profile-full-name",
                    "full_name",
                    "Full name",
                    profile_full_name.as_str(),
                ),
                (
                    "profile_phone_number_input_ui_html",
                    "profile-phone",
                    "phone_number",
                    "Phone number",
                    profile_phone_number.as_str(),
                ),
                (
                    "profile_address_input_ui_html",
                    "profile-address",
                    "address",
                    "Address",
                    profile_address.as_str(),
                ),
            ] {
                insert(
                    param,
                    app_ui_input(
                        artifact_root,
                        id,
                        "text",
                        name,
                        label,
                        "",
                        "form-control",
                        current_value,
                        "",
                    ),
                )?;
            }
            let selected_payment_preference = if selected_payment_preference.is_empty() {
                "pay_on_site"
            } else {
                selected_payment_preference.as_str()
            };
            let payment_options = [
                ("pay_on_site", "Pay on site"),
                ("credit_card", "Credit card"),
            ]
            .into_iter()
            .map(|(value, label)| {
                app_select_option(
                    artifact_root,
                    value,
                    label,
                    value == selected_payment_preference,
                )
            })
            .collect::<Option<Vec<_>>>()?
            .join("");
            insert(
                "profile_payment_preference_select_ui_html",
                app_ui_select(
                    artifact_root,
                    "profile-payment-preference",
                    "payment_preference",
                    "Payment preference",
                    "",
                    "form-control",
                    "",
                    &payment_options,
                ),
            )?;
            insert(
                "profile_save_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "profile-save",
                    "submit",
                    "",
                    "",
                    "Save Profile",
                ),
            )?;
            insert(
                "profile_google_mode_input_ui_html",
                app_ui_hidden_input(artifact_root, "profile-google-mode", "mode", "user", ""),
            )?;
            insert(
                "profile_google_next_input_ui_html",
                app_ui_hidden_input(
                    artifact_root,
                    "profile-google-next",
                    "next",
                    "/profile/",
                    "",
                ),
            )?;
            insert(
                "profile_google_connect_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "profile-google-connect",
                    "submit",
                    "",
                    "",
                    "Connect Google Calendar",
                ),
            )?;
        }
        "business_create" => {
            insert(
                "business_create_name_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "business_create_name_input",
                    "text",
                    "name",
                    "Name",
                    "",
                    "form-control",
                    "",
                    " required autocomplete=\"organization\"",
                ),
            )?;
            insert(
                "business_create_address_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "business_create_address_input",
                    "text",
                    "address",
                    "Address",
                    "",
                    "form-control",
                    "",
                    " autocomplete=\"street-address\"",
                ),
            )?;
            insert(
                "business_create_description_textarea_ui_html",
                app_ui_textarea(
                    artifact_root,
                    "business_create_description_textarea",
                    "description",
                    "Description",
                    "",
                    "form-control",
                    "",
                    " rows=\"4\"",
                ),
            )?;
            let public_hidden = app_ui_hidden_input(
                artifact_root,
                "business-create-public-hidden",
                "is_public",
                "0",
                "",
            )?;
            let public_checkbox = app_ui_fragment(
                artifact_root,
                "templates/shared/fragments/ui_checkbox.html",
                serde_json::json!({"id":"business_create_public_toggle","name":"is_public","class_name":"","value":"1","label_class":"business-create-toggle-option","attributes_html":" checked","label_html":"Public","help_html":""}),
            )?;
            insert(
                "business_create_is_public_input_ui_html",
                Some(format!("{public_hidden}{public_checkbox}")),
            )?;
            let time_options = [
                app_select_option(artifact_root, "am_pm", "12-hour AM/PM", true)?,
                app_select_option(artifact_root, "24_hour", "24 hour", false)?,
            ]
            .join("");
            insert(
                "business_create_time_format_select_ui_html",
                app_ui_select(
                    artifact_root,
                    "business_create_time_format_select",
                    "time_format",
                    "Time Format",
                    "sr-only",
                    "form-control",
                    "",
                    &time_options,
                ),
            )?;
            insert(
                "business_create_secondary_color_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "business_create_secondary_color_input",
                    "color",
                    "secondary_color",
                    "Banner Color",
                    "sr-only",
                    "color-swatch-input",
                    "#2563eb",
                    " data-color-hex-target=\"business-create-secondary-color-hex\"",
                ),
            )?;
            insert(
                "business_create_secondary_color_hex_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "business-create-secondary-color-hex",
                    "text",
                    "business_create_secondary_color_hex",
                    "Banner Color Hex",
                    "sr-only",
                    "form-control form-control-compact color-hex-input",
                    "#2563eb",
                    " inputmode=\"text\" spellcheck=\"false\" autocapitalize=\"characters\" data-color-hex-source=\"secondary_color\"",
                ),
            )?;
            insert(
                "business_create_logo_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "business-create-logo-input",
                    "file",
                    "logo",
                    "Logo",
                    "sr-only",
                    "sr-only business-edit-hidden-input",
                    "",
                    " accept=\"image/*\" data-file-input-label=\"business-create-logo-file-name\"",
                ),
            )?;
            insert(
                "business_create_submit_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "business_create_submit_button",
                    "submit",
                    "btn btn-success btn-icon btn-icon-lg btn-create-business",
                    " title=\"Create Business\" aria-label=\"Create Business\"",
                    &app_static_fragment(
                        artifact_root,
                        "templates/shared/fragments/ui_content_create_business.html",
                    )?,
                ),
            )?;
        }
        "business_edit" => {}
        "business_availability_edit" => {
            insert(
                "availability_day_select_ui_html",
                app_ui_select(
                    artifact_root,
                    "availability-day",
                    "day_of_week",
                    "Day",
                    "",
                    "form-control",
                    " required",
                    &day_options,
                ),
            )?;
            insert(
                "availability_start_time_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "availability-start",
                    "time",
                    "start_time",
                    "Start time",
                    "",
                    "form-control",
                    &start_time,
                    " required",
                ),
            )?;
            insert(
                "availability_end_time_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "availability-end",
                    "time",
                    "end_time",
                    "End time",
                    "",
                    "form-control",
                    &end_time,
                    " required",
                ),
            )?;
            insert(
                "availability_save_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "availability-save",
                    "submit",
                    "btn btn-primary",
                    "",
                    "Save",
                ),
            )?;
            insert(
                "availability_delete_button_ui_html",
                app_ui_button(
                    artifact_root,
                    "availability-delete",
                    "submit",
                    "btn btn-danger",
                    &format!(
                        " formaction=\"{}\"",
                        json_commands::html_escape_text(&delete_path)
                    ),
                    "Delete",
                ),
            )?;
        }
        "service_edit" => {
            insert(
                "service_edit_image_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "service-edit-image",
                    "file",
                    "service_image",
                    "Choose Service Image",
                    "sr-only",
                    "sr-only business-edit-hidden-input",
                    "",
                    " accept=\"image/*\" data-file-input-label=\"service-edit-image-file-name\"",
                ),
            )?;
            insert(
                "service_edit_remove_image_input_ui_html",
                app_ui_fragment(
                    artifact_root,
                    "templates/shared/fragments/ui_checkbox.html",
                    serde_json::json!({"id":"service-edit-remove-image","name":"remove_image","class_name":"sr-only business-edit-hidden-input business-edit-toggle-input","value":"1","label_class":"sr-only","attributes_html":"","label_html":"Remove Service Image","help_html":""}),
                ),
            )?;
            insert(
                "service_edit_name_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "service_edit_name_input",
                    "text",
                    "name",
                    "Name",
                    "sr-only",
                    "form-control form-control-compact",
                    &service_name,
                    " placeholder=\"Name\" autocomplete=\"off\" aria-label=\"Name\" required",
                ),
            )?;
            insert(
                "service_edit_cost_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "service_edit_cost_input",
                    "text",
                    "cost",
                    "Cost",
                    "sr-only",
                    "form-control form-control-compact",
                    &service_cost,
                    " placeholder=\"Cost\" inputmode=\"decimal\" required",
                ),
            )?;
            insert(
                "service_edit_duration_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "service_edit_duration_input",
                    "number",
                    "duration_minutes",
                    "Duration",
                    "sr-only",
                    "form-control form-control-compact",
                    &service_duration,
                    " min=\"1\" placeholder=\"Minutes\" required",
                ),
            )?;
            insert(
                "service_edit_sort_order_select_ui_html",
                app_ui_select(
                    artifact_root,
                    "service_edit_sort_order_select",
                    "sort_order",
                    "Display Order",
                    "sr-only",
                    "form-control form-control-compact",
                    " required",
                    &service_sort_options_html,
                ),
            )?;
            insert(
                "service_edit_description_textarea_ui_html",
                app_ui_textarea(
                    artifact_root,
                    "service_edit_description_textarea",
                    "description",
                    "Description",
                    "sr-only",
                    "form-control",
                    &service_description,
                    "",
                ),
            )?;
            insert(
                "service_edit_primary_color_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "service-edit-primary-color",
                    "color",
                    "primary_color",
                    "Service Color",
                    "sr-only",
                    "color-swatch-input",
                    &service_primary_color,
                    " data-color-hex-target=\"service-edit-primary-color-hex\"",
                ),
            )?;
            insert(
                "service_edit_primary_color_hex_input_ui_html",
                app_ui_input(
                    artifact_root,
                    "service-edit-primary-color-hex",
                    "text",
                    "service_edit_primary_color_hex",
                    "Service Color Hex Code",
                    "sr-only",
                    "form-control form-control-compact color-hex-input",
                    &service_primary_color,
                    " inputmode=\"text\" spellcheck=\"false\" autocapitalize=\"characters\" data-color-hex-source=\"primary_color\"",
                ),
            )?;
            for (param, id, kind, class_name, attrs, content) in [
                (
                    "service_edit_save_button_ui_html",
                    "service_edit_save_button",
                    "submit",
                    "btn btn-primary btn-icon btn-icon-lg",
                    " title=\"Save Service\" aria-label=\"Save Service\"",
                    "Save Service",
                ),
                (
                    "service_edit_delete_dialog_open_button_ui_html",
                    "service_edit_delete_dialog_open_button",
                    "button",
                    "btn btn-danger btn-icon btn-icon-lg",
                    " data-dialog-open=\"service-delete-dialog\"",
                    "Delete Service",
                ),
                (
                    "booking_options_add_button_ui_html",
                    "booking_options_add_button",
                    "button",
                    "btn btn-secondary btn-icon btn-icon-sm",
                    " onclick=\"pharosAddBookingOptionRow(this)\"",
                    "Add Booking Option",
                ),
                (
                    "service_edit_delete_confirm_button_ui_html",
                    "service_edit_delete_confirm_button",
                    "submit",
                    "btn btn-danger",
                    "",
                    "Delete Service",
                ),
                (
                    "service_edit_delete_cancel_button_ui_html",
                    "service_edit_delete_cancel_button",
                    "button",
                    "btn btn-secondary",
                    " data-dialog-close=\"true\"",
                    "Cancel",
                ),
            ] {
                insert(
                    param,
                    app_ui_button(artifact_root, id, kind, class_name, attrs, content),
                )?;
            }
            insert(
                "booking_options_count_input_ui_html",
                app_ui_hidden_input(
                    artifact_root,
                    "booking-options-count",
                    "booking_option_count",
                    &booking_option_count,
                    " data-booking-option-count=\"true\"",
                ),
            )?;
            for (param, id, name, input_type, label, attrs) in [
                (
                    "booking_options_template_label_input_ui_html",
                    "booking-option-template-label",
                    "booking_option_label_template",
                    "text",
                    "Service Name",
                    " placeholder=\"Service Name\" data-booking-option-field=\"label\"",
                ),
                (
                    "booking_options_template_duration_input_ui_html",
                    "booking-option-template-duration",
                    "booking_option_duration_template",
                    "number",
                    "Time in minutes",
                    " min=\"1\" placeholder=\"Minutes\" data-booking-option-field=\"duration\"",
                ),
                (
                    "booking_options_template_cost_input_ui_html",
                    "booking-option-template-cost",
                    "booking_option_cost_template",
                    "text",
                    "Cost",
                    " placeholder=\"Cost\" inputmode=\"decimal\" data-booking-option-field=\"cost\"",
                ),
            ] {
                insert(
                    param,
                    app_ui_input(
                        artifact_root,
                        id,
                        input_type,
                        name,
                        label,
                        "sr-only",
                        "form-control form-control-compact booking-option-input",
                        "",
                        attrs,
                    ),
                )?;
            }
        }
        _ => {}
    }
    Some(())
}

/// Performs app route page HTML.
fn app_route_page_html(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    has_user: bool,
    managed_business_count: i64,
    error_message: Option<&str>,
    csrf_token: &str,
) -> Option<String> {
    app_route_page_html_result(
        app,
        route,
        target,
        actor_id,
        has_user,
        managed_business_count,
        error_message,
        csrf_token,
    )
    .ok()
}

/// Retains scoped database failures as HTTP outcomes and reads each detail once.
fn app_route_page_html_result(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    has_user: bool,
    managed_business_count: i64,
    error_message: Option<&str>,
    csrf_token: &str,
) -> Result<String, u16> {
    let page_id = route
        .get("page_id")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let detail = if matches!(page_id, "booking_detail" | "appointment_detail")
        && route.get("feature_id").and_then(Value::as_str).is_none()
    {
        let prefix = if page_id == "booking_detail" {
            "/bookings/"
        } else {
            "/appointments/"
        };
        let id = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix(prefix))
            .and_then(|path| path.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())
            .filter(|id| *id > 0)
            .ok_or(404u16)?;
        let store = app_database_operations(app).ok_or(503u16)?;
        let result = if page_id == "booking_detail" {
            business::personal_booking_view(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                actor_id,
                Some(id),
            )
        } else {
            business::appointment_view(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                actor_id,
                Some(id),
            )
        };
        Some(result.map_err(database_operation_http_status)?)
    } else if page_id == "job_queue_detail" {
        let execution_id = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/admin/jobs/"))
            .and_then(|path| path.trim_end_matches('/').parse::<i64>().ok())
            .filter(|id| *id > 0)
            .ok_or(404_u16)?;
        let store = app_database_operations(app).ok_or(503_u16)?;
        Some(
            pharos_runtime_database::queue::job_detail_view(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                execution_id,
            )
            .map_err(database_operation_http_status)?,
        )
    } else {
        None
    };
    app_route_page_html_from_detail(
        app,
        route,
        target,
        actor_id,
        has_user,
        managed_business_count,
        error_message,
        csrf_token,
        detail.as_ref(),
    )
    .ok_or(500)
}

/// Renders an authorized bounded detail model without repeating its database read.
fn app_route_page_html_from_detail(
    app: &AppRuntime,
    route: &Value,
    target: &str,
    actor_id: i64,
    has_user: bool,
    managed_business_count: i64,
    error_message: Option<&str>,
    csrf_token: &str,
    detail: Option<&Value>,
) -> Option<String> {
    let is_job_queue_request = target.split('?').next() == Some("/admin/jobs/");
    let artifact_dir = app.artifact_dir.as_deref().or_else(|| {
        if is_job_queue_request {
            eprintln!("job queue list render failed: artifact directory unavailable");
        }
        None
    })?;
    let artifact_root = Path::new(artifact_dir.trim());
    if route.get("feature_id").and_then(Value::as_str).is_some() {
        let mut last_error = None;
        let max_attempts = 10;
        for attempt in 0..max_attempts {
            let is_architect_settings = app.app_id.as_deref() == Some("architect")
                && target
                    .split('?')
                    .next()
                    .unwrap_or_default()
                    .trim_end_matches('/')
                    == "/settings";
            if is_architect_settings {
                eprintln!(
                    "architect settings full-page render attempt {} start",
                    attempt + 1
                );
            }
            match feature_runtime::render_feature_page_html(
                app, route, target, actor_id, has_user, csrf_token,
            ) {
                Ok(html) => {
                    if is_architect_settings {
                        eprintln!(
                            "architect settings full-page render attempt {} ok",
                            attempt + 1
                        );
                    }
                    return Some(html);
                }
                Err(error) => {
                    if is_architect_settings {
                        eprintln!(
                            "architect settings full-page render attempt {} failed: {error:?}",
                            attempt + 1
                        );
                    }
                    last_error = Some(error);
                    if attempt + 1 < max_attempts {
                        std::thread::sleep(Duration::from_millis(50));
                    }
                }
            }
        }
        if let Some(error) = last_error {
            eprintln!("feature page render failed: {error:?}");
        }
        return None;
    }
    let page_id = route
        .get("page_id")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .or_else(|| {
            if is_job_queue_request {
                eprintln!("job queue list render failed: page id unavailable");
            }
            None
        })?;
    let page_relative = json_commands::declared_page_relative_path(artifact_root, page_id)
        .or_else(|| match page_id {
            "generated_admin_manage" => {
                Some("templates/generated_admin/manage.page.json".to_owned())
            }
            "generated_admin_edit" => Some("templates/generated_admin/edit.page.json".to_owned()),
            _ => None,
        })
        .or_else(|| {
            if is_job_queue_request {
                eprintln!(
                    "job queue list render failed: page declaration unavailable for {page_id}"
                );
            }
            None
        })?;
    let page_spec_path = artifact_root.join(&page_relative);
    let page_spec = json_commands::json_doc_load_file(&page_spec_path).or_else(|| {
        if is_job_queue_request {
            eprintln!("job queue list render failed: page specification unreadable");
        }
        None
    })?;
    let template_relative = page_spec
        .get("template_file")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .or_else(|| {
            if is_job_queue_request {
                eprintln!("job queue list render failed: body template undeclared");
            }
            None
        })?;
    let template_path = artifact_root.join(template_relative);
    let mut params = serde_json::Map::new();
    if page_id == "generated_admin_manage" {
        let business_slug = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/businesses/"))
            .and_then(|path| path.split('/').next())
            .filter(|slug| !slug.is_empty())?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, true)?;
        params.insert(
            "manage_sections_html".to_owned(),
            Value::String(json_commands::dynamic_generated_admin_manage_sections_html(
                &state_root,
                business_slug,
                artifact_root,
                target,
            )?),
        );
    } else if page_id == "generated_admin_edit" {
        let service_name_input_ui_html = app_ui_input(
            artifact_root,
            "generated-admin-service-name",
            "text",
            "name",
            "Service",
            "",
            "form-control",
            "",
            " required",
        )?;
        let save_button_ui_html = app_ui_button(
            artifact_root,
            "generated-admin-save",
            "submit",
            "",
            "",
            "Save Service",
        )?;
        let delete_button_ui_html = app_ui_button(
            artifact_root,
            "generated-admin-delete",
            "submit",
            "",
            "",
            "Delete",
        )?;
        params = serde_json::Map::from_iter([
            ("title".to_owned(), Value::String("Edit Record".to_owned())),
            (
                "manage_path".to_owned(),
                Value::String("/businesses/lotus-studio/services/".to_owned()),
            ),
            ("update_path".to_owned(), Value::String(String::new())),
            (
                "form_fields_html".to_owned(),
                Value::String(app_ui_fragment(
                    artifact_root,
                    "templates/generated_admin/fragments/edit_form_fields.html",
                    serde_json::json!({"service_name_input_ui_html": service_name_input_ui_html}),
                )?),
            ),
            (
                "generated_admin_save_button_ui_html".to_owned(),
                Value::String(app_ui_fragment(
                    artifact_root,
                    "templates/generated_admin/fragments/edit_save_button.html",
                    serde_json::json!({"save_button_ui_html": save_button_ui_html}),
                )?),
            ),
            (
                "delete_form_html".to_owned(),
                Value::String(app_ui_fragment(
                    artifact_root,
                    "templates/generated_admin/fragments/edit_delete_form.html",
                    serde_json::json!({"delete_button_ui_html": delete_button_ui_html}),
                )?),
            ),
        ]);
    } else if page_id == "business_calendar" {
        let business_slug = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/business/"))
            .and_then(|path| path.strip_suffix("/calendar/"))
            .filter(|slug| !slug.is_empty())?;
        let year = target
            .split_once('?')
            .and_then(|(_, query)| json_commands::request_query_value(query, "year"));
        let month = target
            .split_once('?')
            .and_then(|(_, query)| json_commands::request_query_value(query, "month"));
        let date = target
            .split_once('?')
            .and_then(|(_, query)| json_commands::request_query_value(query, "date"));
        let store = app_database_operations(app)?;
        let state_root = pharos_runtime_business::business_calendar_view(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            business_slug,
            actor_id,
            pharos_runtime_business::CalendarSelection {
                year: year.as_deref(),
                month: month.as_deref(),
                date: date.as_deref(),
            },
        )
        .ok()?;
        let params_json = json_commands::dynamic_business_calendar_template_params_from_root_json(
            &state_root,
            business_slug,
            artifact_root,
            state_root.get("_calendar_year")?.as_str(),
            state_root.get("_calendar_month")?.as_str(),
            state_root.get("_calendar_date")?.as_str(),
            actor_id,
            csrf_token,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "diagnostics" {
        use pharos_runtime_database::operations::{
            Aggregate, AggregateQuery, Predicate, Query, SortKey,
        };
        let store = app_database_operations(app)?;
        let count = |entity: &str, filter: Option<Predicate>| -> Option<u64> {
            store
                .adapter
                .aggregate(
                    &store.config,
                    &store.schema,
                    &AggregateQuery {
                        entity: entity.to_owned(),
                        filter,
                        aggregate: Aggregate::Count,
                    },
                )
                .ok()?
                .as_u64()
        };
        let appointment_count = count("appointment", None)?;
        let booking_count = count("booking", None)?;
        let subscription_count = count("subscription", None)?;
        let rating_count = count("rating", None)?;
        let connection_count = count("google_calendar_connection", None)?;
        let unassigned_count = count(
            "appointment",
            Some(Predicate::Any(vec![
                Predicate::IsNull("technician_id".to_owned()),
                Predicate::AtMost("technician_id".to_owned(), Value::from(0)),
            ])),
        )?;
        let cancel_requested_count = count(
            "appointment",
            Some(Predicate::Equal(
                "status".to_owned(),
                Value::String("cancel_requested".to_owned()),
            )),
        )?;
        let mut status_counts = BTreeMap::new();
        for status in [
            "pending",
            "payment_pending",
            "confirmed",
            "cancel_requested",
            "reschedule_requested",
            "completed",
            "cancelled",
            "deleted",
        ] {
            let total = count(
                "appointment",
                Some(Predicate::Equal(
                    "status".to_owned(),
                    Value::String(status.to_owned()),
                )),
            )?;
            if total > 0 {
                status_counts.insert(status.to_owned(), total);
            }
        }
        let audit = store
            .adapter
            .query(
                &store.config,
                &store.schema,
                &Query {
                    entity: "audit_event".to_owned(),
                    fields: vec!["event_kind".to_owned()],
                    filter: None,
                    order: vec![SortKey {
                        field: "id".to_owned(),
                        descending: true,
                    }],
                    limit: 5,
                    offset: 0,
                },
            )
            .ok()?;
        let state_root = serde_json::json!({"audit_log": audit.into_iter().map(|row| serde_json::json!({"event": row.get("event_kind")})).collect::<Vec<_>>()});
        let appointment_statuses = if status_counts.is_empty() {
            app_static_fragment(
                artifact_root,
                "templates/appointments/fragments/diagnostic_status_empty.html",
            )?
        } else {
            status_counts
                .into_iter()
                .map(|(status, count)| {
                    json_commands::render_app_fragment_from_doc(
                        artifact_root.to_string_lossy().as_ref(),
                        "templates/appointments/fragments/diagnostic_status_row.html",
                        &serde_json::json!({"status": status, "count": count}),
                    )
                })
                .collect::<Option<Vec<_>>>()?
                .join("")
        };
        let recent_audit = state_root
            .get("audit_log")
            .and_then(Value::as_array)
            .and_then(|rows| {
                let mut items = rows
                    .iter()
                    .take(5)
                    .filter_map(|row| {
                        let event = row
                            .get("event")
                            .and_then(Value::as_str)
                            .filter(|value| !value.is_empty())
                            .unwrap_or("audit_event");
                        json_commands::render_app_fragment_from_doc(
                            artifact_root.to_string_lossy().as_ref(),
                            "templates/appointments/fragments/diagnostic_audit_row.html",
                            &serde_json::json!({"event": event}),
                        )
                    })
                    .collect::<Vec<_>>();
                if items.is_empty() {
                    items.push(app_static_fragment(
                        artifact_root,
                        "templates/appointments/fragments/diagnostic_audit_empty.html",
                    )?);
                }
                Some(items.join(""))
            })
            .or_else(|| {
                app_static_fragment(
                    artifact_root,
                    "templates/appointments/fragments/diagnostic_audit_empty.html",
                )
            })?;
        let maintenance_options_html = [
            (
                "dedupe_appointments",
                "Dedupe appointments",
                "pharos maintenance app ucal dedupe_appointments",
            ),
            (
                "reassign_appointments_to_technicians",
                "Reassign appointments to technicians",
                "pharos maintenance app ucal reassign_appointments_to_technicians",
            ),
            (
                "reconcile_future_appointments",
                "Reconcile future appointments",
                "pharos maintenance app ucal reconcile_future_appointments",
            ),
        ]
        .into_iter()
        .map(|(name, title, command)| {
            let content_html = app_ui_fragment(
                artifact_root,
                "templates/appointments/fragments/maintenance_option_content.html",
                serde_json::json!({"title": title, "command": command}),
            )?;
            let checkbox_html = app_ui_fragment(
                artifact_root,
                "templates/shared/fragments/ui_checkbox.html",
                serde_json::json!({
                    "id": format!("maintenance-{name}"),
                    "name": name,
                    "class_name": "",
                    "value": "1",
                    "label_class": "appointments-diagnostics-maintenance-option",
                    "attributes_html": "",
                    "label_html": content_html,
                    "help_html": "",
                }),
            )?;
            app_ui_fragment(
                artifact_root,
                "templates/appointments/fragments/maintenance_option.html",
                serde_json::json!({"maintenance_checkbox_ui_html": checkbox_html}),
            )
        })
        .collect::<Option<Vec<_>>>()?
        .join("");
        params = serde_json::Map::from_iter([
            (
                "appointment_count".to_owned(),
                Value::String(appointment_count.to_string()),
            ),
            (
                "booking_count".to_owned(),
                Value::String(booking_count.to_string()),
            ),
            (
                "subscription_count".to_owned(),
                Value::String(subscription_count.to_string()),
            ),
            (
                "rating_count".to_owned(),
                Value::String(rating_count.to_string()),
            ),
            (
                "unassigned_count".to_owned(),
                Value::String(unassigned_count.to_string()),
            ),
            (
                "cancel_requested_count".to_owned(),
                Value::String(cancel_requested_count.to_string()),
            ),
            (
                "connection_count".to_owned(),
                Value::String(connection_count.to_string()),
            ),
            (
                "appointment_statuses".to_owned(),
                Value::String(appointment_statuses),
            ),
            ("recent_audit".to_owned(), Value::String(recent_audit)),
            (
                "maintenance_options_html".to_owned(),
                Value::String(maintenance_options_html),
            ),
            (
                "run_maintenance_button_ui_html".to_owned(),
                Value::String(app_ui_fragment(
                    artifact_root,
                    "templates/appointments/fragments/maintenance_run_button.html",
                    serde_json::json!({
                        "run_maintenance_button_ui_html": app_ui_button(
                            artifact_root,
                            "run-maintenance",
                            "submit",
                            "btn btn-primary btn-icon btn-icon-lg",
                            " title=\"Run Maintenance\" aria-label=\"Run Maintenance\"",
                            &app_static_fragment(artifact_root, "templates/appointments/fragments/maintenance_button_content.html")?,
                        )?,
                    }),
                )?),
            ),
            (
                "maintenance_result_html".to_owned(),
                Value::String(String::new()),
            ),
        ]);
    } else if page_id == "job_queue_detail" {
        let execution_id = target
            .split('?')
            .next()?
            .trim_end_matches('/')
            .rsplit('/')
            .next()?
            .parse::<i64>()
            .ok()?;
        let view = detail?;
        params = serde_json::from_str(&json_commands::dynamic_job_queue_detail_page_params_json(
            view,
            execution_id,
            artifact_root,
        )?)
        .ok()?;
    } else if page_id == "job_queue_list" {
        let query_string = target
            .split_once('?')
            .map(|(_, query)| query)
            .unwrap_or_default();
        let status = json_commands::request_query_value(query_string, "status").unwrap_or_default();
        let search = json_commands::request_query_value(query_string, "q").unwrap_or_default();
        let page = json_commands::request_query_value(query_string, "page")
            .and_then(|value| value.parse::<usize>().ok())
            .unwrap_or(1);
        let store = app_database_operations(app)?;
        let state_root = pharos_runtime_database::queue::job_queue_page(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            &status,
            &search,
            page,
        )
        .ok()?;
        let params_json = json_commands::dynamic_job_queue_list_page_params_json(
            &state_root,
            artifact_root,
            query_string,
        )
        .or_else(|| {
            eprintln!("job queue list render failed: page parameters unavailable");
            None
        })?;
        params = serde_json::from_str::<Value>(&params_json)
            .ok()
            .and_then(|value| value.as_object().cloned())
            .or_else(|| {
                eprintln!("job queue list render failed: page parameters invalid");
                None
            })?;
    } else if page_id == "explore" {
        let store = app_database_operations(app)?;
        let state_root = Some(
            pharos_runtime_business::public_businesses(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
            )
            .ok()?,
        );
        let mut cards = String::new();
        if let Some(root) = state_root.as_ref()
            && let Some(businesses) = root.get("businesses").and_then(Value::as_array)
        {
            for business in businesses
                .iter()
                .filter(|row| row.get("is_public").and_then(Value::as_bool) == Some(true))
            {
                let Some(slug) = business.get("slug").and_then(Value::as_str) else {
                    continue;
                };
                let description = business
                    .get("description")
                    .and_then(Value::as_str)
                    .unwrap_or_default();
                let description = if description == "Business description" {
                    artifact_root
                        .join("data/fixtures/synthetic-public-state.json")
                        .as_path()
                        .to_str()
                        .and_then(|path| stdfs::read_to_string(path).ok())
                        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
                        .and_then(|fixture| {
                            fixture.get("businesses").and_then(Value::as_array).cloned()
                        })
                        .and_then(|businesses| {
                            businesses
                                .into_iter()
                                .find(|row| row.get("slug").and_then(Value::as_str) == Some(slug))
                        })
                        .and_then(|row| {
                            row.get("description")
                                .and_then(Value::as_str)
                                .map(str::to_owned)
                        })
                        .unwrap_or_else(|| description.to_owned())
                } else {
                    description.to_owned()
                };
                let card_params = serde_json::Map::from_iter([
                    ("business_slug".to_owned(), Value::String(slug.to_owned())),
                    (
                        "business_name".to_owned(),
                        Value::String(
                            business
                                .get("name")
                                .and_then(Value::as_str)
                                .unwrap_or_default()
                                .to_owned(),
                        ),
                    ),
                    (
                        "business_description".to_owned(),
                        Value::String(description.clone()),
                    ),
                    (
                        "business_image_url".to_owned(),
                        Value::String(
                            business
                                .get("image_url")
                                .and_then(Value::as_str)
                                .unwrap_or_default()
                                .to_owned(),
                        ),
                    ),
                ]);
                let rendered_card = json_commands::render_app_fragment_from_doc(
                    artifact_root.to_string_lossy().as_ref(),
                    "templates/explore/fragments/business_card.html",
                    &Value::Object(card_params),
                );
                let card = rendered_card.filter(|card| {
                    description.is_empty()
                        || card.contains(&json_commands::html_escape_text(&description))
                });
                if let Some(card) = card {
                    cards.push_str(&card);
                }
            }
        }
        if cards.is_empty() {
            cards = json_commands::render_app_fragment_from_doc(
                artifact_root.to_string_lossy().as_ref(),
                "templates/explore/fragments/businesses_empty.html",
                &Value::Object(serde_json::Map::from_iter([(
                    "message".to_owned(),
                    Value::String("No businesses available yet.".to_owned()),
                )])),
            )?;
        }
        params.insert("business_cards_html".to_owned(), Value::String(cards));
    } else if page_id == "business_landing" {
        let business_slug = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/b/"))
            .map(|path| path.trim_matches('/'))
            .filter(|slug| !slug.is_empty())?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, false)?;
        let landing_params = json_commands::dynamic_business_landing_page_params_json(
            &state_root,
            business_slug,
            artifact_root,
        )?;
        params = serde_json::from_str(&landing_params).ok()?;
        if has_user && actor_id > 0 {
            params.insert("cta_html".to_owned(), Value::String(String::new()));
        }
    } else if page_id == "business_rate" {
        let business_slug = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/rate/"))
            .map(|path| path.trim_matches('/'))
            .filter(|slug| !slug.is_empty())?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, false)?;
        let business = state_root
            .get("businesses")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.iter()
                    .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))
            })?;
        let business_name = business
            .get("name")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())?;
        let rating_options_ui_html = [
            ("50", "5.0", "5 stars", "business-rating-star-full", true),
            ("45", "4.5", "4.5 stars", "business-rating-star-half", false),
            ("40", "4.0", "4 stars", "business-rating-star-full", false),
            ("35", "3.5", "3.5 stars", "business-rating-star-half", false),
            ("30", "3.0", "3 stars", "business-rating-star-full", false),
            ("25", "2.5", "2.5 stars", "business-rating-star-half", false),
            ("20", "2.0", "2 stars", "business-rating-star-full", false),
            ("15", "1.5", "1.5 stars", "business-rating-star-half", false),
            ("10", "1.0", "1 star", "business-rating-star-full", false),
            ("05", "0.5", "0.5 stars", "business-rating-star-half", false),
        ]
        .into_iter()
        .map(|(suffix, value, label, star_class, checked)| {
            app_ui_fragment(
                artifact_root,
                "templates/shared/fragments/ui_radio_option.html",
                serde_json::json!({
                    "id": format!("rating-{suffix}"),
                    "name": "score",
                    "class_name": "",
                    "value": value,
                    "attributes_html": if checked { " checked" } else { "" },
                    "label_class": format!("business-rating-star {star_class}"),
                    "label_attributes_html": format!(" title=\"{label}\""),
                    "label_html": app_ui_fragment(
                        artifact_root,
                        "templates/businesses/fragments/rating_option_content.html",
                        serde_json::json!({"label": label}),
                    )?,
                }),
            )
        })
        .collect::<Option<Vec<_>>>()?
        .join("");
        let rating_score_ui_html = app_ui_fragment(
            artifact_root,
            "templates/businesses/fragments/rating_form_controls.html",
            serde_json::json!({"rating_options_ui_html": rating_options_ui_html}),
        )?;
        let rating_comment_textarea_ui_html = app_ui_fragment(
            artifact_root,
            "templates/businesses/fragments/rating_comment.html",
            serde_json::json!({
                "rating_comment_textarea_ui_html": app_ui_fragment(
                    artifact_root,
                    "templates/shared/fragments/ui_textarea.html",
                    serde_json::json!({
                        "id": "rating-comment",
                        "name": "comment",
                        "label": "Comment",
                        "label_class": "",
                        "class_name": "form-control",
                        "attributes_html": " rows=\"4\" placeholder=\"Share what stood out.\"",
                        "value": "",
                        "help_html": "",
                    }),
                )?,
            }),
        )?;
        let rating_submit_button_ui_html = app_ui_fragment(
            artifact_root,
            "templates/businesses/fragments/rating_submit.html",
            serde_json::json!({
                "rating_submit_button_ui_html": app_ui_button(
                    artifact_root,
                    "rating-submit",
                    "submit",
                    "btn btn-primary",
                    "",
                    "Submit Rating",
                )?,
            }),
        )?;
        params = serde_json::Map::from_iter([
            (
                "business_slug".to_owned(),
                Value::String(business_slug.to_owned()),
            ),
            (
                "business_name".to_owned(),
                Value::String(business_name.to_owned()),
            ),
            (
                "rating_score_ui_html".to_owned(),
                Value::String(rating_score_ui_html.to_owned()),
            ),
            (
                "rating_comment_textarea_ui_html".to_owned(),
                Value::String(rating_comment_textarea_ui_html.to_owned()),
            ),
            (
                "rating_submit_button_ui_html".to_owned(),
                Value::String(rating_submit_button_ui_html.to_owned()),
            ),
            ("error_html".to_owned(), Value::String(String::new())),
        ]);
    } else if page_id == "service_book_form" {
        let path = target.split('?').next().unwrap_or_default();
        let segments = path.trim_matches('/').split('/').collect::<Vec<_>>();
        let business_slug = segments.get(1).copied().unwrap_or_default();
        let service_id = path
            .trim_end_matches('/')
            .rsplit('/')
            .next()
            .and_then(|value| value.parse::<i64>().ok())?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, false)?;
        let business = state_root
            .get("businesses")
            .and_then(Value::as_array)
            .and_then(|businesses| {
                businesses.iter().find(|business| {
                    business.get("slug").and_then(Value::as_str) == Some(business_slug)
                })
            })?;
        let business_id = business.get("id").and_then(Value::as_i64)?;
        let service = state_root
            .get("services")
            .and_then(Value::as_array)
            .and_then(|services| {
                services.iter().find(|service| {
                    service.get("id").and_then(Value::as_i64) == Some(service_id)
                        && service.get("business_id").and_then(Value::as_i64) == Some(business_id)
                })
            })?;
        let service_name = service
            .get("name")
            .and_then(Value::as_str)
            .unwrap_or("Book service");
        let service_description = service
            .get("description")
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_owned();
        let service_image_url = service
            .get("image_url")
            .or_else(|| service.get("image"))
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_owned();
        let service_primary_color = service
            .get("primary_color")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .unwrap_or("#475569")
            .to_owned();
        let default_date =
            business::dynamic_next_day_ymd().unwrap_or_else(|| "2026-08-13".to_owned());
        let date_input_html = json_commands::render_app_fragment_from_doc(
            artifact_root.to_string_lossy().as_ref(),
            "templates/shared/fragments/ui_input.html",
            &Value::Object(serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("service_booking_date_input".to_owned()),
                ),
                ("input_type".to_owned(), Value::String("date".to_owned())),
                ("name".to_owned(), Value::String("date".to_owned())),
                ("label".to_owned(), Value::String("Date".to_owned())),
                (
                    "label_class".to_owned(),
                    Value::String("sr-only".to_owned()),
                ),
                (
                    "class_name".to_owned(),
                    Value::String("form-control".to_owned()),
                ),
                ("value".to_owned(), Value::String(default_date.clone())),
                (
                    "attributes_html".to_owned(),
                    Value::String(" required".to_owned()),
                ),
                ("help_html".to_owned(), Value::String(String::new())),
            ])),
        )?;
        let hour_options = (1..=12)
            .map(|hour| {
                app_select_option(
                    artifact_root,
                    &hour.to_string(),
                    &hour.to_string(),
                    hour == 12,
                )
            })
            .collect::<Option<Vec<_>>>()?
            .join("");
        let minute_options = [
            "00", "05", "10", "15", "20", "25", "30", "35", "40", "45", "50", "55",
        ]
        .into_iter()
        .map(|minute| app_select_option(artifact_root, minute, minute, minute == "00"))
        .collect::<Option<Vec<_>>>()?
        .join("");
        let period_options = [("AM", false), ("PM", true)]
            .into_iter()
            .map(|(value, selected)| app_select_option(artifact_root, value, value, selected))
            .collect::<Option<Vec<_>>>()?
            .join("");
        let service_booking_submit_button_ui_html = json_commands::render_app_fragment_from_doc(
            artifact_root.to_string_lossy().as_ref(),
            "templates/shared/fragments/ui_button.html",
            &Value::Object(serde_json::Map::from_iter([
                ("id".to_owned(), Value::String("service_booking_submit_button".to_owned())),
                ("button_type".to_owned(), Value::String("submit".to_owned())),
                ("class_name".to_owned(), Value::String("btn btn-primary btn-icon".to_owned())),
                ("attributes_html".to_owned(), Value::String(" title=\"Create Appointment\" aria-label=\"Create Appointment\" style=\"width:2.75rem;min-width:2.75rem;height:2.75rem;border-radius:10px;\"".to_owned())),
                (
                    "content_html".to_owned(),
                    Value::String(
                        json_commands::render_app_fragment_from_doc(
                            artifact_root.to_string_lossy().as_ref(),
                            "templates/shared/fragments/ui_content_create_appointment.html",
                            &Value::Object(serde_json::Map::new()),
                        )?,
                    ),
                ),
            ])),
        )?;
        let service_booking_notes_textarea_ui_html = json_commands::render_app_fragment_from_doc(
            artifact_root.to_string_lossy().as_ref(),
            "templates/shared/fragments/ui_textarea.html",
            &Value::Object(serde_json::Map::from_iter([
                (
                    "id".to_owned(),
                    Value::String("service_booking_notes_textarea".to_owned()),
                ),
                ("name".to_owned(), Value::String("notes".to_owned())),
                ("label".to_owned(), Value::String("Notes".to_owned())),
                (
                    "label_class".to_owned(),
                    Value::String("sr-only".to_owned()),
                ),
                (
                    "class_name".to_owned(),
                    Value::String("form-control".to_owned()),
                ),
                ("value".to_owned(), Value::String(String::new())),
                (
                    "attributes_html".to_owned(),
                    Value::String(
                        " rows=\"3\" placeholder=\"Notes\" aria-label=\"Notes\"".to_owned(),
                    ),
                ),
                ("help_html".to_owned(), Value::String(String::new())),
            ])),
        )?;
        params = serde_json::Map::from_iter([
            (
                "service_name".to_owned(),
                Value::String(service_name.to_owned()),
            ),
            (
                "service_duration".to_owned(),
                Value::String(
                    service
                        .get("duration_minutes")
                        .and_then(Value::as_i64)
                        .unwrap_or(45)
                        .to_string(),
                ),
            ),
            (
                "service_image_style".to_owned(),
                Value::String(if service_image_url.is_empty() {
                    "display:none;".to_owned()
                } else {
                    String::new()
                }),
            ),
            (
                "service_image_url".to_owned(),
                Value::String(service_image_url),
            ),
            (
                "service_image_alt".to_owned(),
                Value::String(service_name.to_owned()),
            ),
            (
                "service_badge_style".to_owned(),
                Value::String(
                    if service
                        .get("image_url")
                        .and_then(Value::as_str)
                        .filter(|value| !value.is_empty())
                        .is_some()
                    {
                        "display:none;".to_owned()
                    } else {
                        String::new()
                    },
                ),
            ),
            (
                "service_badge_color".to_owned(),
                Value::String(service_primary_color),
            ),
            (
                "service_badge_initials".to_owned(),
                Value::String(json_commands::dynamic_service_abbreviation(service_name)),
            ),
            (
                "service_description".to_owned(),
                Value::String(service_description),
            ),
            (
                "error_style".to_owned(),
                Value::String("display:none;".to_owned()),
            ),
            ("error_message".to_owned(), Value::String(String::new())),
            (
                "booking_option_select_style".to_owned(),
                Value::String("display:none;".to_owned()),
            ),
            (
                "time_period_style".to_owned(),
                Value::String("display:block;".to_owned()),
            ),
            (
                "booking-option-index_ui_html".to_owned(),
                Value::String(json_commands::render_app_fragment_from_doc(
                    artifact_root.to_string_lossy().as_ref(),
                    "templates/shared/fragments/ui_select.html",
                    &Value::Object(serde_json::Map::from_iter([
                        (
                            "id".to_owned(),
                            Value::String("booking-option-index".to_owned()),
                        ),
                        (
                            "name".to_owned(),
                            Value::String("booking_option_index".to_owned()),
                        ),
                        (
                            "label".to_owned(),
                            Value::String("Booking option".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(" required".to_owned()),
                        ),
                        ("options_html".to_owned(), Value::String(String::new())),
                        ("help_html".to_owned(), Value::String(String::new())),
                    ])),
                )?),
            ),
            (
                "service_booking_date_input_ui_html".to_owned(),
                Value::String(date_input_html),
            ),
            (
                "service_booking_hour_select_ui_html".to_owned(),
                Value::String(json_commands::render_app_fragment_from_doc(
                    artifact_root.to_string_lossy().as_ref(),
                    "templates/shared/fragments/ui_select.html",
                    &serde_json::json!({"id":"service_booking_hour_select","name":"time_hour","label":"Hour","label_class":"sr-only","class_name":"form-control","attributes_html":" style=\"width:4.5rem;min-width:4.5rem;\" required","options_html":hour_options,"help_html":""}),
                )?),
            ),
            (
                "service_booking_minute_select_ui_html".to_owned(),
                Value::String(json_commands::render_app_fragment_from_doc(
                    artifact_root.to_string_lossy().as_ref(),
                    "templates/shared/fragments/ui_select.html",
                    &serde_json::json!({"id":"service_booking_minute_select","name":"time_minute","label":"Minute","label_class":"sr-only","class_name":"form-control","attributes_html":" style=\"width:4.5rem;min-width:4.5rem;\" required","options_html":minute_options,"help_html":""}),
                )?),
            ),
            (
                "time_period_select_ui_html".to_owned(),
                Value::String(json_commands::render_app_fragment_from_doc(
                    artifact_root.to_string_lossy().as_ref(),
                    "templates/shared/fragments/ui_select.html",
                    &serde_json::json!({"id":"time_period_select","name":"time_period","label":"Time period","label_class":"sr-only","class_name":"form-control","attributes_html":" style=\"width:4.5rem;min-width:4.5rem;\" required","options_html":period_options,"help_html":""}),
                )?),
            ),
            (
                "service_booking_submit_button_ui_html".to_owned(),
                Value::String(service_booking_submit_button_ui_html),
            ),
            (
                "service_booking_notes_textarea_ui_html".to_owned(),
                Value::String(service_booking_notes_textarea_ui_html),
            ),
            (
                "pharos_idempotency_key".to_owned(),
                Value::String(
                    dynamic::random_secret_hex(16)
                        .unwrap_or_else(|_| "pharos-booking-idempotency".to_owned()),
                ),
            ),
        ]);
    } else if page_id == "business_detail_admin" {
        let business_slug = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/businesses/"))
            .and_then(|path| path.trim_matches('/').split('/').next())
            .filter(|slug| !slug.is_empty())?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, true)?;
        let params_json = json_commands::dynamic_business_detail_admin_page_params_from_root_json(
            &state_root,
            business_slug,
            artifact_root,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "payment_provider_setup" {
        let business_slug = target
            .split('?')
            .next()
            .and_then(|request_path| request_path.strip_prefix("/businesses/"))
            .and_then(|request_path| request_path.trim_matches('/').split('/').next())
            .filter(|slug| !slug.is_empty())?;
        let state_root = business_payment_for_page(app, artifact_root, business_slug, actor_id)?;
        let params_json = json_commands::dynamic_payment_provider_setup_page_params_from_root_json(
            &state_root,
            business_slug,
            artifact_root,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "business_delete_confirm" {
        let slug = target
            .split('?')
            .next()?
            .strip_prefix("/businesses/")?
            .split('/')
            .next()
            .filter(|slug| !slug.is_empty())?;
        let catalog = business_catalog_for_page(app, slug, actor_id, true)?;
        let business = catalog.get("businesses")?.as_array()?.first()?;
        params.insert("business_name".to_owned(), business.get("name")?.clone());
        params.insert("error_html".to_owned(), Value::String(String::new()));
        params.insert(
            "delete_path".to_owned(),
            Value::String(format!("/businesses/{slug}/delete/")),
        );
        params.insert(
            "cancel_path".to_owned(),
            Value::String(format!("/businesses/{slug}/")),
        );
        let ledger = dynamic::dynamic_contract_doc(app, "ui_ledger")?;
        let element = ui::ui_find_element(&ledger, "business_delete_confirm_button")?;
        let button_params = Value::Object(params.clone());
        let content = app_ui_fragment(
            artifact_root,
            element.get("content_fragment")?.as_str()?,
            button_params.clone(),
        )?;
        let mut attributes = ui::ui_declaration_attributes(element, &button_params)?;
        if !ui::ui_append_ledger_attribute(
            &mut attributes,
            element,
            "title",
            "title",
            &button_params,
            false,
        ) {
            return None;
        }
        let button = app_ui_button(
            artifact_root,
            element.get("id")?.as_str()?,
            element.get("button_type")?.as_str()?,
            element.get("class_name")?.as_str()?,
            &attributes,
            &content,
        )?;
        params.insert(
            "business_delete_confirm_button_ui_html".to_owned(),
            Value::String(button),
        );
    } else if page_id == "business_create" {
        params = serde_json::Map::new();
    } else if page_id == "business_edit" {
        let edit_path = target.split('?').next().unwrap_or_default();
        let business_slug = edit_path
            .strip_prefix("/businesses/")
            .and_then(|value| value.split('/').next())
            .filter(|value| !value.is_empty())?;
        let state_root = business_payment_for_page(app, artifact_root, business_slug, actor_id)?;
        let business = state_root
            .get("businesses")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.iter()
                    .find(|row| row.get("slug").and_then(Value::as_str) == Some(business_slug))
            })?;
        let business_name = business
            .get("name")
            .and_then(Value::as_str)
            .unwrap_or("Business");
        let description = business
            .get("description")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let address = business
            .get("address")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let logo_url = business
            .get("image_url")
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_owned();
        let time_format = business
            .get("time_format")
            .and_then(Value::as_str)
            .unwrap_or("am_pm");
        let secondary_color = business
            .get("secondary_color")
            .and_then(Value::as_str)
            .filter(|v| !v.is_empty())
            .unwrap_or("#e5e7eb");
        let external_integrations_html =
            json_commands::dynamic_business_edit_external_integrations_html(
                &state_root,
                business_slug,
                artifact_root,
            )
            .unwrap_or_default();
        params = serde_json::Map::from_iter([
            (
                "current_logo_image_url".to_owned(),
                Value::String(logo_url.clone()),
            ),
            (
                "current_logo_image_alt".to_owned(),
                Value::String(format!("{} logo", business_name)),
            ),
            (
                "current_logo_image_style".to_owned(),
                Value::String(if logo_url.is_empty() {
                    "display:none".to_owned()
                } else {
                    String::new()
                }),
            ),
            (
                "current_logo_empty_style".to_owned(),
                Value::String(if logo_url.is_empty() {
                    String::new()
                } else {
                    "display:none".to_owned()
                }),
            ),
            (
                "business_name".to_owned(),
                Value::String(business_name.to_owned()),
            ),
            (
                "business_description".to_owned(),
                Value::String(description.to_owned()),
            ),
            (
                "business_address".to_owned(),
                Value::String(address.to_owned()),
            ),
            (
                "business_edit_external_integrations_html".to_owned(),
                Value::String(external_integrations_html),
            ),
            (
                "am_pm_selected".to_owned(),
                Value::String(
                    if time_format == "am_pm" {
                        " selected"
                    } else {
                        ""
                    }
                    .to_owned(),
                ),
            ),
            (
                "hour_24_selected".to_owned(),
                Value::String(
                    if time_format == "24_hour" {
                        " selected"
                    } else {
                        ""
                    }
                    .to_owned(),
                ),
            ),
            (
                "secondary_color".to_owned(),
                Value::String(secondary_color.to_owned()),
            ),
        ]);
    } else if page_id == "service_edit" {
        let edit_path = target.split('?').next().unwrap_or_default();
        let business_slug = edit_path
            .strip_prefix("/businesses/")
            .and_then(|value| value.split('/').next())
            .filter(|value| !value.is_empty())?;
        let service_id = edit_path
            .trim_end_matches('/')
            .rsplit('/')
            .nth(1)
            .and_then(|value| value.parse::<i64>().ok())?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, true)?;
        let business = state_root
            .get("businesses")
            .and_then(Value::as_array)
            .and_then(|businesses| {
                businesses.iter().find(|business| {
                    business.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")
            .and_then(Value::as_str)
            .unwrap_or("Business")
            .to_owned();
        let service = state_root
            .get("services")
            .and_then(Value::as_array)
            .and_then(|services| {
                services.iter().find(|service| {
                    service.get("id").and_then(Value::as_i64) == Some(service_id)
                        && service.get("business_id").and_then(Value::as_i64) == Some(business_id)
                })
            })?;
        let service_name = service
            .get("name")
            .and_then(Value::as_str)
            .unwrap_or("Service");
        let service_image_url = service
            .get("image_url")
            .or_else(|| service.get("image"))
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_owned();
        let service_primary_color = service
            .get("primary_color")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .unwrap_or("#2563eb")
            .to_owned();
        let service_sort_order = service
            .get("sort_order")
            .and_then(Value::as_i64)
            .unwrap_or(1);
        let booking_options = service
            .get("booking_options")
            .cloned()
            .unwrap_or(Value::Array(Vec::new()));
        let booking_option_rows_html = booking_options
            .as_array()
            .and_then(|rows| {
                rows.iter()
                    .enumerate()
                    .map(|(index, option)| {
                        let option_index = index + 1;
                        let label_value = option
                            .get("label")
                            .map(|value| match value {
                                Value::String(text) => text.clone(),
                                other => serde_json::to_string(other)
                                    .unwrap_or_default()
                                    .trim_matches('"')
                                    .to_owned(),
                            })
                            .unwrap_or_default();
                        let duration_value = option
                            .get("duration_minutes")
                            .map(|value| match value {
                                Value::String(text) => text.clone(),
                                Value::Number(number) => number.to_string(),
                                other => serde_json::to_string(other)
                                    .unwrap_or_default()
                                    .trim_matches('"')
                                    .to_owned(),
                            })
                            .unwrap_or_else(|| "45".to_owned());
                        let cost_value = option
                            .get("cost")
                            .map(|value| match value {
                                Value::String(text) => text.clone(),
                                Value::Number(number) => number.to_string(),
                                other => serde_json::to_string(other)
                                    .unwrap_or_default()
                                    .trim_matches('"')
                                    .to_owned(),
                            })
                            .unwrap_or_default();
                        let label_input_ui_html = app_ui_input(
                            artifact_root,
                            &format!("booking-option-label-{option_index}"),
                            "text",
                            &format!("booking_option_label_{option_index}"),
                            "Service Name",
                            "sr-only",
                            "form-control form-control-compact booking-option-input booking-option-input-label",
                            &label_value,
                            " placeholder=\"Service Name\" autocomplete=\"off\" aria-label=\"Service Name\"",
                        )?;
                        let duration_input_ui_html = app_ui_input(
                            artifact_root,
                            &format!("booking-option-duration-{option_index}"),
                            "number",
                            &format!("booking_option_duration_{option_index}"),
                            "Time in minutes",
                            "sr-only",
                            "form-control form-control-compact booking-option-input booking-option-input-duration",
                            &duration_value,
                            " min=\"1\" placeholder=\"Minutes\" aria-label=\"Time in minutes\"",
                        )?;
                        let cost_input_ui_html = app_ui_input(
                            artifact_root,
                            &format!("booking-option-cost-{option_index}"),
                            "text",
                            &format!("booking_option_cost_{option_index}"),
                            "Cost",
                            "sr-only",
                            "form-control form-control-compact booking-option-input booking-option-input-cost",
                            &cost_value,
                            " placeholder=\"Cost\" aria-label=\"Cost\" inputmode=\"decimal\" autocomplete=\"off\"",
                        )?;
                        app_ui_fragment(
                            artifact_root,
                            "templates/businesses/fragments/service_edit_booking_option_row.html",
                            serde_json::json!({
                                "label_input_ui_html": label_input_ui_html,
                                "duration_input_ui_html": duration_input_ui_html,
                                "cost_input_ui_html": cost_input_ui_html,
                            }),
                        )
                    })
                    .collect::<Option<Vec<_>>>()
                    .map(|items| items.join(""))
            })
            .unwrap_or_default();
        let technician_rows_html = json_commands::technician_checkboxes_html(
            artifact_root,
            &state_root,
            business_id,
            service_id,
            "No technicians assigned.",
            false,
        )
        .unwrap_or_default();
        params = serde_json::Map::from_iter([
            (
                "save_path".to_owned(),
                Value::String(format!(
                    "/businesses/{business_slug}/services/{service_id}/edit/"
                )),
            ),
            (
                "cancel_path".to_owned(),
                Value::String(format!("/businesses/{business_slug}/")),
            ),
            (
                "delete_path".to_owned(),
                Value::String(format!(
                    "/businesses/{business_slug}/services/{service_id}/delete/"
                )),
            ),
            (
                "service_name".to_owned(),
                Value::String(service_name.to_owned()),
            ),
            ("business_name".to_owned(), Value::String(business_name)),
            (
                "service_image_style".to_owned(),
                Value::String(if service_image_url.is_empty() {
                    "display:none;".to_owned()
                } else {
                    "display:block;".to_owned()
                }),
            ),
            (
                "service_image_url".to_owned(),
                Value::String(service_image_url.clone()),
            ),
            (
                "service_image_alt".to_owned(),
                Value::String(service_name.to_owned()),
            ),
            (
                "service_badge_style".to_owned(),
                Value::String(if service_image_url.is_empty() {
                    String::new()
                } else {
                    "display:none;".to_owned()
                }),
            ),
            (
                "service_badge_color".to_owned(),
                Value::String(service_primary_color.clone()),
            ),
            (
                "service_badge_initials".to_owned(),
                Value::String(json_commands::dynamic_service_abbreviation(service_name)),
            ),
            (
                "service_cost".to_owned(),
                Value::String(
                    service
                        .get("cost")
                        .map(|value| value.to_string().trim_matches('"').to_owned())
                        .unwrap_or_default(),
                ),
            ),
            (
                "service_duration".to_owned(),
                Value::String(
                    service
                        .get("duration_minutes")
                        .and_then(Value::as_i64)
                        .unwrap_or(45)
                        .to_string(),
                ),
            ),
            (
                "service_sort_options_html".to_owned(),
                Value::String(
                    json_commands::service_sort_order_options_html(
                        artifact_root,
                        &state_root,
                        business_id,
                        service_sort_order,
                        false,
                    )
                    .unwrap_or_default(),
                ),
            ),
            (
                "service_description".to_owned(),
                Value::String(
                    service
                        .get("description")
                        .and_then(Value::as_str)
                        .unwrap_or_default()
                        .to_owned(),
                ),
            ),
            (
                "service_primary_color".to_owned(),
                Value::String(service_primary_color.clone()),
            ),
            (
                "booking_option_count".to_owned(),
                Value::String(
                    booking_options
                        .as_array()
                        .map(|rows| rows.len())
                        .unwrap_or(0)
                        .to_string(),
                ),
            ),
            (
                "service_booking_option_rows_html".to_owned(),
                Value::String(booking_option_rows_html),
            ),
            (
                "service_edit_technicians_empty_style".to_owned(),
                Value::String(if technician_rows_html.is_empty() {
                    String::new()
                } else {
                    "display:none;".to_owned()
                }),
            ),
            (
                "service_edit_technicians_empty_message".to_owned(),
                Value::String("No technicians assigned.".to_owned()),
            ),
            (
                "service_edit_technician_assignment_rows_html".to_owned(),
                Value::String(technician_rows_html),
            ),
        ]);
    } else if page_id == "business_availability_edit" {
        let edit_path = target.split('?').next().unwrap_or_default();
        let business_slug = edit_path
            .strip_prefix("/businesses/")
            .and_then(|value| value.split('/').next())
            .filter(|value| !value.is_empty())?;
        let availability_id = edit_path
            .split('/')
            .filter_map(|value| value.parse::<i64>().ok())
            .next_back()
            .filter(|value| *value > 0)?;
        let state_root = business_catalog_for_page(app, business_slug, actor_id, true)?;
        let business_id = state_root
            .get("businesses")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.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))?;
        let availability = state_root
            .get("business_availability")
            .and_then(Value::as_array)
            .and_then(|rows| {
                rows.iter().find(|row| {
                    row.get("id").and_then(Value::as_i64) == Some(availability_id)
                        && row.get("business_id").and_then(Value::as_i64) == Some(business_id)
                })
            })?;
        let day = availability
            .get("day_of_week")
            .and_then(Value::as_str)
            .unwrap_or("Mon");
        let start = availability
            .get("start_time")
            .and_then(Value::as_str)
            .unwrap_or("09:00");
        let end = availability
            .get("end_time")
            .and_then(Value::as_str)
            .unwrap_or("17:00");
        let day_options = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
            .into_iter()
            .map(|candidate| {
                app_select_option(artifact_root, candidate, candidate, candidate == day)
            })
            .collect::<Option<Vec<_>>>()?
            .join("");
        params = serde_json::Map::from_iter([
            (
                "business_path".to_owned(),
                Value::String(format!("/businesses/{business_slug}/")),
            ),
            ("save_path".to_owned(), Value::String(edit_path.to_owned())),
            (
                "delete_path".to_owned(),
                Value::String(format!(
                    "/businesses/{business_slug}/availability/{availability_id}/delete/"
                )),
            ),
            ("error_html".to_owned(), Value::String(String::new())),
            ("day_options".to_owned(), Value::String(day_options)),
            ("start_time".to_owned(), Value::String(start.to_owned())),
            ("end_time".to_owned(), Value::String(end.to_owned())),
        ]);
    } else if page_id == "business_dashboard" {
        let header = app_static_fragment(
            artifact_root,
            "templates/businesses/fragments/business_dashboard_header.html",
        )?;
        let store = database::runtime_logical_app_store(app).ok()?;
        let managed_businesses = pharos_runtime_business::managed_businesses(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            actor_id,
            64,
        )
        .ok()?;
        let managed_businesses = serde_json::to_value(managed_businesses)
            .ok()?
            .as_array()?
            .clone();
        let mut cards = String::new();
        for business in managed_businesses.iter() {
            let slug = business
                .get("slug")
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty())?;
            let name = business
                .get("name")
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty())?;
            let description = business
                .get("description")
                .and_then(Value::as_str)
                .unwrap_or_default();
            cards.push_str(&json_commands::render_app_fragment_from_doc(
                artifact_root.to_string_lossy().as_ref(),
                "templates/businesses/fragments/business_dashboard_card.html",
                &serde_json::json!({
                    "business_name": name,
                    "business_description": description,
                    "business_dashboard_actions_html": json_commands::render_app_fragment_from_doc(
                        artifact_root.to_string_lossy().as_ref(),
                        "templates/businesses/fragments/business_dashboard_actions.html",
                        &serde_json::json!({"business_slug": slug}),
                    )?,
                }),
            )?);
        }
        params = serde_json::Map::from_iter([
            (
                "business_dashboard_header_html".to_owned(),
                Value::String(header),
            ),
            ("business_cards_html".to_owned(), Value::String(cards)),
        ]);
    } else if page_id == "qr_upload" {
        params.insert("scan_html".to_owned(), Value::String(String::new()));
    } else if page_id == "booking_form" {
        params = serde_json::Map::from_iter([(
            "save_path".to_owned(),
            Value::String("/bookings/new/".to_owned()),
        )]);
    } else if page_id == "profile" {
        let store = database::runtime_logical_app_store(app).ok()?;
        let state_root = pharos_runtime_database::account_tokens::account_profile_view(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            actor_id,
        )
        .ok()?;
        let params_json =
            json_commands::dynamic_profile_page_params_json(&state_root, actor_id, artifact_root)?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "bookings" {
        let store = database::runtime_logical_app_store(app).ok()?;
        let state_root = business::personal_booking_view(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            actor_id,
            None,
        )
        .ok()?;
        let params_json = json_commands::dynamic_user_bookings_page_params_from_root_json(
            &state_root,
            actor_id,
            artifact_root,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "booking_detail" {
        let booking_id = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/bookings/"))
            .and_then(|path| path.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())?;
        let state_root = detail?;
        let params_json = json_commands::dynamic_booking_detail_page_params_from_root_json(
            state_root, actor_id, booking_id,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "appointments" {
        let store = database::runtime_logical_app_store(app).ok()?;
        let state_root = business::appointment_view(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            actor_id,
            None,
        )
        .ok()?;
        let params_json = json_commands::dynamic_appointments_page_params_from_root_json(
            &state_root,
            actor_id,
            artifact_root,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "appointment_detail" {
        let appointment_id = target
            .split('?')
            .next()
            .and_then(|path| path.strip_prefix("/appointments/"))
            .and_then(|path| path.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())?;
        let state_root = detail?;
        let params_json = json_commands::dynamic_appointment_detail_page_params_from_root_json(
            state_root,
            actor_id,
            appointment_id,
            artifact_root,
        )?;
        params = serde_json::from_str(&params_json).ok()?;
    } else if page_id == "login" {
        params = serde_json::Map::from_iter([
            ("error_html".to_owned(), Value::String(String::new())),
            ("next_input".to_owned(), Value::String(String::new())),
        ]);
    } else if page_id == "password_reset_request" {
        params =
            serde_json::Map::from_iter([("error_html".to_owned(), Value::String(String::new()))]);
    } else if page_id == "password_reset_complete" {
        params = serde_json::Map::from_iter([
            ("error_html".to_owned(), Value::String(String::new())),
            (
                "reset_post_path".to_owned(),
                Value::String(target.to_owned()),
            ),
        ]);
    } else if page_id == "register" {
        params = serde_json::Map::from_iter([
            ("error_html".to_owned(), Value::String(String::new())),
            ("next_input".to_owned(), Value::String(String::new())),
        ]);
    }
    let populated_ui_params = populate_static_page_ui_params(artifact_root, page_id, &mut params);
    if populated_ui_params.is_none() && page_id != "login" {
        return None.or_else(|| {
            if page_id == "job_queue_list" {
                eprintln!("job queue list render failed: UI parameters unavailable");
            }
            None
        });
    }
    if page_id.ends_with("_edit")
        && let Some(ledger) = dynamic::dynamic_contract_doc(app, "ui_ledger")
    {
        let declarations = ledger.get("elements")?.as_array()?;
        let values = Value::Object(params.clone());
        for element in declarations {
            if element.get("element_type").and_then(Value::as_str) != Some("button") {
                continue;
            }
            let id = element.get("id")?.as_str()?;
            let key = format!("{id}_ui_html");
            if !params.contains_key(&key) {
                continue;
            }
            let content = app_ui_fragment(
                artifact_root,
                element.get("content_fragment")?.as_str()?,
                values.clone(),
            )?;
            let mut attributes = ui::ui_declaration_attributes(element, &values)?;
            for name in [
                "title",
                "onclick",
                "formaction",
                "formmethod",
                "formtarget",
                "formenctype",
            ] {
                if !ui::ui_append_ledger_attribute(
                    &mut attributes,
                    element,
                    name,
                    name,
                    &values,
                    false,
                ) {
                    return None;
                }
            }
            for group in ["data", "hx"] {
                if !ui::ui_append_structured_attributes(&mut attributes, element, group, &values) {
                    return None;
                }
            }
            let button = app_ui_button(
                artifact_root,
                id,
                element.get("button_type")?.as_str()?,
                element.get("class_name")?.as_str()?,
                &attributes,
                &content,
            )?;
            params.insert(key, Value::String(button));
        }
    }
    if page_id == "login"
        && let Some(message) = error_message.filter(|value| !value.is_empty())
    {
        let error_html = json_commands::template_error_alert_html(artifact_root, message)
            .unwrap_or_else(|| json_commands::html_escape_text(message));
        params.insert("error_html".to_owned(), Value::String(error_html));
    }
    if matches!(
        page_id,
        "login" | "password_reset_request" | "password_reset_complete"
    ) {
        let csrf_token_input_ui_html = app_ui_fragment(
            artifact_root,
            "templates/shared/fragments/csrf_hidden_input.html",
            serde_json::json!({"csrf_token": csrf_token}),
        )?;
        params.insert(
            "csrf_token_input_ui_html".to_owned(),
            Value::String(csrf_token_input_ui_html),
        );
    }
    if page_id == "login" {
        params.insert(
            "login_action_path".to_owned(),
            Value::String(app_login_location(app)),
        );
        let next_target = target
            .split_once('?')
            .and_then(|(_, query)| json_commands::request_query_value(query, "next"))
            .unwrap_or_default();
        let next_input_html =
            app_ui_hidden_input(artifact_root, "login-next", "next", &next_target, "")?;
        params.insert("next_input".to_owned(), Value::String(next_input_html));
    }
    let title = page_spec
        .get("title")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .map(ToOwned::to_owned)
        .or_else(|| {
            page_spec
                .get("title_mode")
                .and_then(Value::as_str)
                .and_then(|key| params.get(key))
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty())
                .map(ToOwned::to_owned)
        })
        .or_else(|| {
            params
                .get("business_name")
                .or_else(|| params.get("service_name"))
                .or_else(|| params.get("surface_title"))
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty())
                .map(ToOwned::to_owned)
        })
        .unwrap_or_else(|| page_id.to_owned());
    let params = Value::Object(params);
    let body = json_commands::template_render_file(&template_path, &params).or_else(|| {
        if page_id == "job_queue_list" {
            eprintln!("job queue list render failed: body template unavailable");
        }
        None
    })?;
    let layout_id = route
        .get("layout_id")
        .and_then(Value::as_str)
        .or_else(|| page_spec.get("layout_id").and_then(Value::as_str));
    let rendered = json_commands::template_layout_page_html(
        artifact_root,
        app.base_path.as_deref(),
        layout_id,
        Some("en"),
        &title,
        &body,
        Some(target),
        has_user,
        managed_business_count,
    )
    .or_else(|| {
        if page_id == "job_queue_list" {
            eprintln!("job queue list render failed: layout unavailable");
        }
        None
    })?;
    Some(dynamic::csrf_inject_hidden_inputs(
        artifact_root,
        &rendered,
        csrf_token,
    ))
}

/// Performs app relative target.
fn app_relative_target(app: &AppRuntime, target: &str) -> String {
    pharos_runtime_core::relative_target(app.base_path.as_deref(), target)
}

/// Builds app-neutral request data for render and route adapters.
fn app_render_request(
    app: &AppRuntime,
    request: &http::HttpRequest,
) -> Result<
    pharos_runtime_core::render::RuntimeRenderRequest,
    pharos_runtime_database::operations::DatabaseError,
> {
    Ok(
        pharos_runtime_core::render::RuntimeRenderRequest::from_request(
            request,
            app.base_path.as_deref(),
            dynamic::csrf_token_for_response(request.cookie.as_deref()),
            active_session_user_id(app, request.cookie.as_deref())?,
        ),
    )
}

/// Performs app declarative route response.
fn app_declarative_route_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
) -> Option<Vec<u8>> {
    let render_request = match app_render_request(app, request) {
        Ok(value) => value,
        Err(error) => return Some(database_error_response(error)),
    };
    let method = render_request.method.as_str();
    let target = render_request.relative_target.as_str();
    let path = render_request.relative_path.as_str();
    let route = matched_app_route(app, method, path)?;
    let kind = route.get("kind").and_then(Value::as_str)?;
    if app.app_id.as_deref() == Some("ucal")
        && kind == "page"
        && route.get("route_id").and_then(Value::as_str) == Some("business_detail")
    {
        if render_request.actor_id <= 0 {
            return Some(app_login_redirect(app, path));
        }
        let slug = path.strip_prefix("/businesses/")?.trim_end_matches('/');
        match ucal_business_api_actor_manages_business(app, target, slug, request.cookie.as_deref())
        {
            Ok(Some(true)) => {}
            Ok(Some(false) | None) => {
                return Some(http_text_response(404, "Not Found", "Not found\n"));
            }
            Err(error) => {
                eprintln!("ucal business detail access check failed: {error:?}");
                return Some(http_text_response(
                    503,
                    "Service Unavailable",
                    "Unavailable\n",
                ));
            }
        }
    }
    let auth_gate = route.get("auth_gate").and_then(Value::as_str).unwrap_or("");
    if kind == "page"
        && auth_gate == "session_required"
        && route.get("feature_id").and_then(Value::as_str).is_some()
    {
        if render_request.actor_id <= 0 {
            return Some(app_login_redirect(app, path));
        }
        if let Some(policy) = route.get("policy_gate").and_then(Value::as_str)
            && policy != "public"
            && !match actor_has_route_policy(app, render_request.actor_id, policy) {
                Ok(value) => value,
                Err(error) => return Some(database_error_response(error)),
            }
        {
            if app.app_id.as_deref() == Some("architect")
                && path.trim_end_matches('/') == "/settings"
                && policy == "manage_llm_vendors"
            {
                return Some(architect_settings_access_denied_response(
                    app, request, method, target,
                ));
            }
            return Some(http_text_response(403, "Forbidden", "capability denied\n"));
        }
    }
    if kind == "page"
        && app.app_id.as_deref() == Some("architect")
        && path.trim_end_matches('/') == "/settings"
    {
        return Some(architect_settings_review_response(app, request, method));
    }
    if kind == "page"
        && app.app_id.as_deref() == Some("architect")
        && matches!(path.trim_end_matches('/'), "" | "/editor")
        && !dynamic::request_is_hx(Some(request))
    {
        let Some(html) = app_route_page_html(
            app,
            &route,
            target,
            render_request.actor_id,
            render_request.has_user,
            0,
            None,
            &render_request.csrf_token,
        ) else {
            return Some(http_text_response(
                500,
                "Internal Server Error",
                "declared app route failed to render\n",
            ));
        };
        // The task-status poll prepares stale previews after the dashboard renders.
        let html = architect_guard_preview_actions(app, &html, false);
        return Some(http_html_response_with_csrf(
            200,
            "OK",
            &html,
            method,
            Some(&render_request.csrf_token),
        ));
    }
    if kind == "page"
        && route.get("feature_id").and_then(Value::as_str).is_some()
        && dynamic::request_is_hx(Some(request))
    {
        let mut last_error = None;
        for attempt in 0..10 {
            match feature_runtime::render_feature_page_body(
                app,
                &route,
                target,
                render_request.actor_id,
                &render_request.csrf_token,
            ) {
                Ok(body) => {
                    let body = if app.app_id.as_deref() == Some("architect") {
                        let prepare_previews = path == "/tasks/status";
                        architect_guard_preview_actions(app, &body, prepare_previews)
                    } else {
                        body
                    };
                    return Some(http_html_response(200, "OK", &body, method));
                }
                Err(error) => {
                    last_error = Some(error);
                    if attempt < 9 {
                        std::thread::sleep(Duration::from_millis(50));
                    }
                }
            }
        }
        if let Some(error) = last_error {
            eprintln!("feature page fragment render failed: {error:?}");
        }
        return Some(http_text_response(
            500,
            "Internal Server Error",
            "feature page unavailable\n",
        ));
    }
    if let Some((status, status_text, body)) = route_request_middleware_failure(&route, request) {
        return Some(http_json_response(status, status_text, &body, method));
    }
    if kind == "action" {
        if let Some((status, status_text, body)) = route_request_hook_failure(&route, request) {
            return Some(http_json_response(status, status_text, &body, method));
        }
        let action_id = route
            .get("action_id")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let action_is_payment_provider_checkout_webhook = app
            .app_root
            .as_deref()
            .and_then(|app_root| {
                payment_provider::payment_provider_checkout_webhook_action_declared(
                    Path::new(app_root),
                    action_id,
                )
            })
            .or_else(|| {
                app.artifact_dir.as_deref().and_then(|artifact_dir| {
                    payment_provider::payment_provider_checkout_webhook_action_declared(
                        Path::new(artifact_dir),
                        action_id,
                    )
                })
            })
            .is_some();
        if method != "GET"
            && method != "HEAD"
            && !action_is_payment_provider_checkout_webhook
            && !dynamic::csrf_request_valid(request, dynamic::request_body_text(request).as_deref())
        {
            if action_id == "login" {
                return Some(login_error_response(
                    app,
                    request,
                    "Security verification failed",
                ));
            }
            return Some(http_text_response(
                403,
                "Forbidden",
                "Security verification failed\n",
            ));
        }
        if let Some(provider_id) = payment_provider_checkout_provider_for_action(app, action_id)
            && let Some(response) =
                payment_provider_checkout_action_response(app, request, action_id, &provider_id)
        {
            return Some(response);
        }
        if let Some(architect_action) =
            pharos_runtime_architect::architect_http_action_from_id(action_id)
        {
            use pharos_runtime_architect::ArchitectHttpAction;
            if app.app_id.as_deref() == Some("architect")
                && matches!(
                    architect_action,
                    ArchitectHttpAction::AutoBuildTask
                        | ArchitectHttpAction::ApproveApplyPlan
                        | ArchitectHttpAction::DeleteTask
                        | ArchitectHttpAction::UploadAttachment
                        | ArchitectHttpAction::UploadTranscript
                )
                && let Err(response) = architect_task_actor_allowed_response(app, request)
            {
                return Some(response);
            }
            return Some(match architect_action {
                ArchitectHttpAction::ChatGptConnect
                | ArchitectHttpAction::ChatGptStatus
                | ArchitectHttpAction::ChatGptTest
                | ArchitectHttpAction::ChatGptDisconnect
                | ArchitectHttpAction::ChatGptCancel => {
                    architect_chatgpt_response(app, request, method, architect_action)
                }
                ArchitectHttpAction::UploadAttachment => {
                    architect_upload_attachment_response(app, request, method)
                }
                ArchitectHttpAction::ReadImageAsset => {
                    architect_read_image_asset_response(app, request, method)
                }
                ArchitectHttpAction::UploadTranscript => {
                    architect_upload_transcript_response(app, request, method)
                }
                ArchitectHttpAction::SubmitBuiltinTask => {
                    architect_submit_builtin_task_response(app, request, method)
                }
                ArchitectHttpAction::AutoBuildTask => {
                    architect_auto_build_task_response(app, request, method)
                }
                ArchitectHttpAction::ApproveApplyPlan => {
                    architect_approve_apply_plan_response(app, request, method)
                }
                ArchitectHttpAction::DeleteTask => {
                    architect_delete_task_response(app, request, method)
                }
                ArchitectHttpAction::ConfigureLlmVendorConnection => {
                    architect_configure_llm_vendor_connection_response(app, request, method)
                }
                ArchitectHttpAction::RotateLlmVendorSecret => {
                    architect_rotate_llm_vendor_secret_response(app, request, method)
                }
                ArchitectHttpAction::TestLlmVendorConnection => {
                    architect_test_llm_vendor_connection_response(app, request, method)
                }
                ArchitectHttpAction::RevokeLlmVendorConnection => {
                    architect_revoke_llm_vendor_connection_response(app, request, method)
                }
                ArchitectHttpAction::CreateUser => {
                    architect_create_user_response(app, request, method)
                }
                ArchitectHttpAction::UpdateUser => {
                    architect_update_user_response(app, request, method)
                }
                ArchitectHttpAction::DeleteUser => {
                    architect_delete_user_response(app, request, method)
                }
                ArchitectHttpAction::SetUserPassword => {
                    architect_set_user_password_response(app, request, method)
                }
                ArchitectHttpAction::ImportSourceAppProject => {
                    architect_import_source_app_project_response(app, request, method)
                }
                ArchitectHttpAction::RenameEditorProject => {
                    architect_rename_editor_project_response(app, request, method)
                }
                ArchitectHttpAction::DuplicateEditorProject => {
                    architect_duplicate_editor_project_response(app, request, method)
                }
                ArchitectHttpAction::DeleteEditorProject => {
                    architect_delete_editor_project_response(app, request, method)
                }
                ArchitectHttpAction::RollbackEditorVersion => {
                    architect_rollback_editor_version_response(app, request, method)
                }
                ArchitectHttpAction::ViewEditorSourceFile => {
                    architect_view_editor_source_file_response(app, request, method)
                }
                ArchitectHttpAction::PrepareEditorSourceEdit => {
                    architect_prepare_editor_source_edit_response(app, request, method)
                }
                ArchitectHttpAction::PrepareEditorStructuredEdit => {
                    architect_prepare_editor_structured_edit_response(app, request, method)
                }
                ArchitectHttpAction::ApplyEditorSourceEdit => {
                    architect_apply_editor_source_edit_response(app, request, method)
                }
                ArchitectHttpAction::DownloadSource => {
                    architect_download_source_export_response(app, request, method)
                }
                ArchitectHttpAction::ViewGeneratedApp => {
                    architect_generated_app_preview_response(app, request, method)
                }
                ArchitectHttpAction::UploadPreviewImage => {
                    architect_upload_preview_image_response(app, request, method)
                }
                ArchitectHttpAction::ApplyPreviewEdit => {
                    architect_apply_preview_edit_response(app, request, method)
                }
            });
        }
        if action_id == "issue_business_invite" {
            return Some(ucal_issue_business_invite_response(
                app, request, method, path,
            ));
        }
        if action_id == "accept_invite" {
            return Some(ucal_accept_business_invite_response(
                app, request, method, path,
            ));
        }
        if route.get("feature_id").and_then(Value::as_str).is_some() {
            let actor_id = render_request.actor_id;
            if route
                .get("auth_gate")
                .and_then(Value::as_str)
                .is_some_and(|gate| gate == "session_required")
                && actor_id <= 0
            {
                let next_path = route
                    .get("action_id")
                    .and_then(Value::as_str)
                    .and_then(|action_id| {
                        feature_runtime::action_fallback_redirect(app, action_id).ok()
                    })
                    .map(|redirect| app_scope_path(app, &redirect))
                    .unwrap_or_else(|| path.to_owned());
                return Some(app_login_redirect(app, &next_path));
            }
            let outcome =
                match feature_runtime::execute_feature_action(app, &route, request, actor_id) {
                    Ok(outcome) => outcome,
                    Err(feature_runtime::FeatureRuntimeError::Database(error)) => {
                        return Some(database_error_response(error));
                    }
                    Err(feature_runtime::FeatureRuntimeError::DatabaseUnavailable) => {
                        return Some(database_error_response(
                            pharos_runtime_database::operations::DatabaseError::Unavailable,
                        ));
                    }
                    Err(feature_runtime::FeatureRuntimeError::ValidationReport(report)) => {
                        return Some(http_json_response(
                            422,
                            "Unprocessable Entity",
                            &report,
                            method,
                        ));
                    }
                    Err(feature_runtime::FeatureRuntimeError::InvalidInput(field)) => {
                        eprintln!(
                            "feature action invalid input: action_id={action_id} field={field}"
                        );
                        return Some(http_text_response(
                            422,
                            "Unprocessable Entity",
                            &format!("missing or invalid field: {field}\n"),
                        ));
                    }
                    Err(feature_runtime::FeatureRuntimeError::MissingRecord(_)) => {
                        return Some(http_text_response(
                            409,
                            "Conflict",
                            "required record unavailable\n",
                        ));
                    }
                    Err(feature_runtime::FeatureRuntimeError::Conflict(_)) => {
                        return Some(http_text_response(
                            409,
                            "Conflict",
                            "transaction conflict\n",
                        ));
                    }
                    Err(error) => {
                        eprintln!("feature action failed: {error:?}");
                        return Some(http_text_response(
                            500,
                            "Internal Server Error",
                            "feature action failed\n",
                        ));
                    }
                };
            if outcome.redirect_only {
                let redirect = app_scope_path(app, &outcome.redirect);
                return Some(http_route_redirect_for_request(request, &redirect));
            }
            if dynamic::request_is_hx(Some(request)) {
                let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "declared app response failed to render\n",
                    ));
                };
                let fragment_html = dynamic::csrf_inject_hidden_inputs(
                    artifact_root,
                    &outcome.fragment_html,
                    &render_request.csrf_token,
                );
                return Some(http_html_response(
                    outcome.status,
                    http::http_status_text(outcome.status),
                    &fragment_html,
                    method,
                ));
            }
            let redirect = app
                .base_path
                .as_deref()
                .filter(|base| !base.is_empty() && *base != "/")
                .map(|base| {
                    format!(
                        "{}{}",
                        base.trim_end_matches('/'),
                        outcome.redirect.as_str()
                    )
                })
                .unwrap_or(outcome.redirect);
            return Some(http_route_redirect(&redirect));
        }
        let action_id = route
            .get("action_id")
            .and_then(Value::as_str)
            .unwrap_or_default();
        if matches!(
            action_id,
            "complete_appointment"
                | "cancel_appointment"
                | "request_cancel_appointment"
                | "delete_appointment"
                | "assign_appointment_technician"
        ) {
            let appointment_id = path
                .strip_prefix("/appointments/")
                .and_then(|value| value.split('/').next())
                .and_then(|value| value.parse::<i64>().ok());
            if appointment_id.is_none_or(|id| id <= 0 || id > 1_000_000) {
                return Some(http_text_response(
                    422,
                    "Unprocessable Entity",
                    "invalid request\n",
                ));
            }
        }
        if route.get("action_id").and_then(Value::as_str) == Some("login") {
            let username = dynamic::request_form_value(request, "username").unwrap_or_default();
            let password = dynamic::request_form_value(request, "password").unwrap_or_default();
            let relational_user_id = if app_uses_relational_runtime_authority(app) {
                let app_root = match app.app_root.as_deref() {
                    Some(root) => root,
                    None => {
                        return Some(database_error_response(
                            pharos_runtime_database::operations::DatabaseError::InvalidContract,
                        ));
                    }
                };
                match database::dynamic_relational_authenticate_user(
                    Path::new(app_root),
                    app.runtime_conf_path.as_deref().map(Path::new),
                    app.app_id.as_deref(),
                    &username,
                    &password,
                ) {
                    Ok(value) => value,
                    Err(error) => return Some(database_error_response(error)),
                }
            } else {
                None
            };
            let json_user_id = app
                .state_path
                .as_deref()
                .filter(|_| app_uses_file_backed_runtime_state(app))
                .and_then(|state_path| stdfs::read_to_string(state_path).ok())
                .and_then(|text| serde_json::from_str::<Value>(&text).ok())
                .and_then(|root| {
                    root.get("users")
                        .and_then(Value::as_array)
                        .and_then(|users| {
                            users.iter().find_map(|user| {
                                (user.get("username").and_then(Value::as_str)
                                    == Some(username.as_str())
                                    && user
                                        .get("is_active")
                                        .and_then(Value::as_bool)
                                        .unwrap_or(true)
                                    && dynamic::verify_password_hash(
                                        user.get("password_hash")
                                            .and_then(Value::as_str)
                                            .unwrap_or_default(),
                                        &password,
                                        Some(&username),
                                    ))
                                .then(|| user.get("id").and_then(Value::as_i64))
                                .flatten()
                            })
                        })
                });
            let authenticated_user_id = if app_uses_relational_runtime_authority(app) {
                relational_user_id
            } else {
                json_user_id
            };
            let valid = authenticated_user_id.is_some();
            if !valid {
                if app_uses_relational_runtime_authority(app) {
                    let store = match checked_app_database_operations(app) {
                        Ok(value) => value,
                        Err(error) => return Some(database_error_response(error)),
                    };
                    match store.adapter.append_rate_limit_event(
                        &store.config,
                        "auth.login",
                        &username,
                        "invalid_credentials",
                    ) {
                        Ok(value) => value,
                        Err(error) => return Some(database_error_response(error)),
                    };
                }
                if !app_uses_relational_runtime_authority(app) {
                    let audit_status = dynamic::append_rate_limit_event_runtime_local(
                        app,
                        "auth.login",
                        &username,
                        "invalid_credentials",
                    );
                    if audit_status != 0 {
                        return Some(http_text_response(
                            503,
                            "Service Unavailable",
                            "security audit unavailable\n",
                        ));
                    }
                }
                return Some(login_error_response(
                    app,
                    request,
                    "Invalid username or password",
                ));
            }
            let session_token = match dynamic::random_secret_hex(32) {
                Ok(token) => token,
                Err(_) => {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "session unavailable\n",
                    ));
                }
            };
            let Some(session_hash) = native_session_token_hash(app, &session_token) else {
                return Some(http_text_response(
                    500,
                    "Internal Server Error",
                    "session unavailable\n",
                ));
            };
            let expires_at = timestamp_after_seconds_utc(604_800);
            let session_persisted = if app_uses_relational_runtime_authority(app) {
                let store = match checked_app_database_operations(app) {
                    Ok(value) => value,
                    Err(error) => return Some(database_error_response(error)),
                };
                let Some(user_id) = authenticated_user_id else {
                    return Some(database_error_response(
                        pharos_runtime_database::operations::DatabaseError::AccessDenied,
                    ));
                };
                match store.adapter.issue_session(
                    &store.config,
                    user_id,
                    &session_hash,
                    &expires_at,
                ) {
                    Ok(value) => value,
                    Err(error) => return Some(database_error_response(error)),
                };
                true
            } else if app_uses_file_backed_runtime_state(app)
                && let Some(state_path) = app.state_path.as_deref()
                && let Ok(text) = stdfs::read_to_string(state_path)
                && let Ok(mut root) = serde_json::from_str::<Value>(&text)
                && let Some(object) = root.as_object_mut()
            {
                let Some(user_id) = authenticated_user_id else {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "session unavailable\n",
                    ));
                };
                let sessions = object
                    .entry("sessions")
                    .or_insert_with(|| Value::Array(Vec::new()));
                if let Some(rows) = sessions.as_array_mut()
                    && !rows.iter().any(|row| {
                        row.get("session_token_hash").and_then(Value::as_str)
                            == Some(session_hash.as_str())
                    })
                {
                    rows.push(serde_json::json!({
                        "session_token_hash": session_hash,
                        "app_id": app.app_id,
                        "user_id": user_id,
                        "expires_at": expires_at,
                        "revoked_at": null
                    }));
                } else if let Some(row) = sessions.as_array_mut().and_then(|rows| {
                    rows.iter_mut().find(|row| {
                        row.get("session_token_hash").and_then(Value::as_str)
                            == Some(session_hash.as_str())
                    })
                }) {
                    row["user_id"] = Value::from(user_id);
                    row["revoked_at"] = Value::Null;
                }
                serde_json::to_string(&root).ok().is_some_and(|encoded| {
                    fs::write_text_file(Path::new(state_path), &encoded) == 0
                })
            } else {
                false
            };
            if !session_persisted {
                return Some(http_text_response(
                    500,
                    "Internal Server Error",
                    "session unavailable\n",
                ));
            }
            if app_uses_relational_runtime_authority(app)
                && let Some(user_id) = authenticated_user_id
            {
                let fallback_now = SystemTime::now()
                    .duration_since(UNIX_EPOCH)
                    .map(|value| value.as_secs())
                    .unwrap_or(0);
                let expires_at_epoch = runtime_timestamp_seconds(&expires_at)
                    .unwrap_or(fallback_now.saturating_add(604_800));
                if let Ok(cache_scope) = app_security_cache_scope(app) {
                    cache::session_cache_store(
                        &cache_scope,
                        user_id,
                        &session_hash,
                        expires_at_epoch,
                    );
                }
            }
            let default_landing_path = format!(
                "{}/",
                app_mount_prefix(app, &request.target, path).trim_end_matches('/')
            );
            let default_landing_path = if default_landing_path == "/" {
                "/".to_owned()
            } else {
                default_landing_path
            };
            let next_candidate =
                dynamic::request_form_value(request, "next").unwrap_or_else(|| {
                    feature_runtime::query_parameters(&request.target)
                        .ok()
                        .and_then(|params| {
                            params
                                .get("next")
                                .and_then(Value::as_str)
                                .map(ToOwned::to_owned)
                        })
                        .unwrap_or_default()
                });
            let (role_landing_path, override_next) = match authenticated_user_id {
                Some(actor_id) => {
                    match app_post_login_role_landing_path(app, actor_id, &default_landing_path) {
                        Ok(value) => value,
                        Err(error) => return Some(database_error_response(error)),
                    }
                }
                None => (default_landing_path.clone(), false),
            };
            let landing_path = if override_next {
                role_landing_path
            } else {
                app_safe_next_path(app, &next_candidate, &role_landing_path)
            };
            return Some(http_route_redirect_with_session(
                app,
                &landing_path,
                &request.target,
                request,
                &session_token,
            ));
        }
        if route.get("action_id").and_then(Value::as_str) == Some("password_reset_request")
            && !app_uses_file_backed_runtime_state(app)
        {
            let email = dynamic::request_form_value(request, "email").unwrap_or_default();
            let token = match dynamic::random_secret_hex(32) {
                Ok(token) => token,
                Err(_) => {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "token unavailable\n",
                    ));
                }
            };
            let token_hash = dynamic::hex_digest(&Sha256::digest(token.as_bytes()));
            let expires_at = timestamp_after_seconds_utc(3600);

            let store = match database::runtime_logical_app_store(app) {
                Ok(store) => store,
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            };
            let _issued = match pharos_runtime_database::account_tokens::issue_password_reset(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                &email,
                &token_hash,
                &token,
                &expires_at,
            ) {
                Ok(issued) => issued,
                Err(pharos_runtime_database::operations::DatabaseError::InvalidInput) => {
                    return Some(http_text_response(
                        422,
                        "Unprocessable Entity",
                        "invalid request\n",
                    ));
                }
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            };
            let params = json_commands::template_password_reset_sent_page_json(
                Path::new(app.artifact_dir.as_deref()?),
                None,
            )?;
            let response = dynamic::render_declared_page_response(
                Path::new(app.artifact_dir.as_deref()?),
                "password_reset_sent",
                &params,
            )
            .ok()?;
            return Some(response.into_bytes());
        }
        if route.get("action_id").and_then(Value::as_str) == Some("logout") {
            let session_token = request
                .cookie
                .as_deref()
                .and_then(|cookie| dynamic::dynamic_cookie_value(cookie, "pharos_session"));
            let session_hash = session_token
                .as_deref()
                .and_then(|token| native_session_token_hash(app, token));
            let session_revoked = if session_hash.is_none() {
                true
            } else if !app_uses_file_backed_runtime_state(app) {
                app_database_operations(app).is_some_and(|store| {
                    store
                        .adapter
                        .revoke_session(&store.config, session_hash.as_deref().unwrap_or_default())
                        .is_ok()
                })
            } else if app_uses_file_backed_runtime_state(app)
                && let Some(state_path) = app.state_path.as_deref()
                && let Ok(text) = stdfs::read_to_string(state_path)
                && let Ok(mut root) = serde_json::from_str::<Value>(&text)
                && let Some(rows) = root.get_mut("sessions").and_then(Value::as_array_mut)
            {
                for row in rows {
                    if row.get("session_token_hash").and_then(Value::as_str)
                        == session_hash.as_deref()
                        && let Some(object) = row.as_object_mut()
                    {
                        object.insert("revoked_at".to_owned(), Value::String("1".to_owned()));
                    }
                }
                serde_json::to_string(&root).ok().is_some_and(|encoded| {
                    fs::write_text_file(Path::new(state_path), &encoded) == 0
                })
            } else {
                false
            };
            if !session_revoked {
                return Some(http_text_response(
                    500,
                    "Internal Server Error",
                    "session revocation failed\n",
                ));
            }
            if let Some(session_hash) = session_hash.as_deref()
                && let Ok(cache_scope) = app_security_cache_scope(app)
            {
                pharos_runtime_security::local_session_cache_revoke(&cache_scope, session_hash);
                cache::session_cache_revoke_token(&cache_scope, session_hash);
            }
            return Some(http_route_redirect_clear_session(
                app,
                request,
                &app_login_location(app),
            ));
        }
        let action_id = route
            .get("action_id")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let missing = |field: &str| {
            dynamic::request_form_value(request, field).is_none_or(|value| value.trim().is_empty())
        };
        let invalid_without_required_fields = match action_id {
            "qr_upload_submit" => {
                missing("qr_image") && missing("qr_image_path") && missing("qr_payload")
            }
            "update_profile" => missing("full_name"),
            "create_booking" => missing("title") || missing("date") || missing("time"),
            "create_business" => missing("name"),
            "create_appointment" | "create_internal_appointment" => {
                app_uses_file_backed_runtime_state(app)
                    && (missing("service_id")
                        || missing("date")
                        || (missing("time") && missing("time_hour")))
            }
            "create_service" => missing("name"),
            "create_business_availability" | "update_business_availability" => {
                missing("start_time") || missing("end_time")
            }
            "create_technician" => missing("name") && missing("email"),
            "create_technician_availability" => missing("start_time") || missing("end_time"),
            _ => false,
        };
        let invalid_appointment_action = matches!(
            action_id,
            "complete_appointment"
                | "cancel_appointment"
                | "request_cancel_appointment"
                | "delete_appointment"
                | "assign_appointment_technician"
        ) && path
            .strip_prefix("/appointments/")
            .and_then(|value| value.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())
            .is_none_or(|appointment_id| appointment_id <= 0 || appointment_id > 1_000_000);
        if invalid_without_required_fields
            || (app_uses_file_backed_runtime_state(app) && invalid_appointment_action)
        {
            return Some(http_text_response(
                422,
                "Unprocessable Entity",
                "invalid request\n",
            ));
        }
        if let Some((provider_id, provider_action)) = app
            .app_root
            .as_deref()
            .and_then(|app_root| {
                payment_provider::payment_provider_lifecycle_action_declared(
                    Path::new(app_root),
                    action_id,
                )
            })
            .or_else(|| {
                app.artifact_dir.as_deref().and_then(|artifact_dir| {
                    payment_provider::payment_provider_lifecycle_action_declared(
                        Path::new(artifact_dir),
                        action_id,
                    )
                })
            })
        {
            let Some(app_root) = app.app_root.as_deref() else {
                return Some(http_text_response(
                    500,
                    "Internal Server Error",
                    "missing app root\n",
                ));
            };
            let owner_route_value =
                payment_provider::payment_provider_owner_route_value(Path::new(app_root), path)
                    .unwrap_or_default();
            let logical_store = if app_uses_file_backed_runtime_state(app) {
                None
            } else {
                match database::runtime_logical_app_store(app) {
                    Ok(store) => Some(store),
                    Err(_) => {
                        return Some(http_text_response(
                            503,
                            "Service Unavailable",
                            "database unavailable\n",
                        ));
                    }
                }
            };
            let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
                Ok(value) => value,
                Err(error) => return Some(database_error_response(error)),
            };
            let mut provider_root = if let Some(store) = &logical_store {
                let Some(management) =
                    pharos_runtime_payment::payment_provider_manifest_config(Path::new(app_root))
                else {
                    return Some(http_text_response(
                        422,
                        "Unprocessable Entity",
                        "payment provider declaration unavailable\n",
                    ));
                };
                match pharos_runtime_database::payment::payment_lifecycle_state(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    &management,
                    &owner_route_value,
                    &provider_id,
                    actor_id,
                ) {
                    Ok(root) => root,
                    Err(_) => {
                        return Some(http_text_response(
                            503,
                            "Service Unavailable",
                            "payment provider state unavailable\n",
                        ));
                    }
                }
            } else {
                let Some(state_path) = app.state_path.as_deref().map(Path::new) else {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "state storage unavailable\n",
                    ));
                };
                let Some(root) = json_commands::json_doc_load_file(state_path) else {
                    return Some(http_text_response(
                        404,
                        "Not Found",
                        "payment provider state unavailable\n",
                    ));
                };
                root
            };
            let provider_before = provider_root.clone();
            let mut provider_feedback_key: Option<&str> = None;
            let mut provider_feedback_message: Option<String> = None;
            let mut provider_redirect: Option<String> = None;
            let provider_result: Result<(), i32> = (|| {
                let root = &mut provider_root;
                match provider_action {
                    payment_provider::PaymentProviderLifecycleAction::Connect => {
                        let provider_account_label =
                            dynamic::request_form_value(request, "provider_account_label");
                        let connect_request = payment_provider::PaymentProviderConnectRequest {
                            provider_account_label: provider_account_label.as_deref(),
                        };
                        let redirect =
                            payment_provider::payment_provider_connect_start_with_request(
                                root,
                                Path::new(app_root),
                                app.runtime_conf_path.as_deref().map(Path::new),
                                &owner_route_value,
                                &provider_id,
                                actor_id,
                                connect_request,
                            )?;
                        provider_redirect = Some(redirect);
                        Ok(())
                    }
                    payment_provider::PaymentProviderLifecycleAction::TestCredentials => {
                        let test_request = payment_provider::PaymentProviderConnectRequest {
                            provider_account_label: None,
                        };
                        match payment_provider::payment_provider_test_connection(
                            root,
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &owner_route_value,
                            &provider_id,
                            actor_id,
                            test_request,
                        ) {
                            Ok(()) => {
                                provider_feedback_key =
                                    Some("owner_payment_provider_test_success_feedback");
                            }
                            Err((reason_code, reason_detail, _status)) => {
                                let prefix = payment_provider::payment_provider_copy_value(
                                    Path::new(app_root),
                                    "owner_payment_provider_test_failed_feedback",
                                )
                                .unwrap_or_else(|| "Connection test failed".to_owned());
                                provider_feedback_message =
                                    Some(format!("{prefix}: {reason_code} - {reason_detail}"));
                            }
                        }
                        Ok(())
                    }
                    payment_provider::PaymentProviderLifecycleAction::Callback => {
                        payment_provider::payment_provider_callback_complete(
                            root,
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &owner_route_value,
                            &provider_id,
                            &dynamic::request_query_value(request, "state").unwrap_or_default(),
                            &dynamic::request_query_value(request, "code").unwrap_or_default(),
                            actor_id,
                        )?;
                        Ok(())
                    }
                    payment_provider::PaymentProviderLifecycleAction::Refresh => {
                        match payment_provider::payment_provider_refresh(
                            root,
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &owner_route_value,
                            &provider_id,
                            actor_id,
                        ) {
                            Ok(()) => {
                                provider_feedback_key =
                                    Some("owner_payment_provider_refresh_success_feedback");
                                Ok(())
                            }
                            Err(_status) => {
                                provider_feedback_message = Some(
                                    payment_provider::payment_provider_copy_value(
                                        Path::new(app_root),
                                        "owner_payment_provider_refresh_failed_feedback",
                                    )
                                    .unwrap_or_else(|| {
                                        "No connected provider account is available to refresh"
                                            .to_owned()
                                    }),
                                );
                                Ok(())
                            }
                        }
                    }
                    payment_provider::PaymentProviderLifecycleAction::Disconnect => {
                        payment_provider::payment_provider_disconnect(
                            root,
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &owner_route_value,
                            &provider_id,
                            actor_id,
                        )?;
                        provider_feedback_key =
                            Some("owner_payment_provider_disconnected_feedback");
                        Ok(())
                    }
                    payment_provider::PaymentProviderLifecycleAction::ConfigureCredentials => {
                        let fields = payment_provider::payment_provider_declared_credential_fields(
                            Path::new(app_root),
                            &provider_id,
                        )
                        .into_iter()
                        .filter_map(|field| {
                            dynamic::request_form_value(request, &field.name)
                                .map(|value| (field.name, value))
                        })
                        .collect();
                        payment_provider::payment_provider_configure_credentials(
                            root,
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &owner_route_value,
                            &provider_id,
                            actor_id,
                            payment_provider::PaymentProviderCredentialSubmission { fields },
                        )?;
                        provider_feedback_key =
                            Some("owner_payment_provider_credentials_saved_feedback");
                        Ok(())
                    }
                    payment_provider::PaymentProviderLifecycleAction::RevokeCredentials => {
                        payment_provider::payment_provider_revoke_credentials(
                            root,
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &owner_route_value,
                            &provider_id,
                            actor_id,
                        )?;
                        provider_feedback_key =
                            Some("owner_payment_provider_credentials_deleted_feedback");
                        Ok(())
                    }
                    payment_provider::PaymentProviderLifecycleAction::SetCheckoutMode => {
                        payment_provider::payment_provider_set_checkout_mode(
                            root,
                            Path::new(app_root),
                            &owner_route_value,
                            &provider_id,
                            actor_id,
                            &dynamic::request_form_value(request, "checkout_mode")
                                .unwrap_or_default(),
                        )?;
                        provider_feedback_key =
                            Some("owner_payment_provider_action_completed_feedback");
                        Ok(())
                    }
                }
            })();
            if let Err(status) = provider_result {
                return Some(http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "invalid request\n",
                ));
            }
            if let Some(store) = &logical_store {
                let Some(management) =
                    pharos_runtime_payment::payment_provider_manifest_config(Path::new(app_root))
                else {
                    return Some(http_text_response(
                        422,
                        "Unprocessable Entity",
                        "payment provider declaration unavailable\n",
                    ));
                };
                let committed_store = match with_action_effects(
                    app,
                    request,
                    action_id,
                    database::LogicalAppStore {
                        adapter: store.adapter.clone(),
                        config: store.config.clone(),
                        schema: store.schema.clone(),
                    },
                ) {
                    Ok(store) => store,
                    Err(status) => {
                        return Some(http_text_response(
                            status,
                            http::http_status_text(status),
                            "payment effects unavailable\n",
                        ));
                    }
                };
                if pharos_runtime_database::payment::apply_payment_lifecycle_delta(
                    committed_store.adapter.as_ref(),
                    &committed_store.config,
                    &committed_store.schema,
                    &management,
                    actor_id,
                    &provider_before,
                    &provider_root,
                )
                .is_err()
                {
                    return Some(http_text_response(
                        409,
                        "Conflict",
                        "payment provider update conflict\n",
                    ));
                }
            } else if app
                .state_path
                .as_deref()
                .map(Path::new)
                .is_none_or(|state_path| {
                    payment_provider::persist_payment_provider_state_or_500(
                        &provider_root,
                        state_path,
                    )
                    .is_err()
                })
            {
                return Some(http_text_response(
                    503,
                    "Service Unavailable",
                    "payment provider state unavailable\n",
                ));
            }
            if let Some(redirect) = provider_redirect {
                return Some(http_route_redirect_for_request(request, &redirect));
            }
            if dynamic::request_is_hx(Some(request)) {
                if matches!(
                    provider_action,
                    payment_provider::PaymentProviderLifecycleAction::TestCredentials
                ) {
                    let feedback = provider_feedback_message.unwrap_or_else(|| {
                        provider_feedback_key
                            .and_then(|key| {
                                payment_provider::payment_provider_copy_value(
                                    Path::new(app_root),
                                    key,
                                )
                            })
                            .unwrap_or_else(|| "Payment provider action completed".to_owned())
                    });
                    return Some(payment_provider_feedback_message_response(app, &feedback));
                }
                if let Some(setup_path) = payment_provider::payment_provider_setup_path(
                    Path::new(app_root),
                    &owner_route_value,
                    &provider_id,
                ) && let Some(setup_route) = matched_app_route(app, "GET", &setup_path)
                {
                    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
                        Ok(value) => value,
                        Err(error) => return Some(database_error_response(error)),
                    };
                    let feedback = provider_feedback_message.or_else(|| {
                        provider_feedback_key.and_then(|key| {
                            payment_provider::payment_provider_copy_value(Path::new(app_root), key)
                        })
                    });
                    let mut extra_params = serde_json::Map::new();
                    if let Some(feedback) = feedback {
                        extra_params.insert(
                            "payment_provider_feedback_message".to_owned(),
                            Value::String(feedback),
                        );
                    }
                    if setup_route
                        .get("feature_id")
                        .and_then(Value::as_str)
                        .is_none()
                        && setup_route.get("page_id").and_then(Value::as_str)
                            == Some("payment_provider_setup")
                    {
                        let body = (|| {
                            let artifact_root = app.artifact_dir.as_deref().map(Path::new)?;
                            let page_relative = json_commands::declared_page_relative_path(
                                artifact_root,
                                "payment_provider_setup",
                            )?;
                            let page_spec = json_commands::json_doc_load_file(
                                &artifact_root.join(page_relative),
                            )?;
                            let template_relative =
                                page_spec.get("template_file").and_then(Value::as_str)?;
                            let template_path = artifact_root.join(template_relative);
                            let state_root = &provider_root;
                            let params_json =
                                json_commands::dynamic_payment_provider_setup_page_params_from_root_json(
                                    state_root,
                                    &owner_route_value,
                                    artifact_root,
                                )?;
                            let mut params = serde_json::from_str::<Value>(&params_json)
                                .ok()?
                                .as_object()?
                                .clone();
                            for (key, value) in extra_params.clone() {
                                params.insert(key, value);
                            }
                            let body = json_commands::template_render_file(
                                &template_path,
                                &Value::Object(params),
                            )?;
                            let scoped_body = json_commands::template_apply_base_path(
                                &body,
                                app.base_path.as_deref(),
                            )?;
                            Some(dynamic::csrf_inject_hidden_inputs(
                                artifact_root,
                                &scoped_body,
                                &render_request.csrf_token,
                            ))
                        })();
                        return Some(match body {
                            Some(body) => http_html_response(200, "OK", &body, method),
                            None => http_text_response(
                                500,
                                "Internal Server Error",
                                "payment provider setup unavailable\n",
                            ),
                        });
                    }
                    return Some(
                        match feature_runtime::render_feature_page_body_with_error_and_params(
                            app,
                            &setup_route,
                            &setup_path,
                            actor_id,
                            &render_request.csrf_token,
                            None,
                            extra_params,
                        ) {
                            Ok(body) => http_html_response(200, "OK", &body, method),
                            Err(error) => {
                                eprintln!(
                                    "payment provider setup fragment render failed: {error:?}"
                                );
                                http_text_response(
                                    500,
                                    "Internal Server Error",
                                    "payment provider setup unavailable\n",
                                )
                            }
                        },
                    );
                }
                return Some(payment_provider_feedback_response(
                    app,
                    provider_feedback_key
                        .unwrap_or("owner_payment_provider_action_completed_feedback"),
                ));
            }
            let redirect = payment_provider::payment_provider_return_path(
                Path::new(app_root),
                &owner_route_value,
            )
            .unwrap_or_else(|| "/".to_owned());
            return Some(http_route_redirect(&app_scope_path(app, &redirect)));
        }
        if let Some(provider_id) = app
            .app_root
            .as_deref()
            .and_then(|app_root| {
                payment_provider::payment_provider_checkout_webhook_action_declared(
                    Path::new(app_root),
                    action_id,
                )
            })
            .or_else(|| {
                app.artifact_dir.as_deref().and_then(|artifact_dir| {
                    payment_provider::payment_provider_checkout_webhook_action_declared(
                        Path::new(artifact_dir),
                        action_id,
                    )
                })
            })
        {
            let Some(app_root) = app.app_root.as_deref() else {
                return Some(http_text_response(
                    500,
                    "Internal Server Error",
                    "missing app root\n",
                ));
            };
            if !app_uses_file_backed_runtime_state(app) {
                let result = app_database_operations(app)
                    .ok_or(503)
                    .and_then(|store| {
                        with_action_effects(app, request, action_id, store)
                            .map_err(|status| status as i32)
                    })
                    .and_then(|store| {
                        payment_provider::database_checkout_webhook_complete(
                            Path::new(app_root),
                            app.runtime_conf_path.as_deref().map(Path::new),
                            &store,
                            &provider_id,
                            &request.headers,
                            &request.body,
                        )
                    });
                return Some(match result {
                    Ok(()) => http_json_response(200, "OK", r#"{"received":true}"#, method),
                    Err(status) => http_text_response(
                        status as u16,
                        http::http_status_text(status as u16),
                        "payment event unavailable\n",
                    ),
                });
            }
            let Some(state_path) = app.state_path.as_deref() else {
                return Some(http_text_response(
                    500,
                    "Internal Server Error",
                    "missing state path\n",
                ));
            };
            let result: Result<(), i32> = (|| {
                let _guard = state_store::StateMutationGuard::acquire(Path::new(state_path))
                    .map_err(|_| 503)?;
                let mut root =
                    json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                payment_provider::payment_provider_checkout_webhook_complete(
                    &mut root,
                    Path::new(app_root),
                    app.runtime_conf_path.as_deref().map(Path::new),
                    &provider_id,
                    &request.headers,
                    &request.body,
                )?;
                payment_provider::persist_payment_provider_state_or_500(
                    &root,
                    Path::new(state_path),
                )
            })();
            return Some(match result {
                Ok(()) => http_json_response(200, "OK", r#"{"received":true}"#, method),
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "invalid request\n",
                ),
            });
        }
        if let Some(provider_id) = payment_provider_checkout_provider_for_action(app, action_id)
            && let Some(response) =
                payment_provider_checkout_action_response(app, request, action_id, &provider_id)
        {
            return Some(response);
        }
        if matches!(
            action_id,
            "create_appointment" | "create_internal_appointment"
        ) && !app_uses_file_backed_runtime_state(app)
        {
            let result = (|| {
                let store = database::runtime_logical_app_store(app).map_err(|_| 503)?;
                let store = with_action_effects(app, request, action_id, store)?;
                let slug = path
                    .strip_prefix("/business/")
                    .or_else(|| path.strip_prefix("/businesses/"))
                    .and_then(|value| value.split('/').next())
                    .ok_or(422)?;
                let service_id = dynamic::request_form_value(request, "service_id")
                    .and_then(|value| value.parse::<i64>().ok())
                    .or_else(|| {
                        path.split("/book/")
                            .nth(1)
                            .and_then(|value| value.trim_matches('/').parse::<i64>().ok())
                    })
                    .ok_or(422)?;
                let date = dynamic::request_form_value(request, "date").unwrap_or_default();
                let direct_time = dynamic::request_form_value(request, "time").unwrap_or_default();
                let hour = dynamic::request_form_value(request, "time_hour").unwrap_or_default();
                let minute =
                    dynamic::request_form_value(request, "time_minute").unwrap_or_default();
                let period =
                    dynamic::request_form_value(request, "time_period").unwrap_or_default();
                let time =
                    normalized_booking_time(&direct_time, &hour, &minute, &period).ok_or(422)?;
                let notes = dynamic::request_form_value(request, "notes").unwrap_or_default();
                let technician =
                    dynamic::request_form_value(request, "technician_id").unwrap_or_default();
                let technician_id = match technician.as_str() {
                    "" | "0" => None,
                    value => Some(value.parse::<i64>().map_err(|_| 422)?),
                };
                let option = dynamic::request_form_value(request, "booking_option_index")
                    .unwrap_or_default();
                let booking_option_index = if option.is_empty() {
                    None
                } else {
                    Some(option.parse::<usize>().map_err(|_| 422)?)
                };
                let key = dynamic::request_form_value(request, "idempotency_key")
                    .filter(|value| !value.is_empty());
                business::create_appointment(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    &business::AppointmentCreate {
                        business_slug: slug,
                        service_id,
                        actor_user_id: (active_session_user_id(app, request.cookie.as_deref()))
                            .map_err(database_operation_http_status)?,
                        technician_id,
                        booking_option_index,
                        date: &date,
                        time: &time,
                        notes: &notes,
                        internal: action_id == "create_internal_appointment",
                        idempotency_key: key.as_deref(),
                    },
                )
                .map_err(|error| match error {
                    pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                    pharos_runtime_database::operations::DatabaseError::MissingRecord => 404,
                    pharos_runtime_database::operations::DatabaseError::AccessDenied => 403,
                    pharos_runtime_database::operations::DatabaseError::CapacityExceeded
                    | pharos_runtime_database::operations::DatabaseError::Conflict => 409,
                    _ => 503,
                })
            })();
            return Some(match result {
                Ok(_) => {
                    let redirect = dynamic::request_form_value(request, "return_to")
                        .filter(|value| value.starts_with('/') && !value.starts_with("//"))
                        .unwrap_or_else(|| "/appointments/".to_owned());
                    http_route_redirect_for_request(request, &app_scope_path(app, &redirect))
                }
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "booking unavailable\n",
                ),
            });
        }
        if matches!(
            action_id,
            "complete_appointment"
                | "cancel_appointment"
                | "request_cancel_appointment"
                | "delete_appointment"
        ) && !app_uses_file_backed_runtime_state(app)
        {
            let result = (|| {
                let store = database::runtime_logical_app_store(app).map_err(|_| 503)?;
                let store = with_action_effects(app, request, action_id, store)?;
                let appointment_id = path
                    .strip_prefix("/appointments/")
                    .and_then(|value| value.split('/').next())
                    .and_then(|value| value.parse::<i64>().ok())
                    .ok_or(422)?;
                let change = match action_id {
                    "complete_appointment" => business::AppointmentChange::Complete,
                    "cancel_appointment" => business::AppointmentChange::Cancel,
                    "request_cancel_appointment" => business::AppointmentChange::RequestCancel,
                    "delete_appointment" => business::AppointmentChange::Delete,
                    _ => return Err(422),
                };
                business::change_appointment(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    (active_session_user_id(app, request.cookie.as_deref()))
                        .map_err(database_operation_http_status)?,
                    appointment_id,
                    change,
                )
                .map_err(|error| match error {
                    pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                    pharos_runtime_database::operations::DatabaseError::MissingRecord => 404,
                    pharos_runtime_database::operations::DatabaseError::AccessDenied => 403,
                    pharos_runtime_database::operations::DatabaseError::Conflict => 409,
                    _ => 503,
                })
            })();
            return Some(match result {
                Ok(()) => {
                    http_route_redirect_for_request(request, &app_scope_path(app, "/appointments/"))
                }
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "appointment update unavailable\n",
                ),
            });
        }
        if matches!(
            action_id,
            "assign_appointment_technician" | "reschedule_appointment"
        ) && !app_uses_file_backed_runtime_state(app)
        {
            let result = (|| {
                let store = with_action_effects(
                    app,
                    request,
                    action_id,
                    app_database_operations(app).ok_or(503)?,
                )?;
                let appointment_id = dynamic::request_form_value(request, "appointment_id")
                    .and_then(|value| value.parse::<i64>().ok())
                    .or_else(|| {
                        path.strip_prefix("/appointments/")
                            .and_then(|value| value.split('/').next())
                            .and_then(|value| value.parse::<i64>().ok())
                    })
                    .ok_or(422)?;
                let technician_id = dynamic::request_form_value(request, "technician_id")
                    .map(|value| value.parse::<i64>().map_err(|_| 422))
                    .transpose()?;
                let timestamp = dynamic::request_form_value(request, "start_time")
                    .map(|value| business::appointment_timestamp_parts(&value).map_err(|_| 422))
                    .transpose()?;
                let date = dynamic::request_form_value(request, "date")
                    .or_else(|| timestamp.as_ref().map(|value| value.0.clone()));
                let time = dynamic::request_form_value(request, "time")
                    .or_else(|| timestamp.as_ref().map(|value| value.1.clone()));
                let notes = dynamic::request_form_value(request, "notes");
                if action_id == "assign_appointment_technician" && technician_id.is_none()
                    || action_id == "reschedule_appointment" && (date.is_none() || time.is_none())
                {
                    return Err(422);
                }
                business::move_appointment(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    business::AppointmentMove {
                        actor_id: (active_session_user_id(app, request.cookie.as_deref()))
                            .map_err(database_operation_http_status)?,
                        appointment_id,
                        technician_id,
                        date: date.as_deref(),
                        time: time.as_deref(),
                        notes: notes.as_deref(),
                    },
                )
                .map_err(|error| match error {
                    pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                    pharos_runtime_database::operations::DatabaseError::MissingRecord => 404,
                    pharos_runtime_database::operations::DatabaseError::AccessDenied => 403,
                    pharos_runtime_database::operations::DatabaseError::Conflict
                    | pharos_runtime_database::operations::DatabaseError::CapacityExceeded => 409,
                    _ => 503,
                })
            })();
            return Some(match result {
                Ok(()) => {
                    http_route_redirect_for_request(request, &app_scope_path(app, "/appointments/"))
                }
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "appointment move unavailable\n",
                ),
            });
        }
        if matches!(action_id, "update_booking" | "delete_booking")
            && !app_uses_file_backed_runtime_state(app)
        {
            let result = (|| {
                let store = with_action_effects(
                    app,
                    request,
                    action_id,
                    app_database_operations(app).ok_or(503)?,
                )?;
                let booking_id = dynamic::request_form_value(request, "booking_id")
                    .and_then(|value| value.parse::<i64>().ok())
                    .or_else(|| {
                        path.strip_prefix("/bookings/")
                            .and_then(|value| value.split('/').next())
                            .and_then(|value| value.parse::<i64>().ok())
                    })
                    .ok_or(422)?;
                let input: Map<String, Value> = [
                    "title",
                    "description",
                    "location",
                    "start_time",
                    "end_time",
                    "status",
                ]
                .into_iter()
                .filter_map(|field| {
                    dynamic::request_form_value(request, field)
                        .map(|value| (field.to_owned(), Value::String(value)))
                })
                .collect();
                business::change_personal_booking(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    (active_session_user_id(app, request.cookie.as_deref()))
                        .map_err(database_operation_http_status)?,
                    booking_id,
                    (action_id == "update_booking").then_some(&input),
                )
                .map_err(|error| match error {
                    pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                    pharos_runtime_database::operations::DatabaseError::MissingRecord => 404,
                    pharos_runtime_database::operations::DatabaseError::AccessDenied => 403,
                    pharos_runtime_database::operations::DatabaseError::Conflict => 409,
                    _ => 503,
                })
            })();
            return Some(match result {
                Ok(()) => {
                    http_route_redirect_for_request(request, &app_scope_path(app, "/bookings/"))
                }
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "booking change unavailable\n",
                ),
            });
        }
        if action_id == "create_booking" && !app_uses_file_backed_runtime_state(app) {
            let result = (|| {
                let store = database::runtime_logical_app_store(app).map_err(|_| 503)?;
                let store = with_action_effects(app, request, action_id, store)?;
                let title = dynamic::request_form_value(request, "title").unwrap_or_default();
                let date = dynamic::request_form_value(request, "date").unwrap_or_default();
                let time = dynamic::request_form_value(request, "time").unwrap_or_default();
                business::create_personal_booking(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    (active_session_user_id(app, request.cookie.as_deref()))
                        .map_err(database_operation_http_status)?,
                    &title,
                    &date,
                    &time,
                )
                .map_err(|error| match error {
                    pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                    pharos_runtime_database::operations::DatabaseError::Conflict => 409,
                    _ => 503,
                })
            })();
            return Some(match result {
                Ok(_) => {
                    http_route_redirect_for_request(request, &app_scope_path(app, "/bookings/"))
                }
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "booking unavailable\n",
                ),
            });
        }
        if action_id == "run_selected_appointment_maintenance"
            && !app_uses_file_backed_runtime_state(app)
        {
            let result = (|| {
                let store = with_action_effects(
                    app,
                    request,
                    action_id,
                    app_database_operations(app).ok_or(503u16)?,
                )?;
                let chosen = |field| {
                    dynamic::request_form_value(request, field)
                        .is_some_and(|value| !value.trim().is_empty())
                };
                let results = business::maintain_appointments(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    (active_session_user_id(app, request.cookie.as_deref()))
                        .map_err(database_operation_http_status)?,
                    chosen("dedupe_appointments"),
                    chosen("reassign_appointments_to_technicians"),
                    chosen("reconcile_future_appointments"),
                )
                .map_err(database_operation_http_status)?;
                if dynamic::request_is_hx(Some(request)) {
                    let root = app.app_root.as_deref().map(Path::new).ok_or(503u16)?;
                    let html = business::appointment_maintenance_result_html(root, &results)
                        .ok_or(500u16)?;
                    Ok(http_html_response(200, "OK", &html, method))
                } else {
                    Ok(http_route_redirect_for_request(
                        request,
                        &app_scope_path(app, "/appointments/diagnose/"),
                    ))
                }
            })();
            return Some(match result {
                Ok(response) => response,
                Err(status) => http_text_response(
                    status,
                    http::http_status_text(status),
                    "appointment maintenance unavailable\n",
                ),
            });
        }
        if action_id == "update_profile" && !app_uses_file_backed_runtime_state(app) {
            let result = (|| {
                let store = database::runtime_logical_app_store(app).map_err(|_| 503)?;
                let store = with_action_effects(app, request, action_id, store)?;
                let mut input = Map::new();
                for name in ["full_name", "phone_number", "address", "payment_preference"] {
                    if let Some(value) = dynamic::request_form_value(request, name) {
                        input.insert(name.to_owned(), Value::String(value));
                    }
                }
                if let Some(age) = dynamic::request_form_value(request, "age") {
                    input.insert(
                        "age".to_owned(),
                        if age.is_empty() {
                            Value::Null
                        } else {
                            Value::from(age.parse::<i64>().map_err(|_| 422)?)
                        },
                    );
                }
                pharos_runtime_database::account_tokens::update_account_profile(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    (active_session_user_id(app, request.cookie.as_deref()))
                        .map_err(|error| database_operation_http_status(error) as i32)?,
                    &input,
                )
                .map_err(|error| match error {
                    pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                    pharos_runtime_database::operations::DatabaseError::Conflict => 409,
                    pharos_runtime_database::operations::DatabaseError::MissingRecord => 404,
                    _ => 503,
                })
            })();
            return Some(match result {
                Ok(()) => {
                    http_route_redirect_for_request(request, &app_scope_path(app, "/profile/"))
                }
                Err(status) => http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "profile update unavailable\n",
                ),
            });
        }
        if !app_uses_file_backed_runtime_state(app)
            && pharos_runtime_business::is_catalog_action(action_id)
        {
            return Some(business_catalog_action_response(
                app, request, path, action_id,
            ));
        }
        if !app_uses_file_backed_runtime_state(app)
            && pharos_runtime_business::is_business_identity_action(action_id)
        {
            return Some(business_identity_action_response(
                app, request, path, action_id,
            ));
        }
        if action_id == "password_reset_complete" && !app_uses_file_backed_runtime_state(app) {
            let token = path
                .strip_prefix("/accounts/password-reset/complete/")
                .and_then(|value| value.split('/').next())
                .unwrap_or_default();
            let password = dynamic::request_form_value(request, "password1")
                .or_else(|| dynamic::request_form_value(request, "password"))
                .unwrap_or_default();
            let confirmation = dynamic::request_form_value(request, "password2")
                .or_else(|| dynamic::request_form_value(request, "password_confirm"))
                .unwrap_or_default();
            if password != confirmation || password.len() < 8 {
                return Some(http_text_response(
                    422,
                    "Unprocessable Entity",
                    "invalid request\n",
                ));
            }
            let password_hash = match dynamic::hash_password(&password) {
                Ok(value) => value,
                Err(_) => {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "credential unavailable\n",
                    ));
                }
            };

            let store = match database::runtime_logical_app_store(app) {
                Ok(value) => value,
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            };
            let token_hash = dynamic::hex_digest(&Sha256::digest(token.as_bytes()));
            let claimed = pharos_runtime_database::account_tokens::complete_password_reset(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                &token_hash,
                &password_hash,
                &current_timestamp_utc(),
            );
            match claimed {
                Ok(Some(user_id)) => {
                    if let Ok(cache_scope) = app_security_cache_scope(app) {
                        cache::session_cache_revoke_user(&cache_scope, user_id);
                        pharos_runtime_security::local_session_cache_revoke_user(
                            &cache_scope,
                            user_id,
                        );
                    }
                    return Some(app_fragment_response(
                        app,
                        "templates/registration/password_reset_complete_done.body.html",
                        serde_json::json!({}),
                        method,
                    ));
                }
                Ok(None) => {
                    return Some(http_text_response(
                        404,
                        "Not Found",
                        "reset token unavailable\n",
                    ));
                }
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            }
        }
        if action_id == "verify_email" && !app_uses_file_backed_runtime_state(app) {
            let token = path
                .strip_prefix("/accounts/verify-email/")
                .and_then(|value| value.split('/').next())
                .unwrap_or_default();

            let store = match database::runtime_logical_app_store(app) {
                Ok(value) => value,
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            };
            let token_hash = dynamic::hex_digest(&Sha256::digest(token.as_bytes()));
            match pharos_runtime_database::account_tokens::complete_email_verification(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                &token_hash,
                &current_timestamp_utc(),
            ) {
                Ok(Some(_)) => {
                    return Some(http_route_redirect_for_request(
                        request,
                        &app_scope_path(app, path),
                    ));
                }
                Ok(None) => {
                    return Some(http_text_response(
                        404,
                        "Not Found",
                        "verification token unavailable\n",
                    ));
                }
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            }
        }
        if action_id == "register_account" && !app_uses_file_backed_runtime_state(app) {
            let username = dynamic::request_form_value(request, "username").unwrap_or_default();
            let email = dynamic::request_form_value(request, "email").unwrap_or_default();
            let password = dynamic::request_form_value(request, "password").unwrap_or_default();
            let confirmation =
                dynamic::request_form_value(request, "password_confirm").unwrap_or_default();
            if password.len() < 8
                || password != confirmation
                || !json_commands::generated_surface_text_is_email(&email)
            {
                return Some(http_text_response(
                    422,
                    "Unprocessable Entity",
                    "invalid request\n",
                ));
            }
            let password_hash = match dynamic::hash_password(&password) {
                Ok(value) => value,
                Err(_) => {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "credential unavailable\n",
                    ));
                }
            };

            let store = match database::runtime_logical_app_store(app) {
                Ok(value) => value,
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            };
            match pharos_runtime_database::account_tokens::register_account(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                &username,
                &email,
                &password_hash,
            ) {
                Ok(_) => {
                    return Some(http_route_redirect_for_request(
                        request,
                        &app_scope_path(app, path),
                    ));
                }
                Err(pharos_runtime_database::operations::DatabaseError::InvalidInput) => {
                    return Some(http_text_response(
                        422,
                        "Unprocessable Entity",
                        "invalid request\n",
                    ));
                }
                Err(pharos_runtime_database::operations::DatabaseError::Conflict) => {
                    return Some(http_text_response(
                        409,
                        "Conflict",
                        "account already exists\n",
                    ));
                }
                Err(_) => {
                    return Some(http_text_response(
                        503,
                        "Service Unavailable",
                        "database unavailable\n",
                    ));
                }
            }
        }
        if !app_uses_file_backed_runtime_state(app)
            && dynamic::is_declarative_document_action(app, action_id)
        {
            return Some(
                match dynamic::dynamic_execute_declarative_action(
                    app,
                    app.state_path.as_deref().map(Path::new),
                    request,
                    action_id,
                ) {
                    Ok(dynamic::DeclarativeActionResponse::Redirect(location)) => {
                        http_route_redirect_for_request(request, &app_scope_path(app, &location))
                    }
                    Ok(dynamic::DeclarativeActionResponse::Json(status, body)) => {
                        http_json_response(
                            status,
                            http_reason_phrase(status),
                            &body.to_string(),
                            method,
                        )
                    }
                    Err(status) => http_text_response(
                        status as u16,
                        http::http_status_text(status as u16),
                        "invalid request\n",
                    ),
                },
            );
        }
        if app_uses_file_backed_runtime_state(app)
            && let (Some(action_id), Some(state_path)) = (
                route.get("action_id").and_then(Value::as_str),
                app.state_path.as_deref(),
            )
        {
            let mut maintenance_results: Option<Vec<String>> = None;
            let result = match action_id {
                "register_account" => {
                    dynamic::handle_register_account_action(Path::new(state_path), request)
                        .map(|_| ())
                }
                "create_booking" => (|| {
                    let title = dynamic::request_form_value(request, "title")
                        .map(|value| value.trim().to_owned())
                        .filter(|value| !value.is_empty())
                        .ok_or(422)?;
                    let date = dynamic::request_form_value(request, "date")
                        .map(|value| value.trim().to_owned())
                        .filter(|value| json_commands::generated_surface_text_is_date(value))
                        .ok_or(422)?;
                    let time = dynamic::request_form_value(request, "time")
                        .map(|value| value.trim().to_owned())
                        .filter(|value| json_commands::generated_surface_text_is_time(value))
                        .map(|value| value.get(0..5).unwrap_or("").to_owned())
                        .filter(|value| !value.is_empty())
                        .ok_or(422)?;
                    let mut root =
                        json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                    let booking_id = root
                        .get("bookings")
                        .and_then(Value::as_array)
                        .and_then(|rows| {
                            rows.iter()
                                .filter_map(|row| row.get("id").and_then(Value::as_i64))
                                .max()
                        })
                        .unwrap_or(0)
                        + 1;
                    let rows = root
                        .as_object_mut()
                        .and_then(|object| {
                            object
                                .entry("bookings".to_owned())
                                .or_insert_with(|| Value::Array(Vec::new()))
                                .as_array_mut()
                        })
                        .ok_or(500)?;
                    rows.push(serde_json::json!({
                        "id": booking_id,
                        "user_id": (active_session_user_id(app, request.cookie.as_deref())).map_err(|error| database_operation_http_status(error) as i32)?,
                        "title": title,
                        "date": date,
                        "time": time,
                        "status": "confirmed"
                    }));
                    business::persist_management_state_or_500_local(&root, Path::new(state_path))
                })(),
                "accept_invite" => {
                    let token = path
                        .strip_prefix("/accounts/invite/")
                        .and_then(|value| value.split('/').next())
                        .unwrap_or_default();
                    (|| {
                        let mut form = serde_json::Map::new();
                        form.insert("token_hash".to_owned(), Value::String(token.to_owned()));
                        form.insert("user_id".to_owned(), Value::from(1_i64));
                        let mut root =
                            json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                        let result = business::dynamic_handle_business_identity_action(
                            &mut root,
                            "accept_invite",
                            &form,
                        )
                        .ok_or(404)?;
                        result.and_then(|_| {
                            business::persist_management_state_or_500_local(
                                &root,
                                Path::new(state_path),
                            )
                        })
                    })()
                }
                "run_selected_appointment_maintenance" => {
                    let dedupe = dynamic::request_form_value(request, "dedupe_appointments")
                        .is_some_and(|value| !value.trim().is_empty());
                    let reassign = dynamic::request_form_value(
                        request,
                        "reassign_appointments_to_technicians",
                    )
                    .is_some_and(|value| !value.trim().is_empty());
                    let reconcile =
                        dynamic::request_form_value(request, "reconcile_future_appointments")
                            .is_some_and(|value| !value.trim().is_empty());
                    (|| {
                        let mut root =
                            json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                        let results = business::run_selected_appointment_maintenance(
                            &mut root, dedupe, reassign, reconcile,
                        );
                        maintenance_results = Some(results);
                        business::persist_management_state_or_500_local(
                            &root,
                            Path::new(state_path),
                        )
                    })()
                }
                "create_appointment" | "create_internal_appointment" => (|| {
                    let mut form = serde_json::Map::new();
                    for field in [
                        "csrf_token",
                        "business_id",
                        "service_id",
                        "booking_option_index",
                        "technician_id",
                        "date",
                        "time",
                        "notes",
                    ] {
                        if let Some(value) = dynamic::request_form_value(request, field) {
                            form.insert(field.to_owned(), Value::String(value));
                        }
                    }
                    if !form.contains_key("business_id") {
                        let slug = path
                            .strip_prefix("/business/")
                            .and_then(|value| value.split('/').next())
                            .or_else(|| {
                                path.strip_prefix("/businesses/")
                                    .and_then(|value| value.split('/').next())
                            })
                            .unwrap_or_default();
                        let root =
                            json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                        let business_id = root
                            .get("businesses")
                            .and_then(Value::as_array)
                            .and_then(|rows| {
                                rows.iter().find(|row| {
                                    row.get("slug").and_then(Value::as_str) == Some(slug)
                                })
                            })
                            .and_then(|row| row.get("id").and_then(Value::as_i64))
                            .unwrap_or(0);
                        form.insert("business_id".to_owned(), Value::from(business_id));
                    }
                    form.insert(
                        "user_id".to_owned(),
                        Value::from(
                            (active_session_user_id(app, request.cookie.as_deref()))
                                .map_err(|error| database_operation_http_status(error) as i32)?,
                        ),
                    );
                    let mut root =
                        json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                    let result = business::dynamic_handle_business_booking_action(
                        &mut root, action_id, &form,
                    )
                    .ok_or(404)?;
                    result.and_then(|_| {
                        business::persist_management_state_or_500_local(
                            &root,
                            Path::new(state_path),
                        )
                    })
                })(),
                "assign_appointment_technician" => (|| {
                    let mut form = serde_json::Map::new();
                    for field in ["csrf_token", "appointment_id", "technician_id"] {
                        if let Some(value) = dynamic::request_form_value(request, field) {
                            form.insert(field.to_owned(), Value::String(value));
                        }
                    }
                    if !form.contains_key("appointment_id")
                        && let Some(id) = path
                            .strip_prefix("/appointments/")
                            .and_then(|value| value.split('/').next())
                            .and_then(|value| value.parse::<i64>().ok())
                    {
                        form.insert("appointment_id".to_owned(), Value::from(id));
                    }
                    let mut root =
                        json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                    let result = business::dynamic_handle_business_booking_action(
                        &mut root, action_id, &form,
                    )
                    .ok_or(404)?;
                    result.and_then(|_| {
                        business::persist_management_state_or_500_local(
                            &root,
                            Path::new(state_path),
                        )
                    })
                })(),
                "create_business"
                | "update_business"
                | "toggle_business_public"
                | "delete_business"
                | "subscribe_business"
                | "unsubscribe_business"
                | "rate_business"
                | "create_service"
                | "update_service"
                | "delete_service"
                | "restore_service"
                | "create_technician"
                | "update_technician"
                | "delete_technician"
                | "restore_technician"
                | "create_business_availability"
                | "update_business_availability"
                | "delete_business_availability"
                | "create_technician_availability"
                | "update_technician_availability"
                | "delete_technician_availability" => Ok(()),
                _ => dynamic::dynamic_execute_declarative_action(
                    app,
                    Some(Path::new(state_path)),
                    request,
                    action_id,
                )
                .map(|_| ()),
            };
            if let Err(status) = result {
                return Some(http_text_response(
                    status as u16,
                    http::http_status_text(status as u16),
                    "invalid request\n",
                ));
            }
            if action_id == "create_booking" {
                return Some(http_route_redirect_for_request(
                    request,
                    &app_scope_path(app, "/bookings/"),
                ));
            }
            if action_id == "password_reset_complete" {
                return Some(app_fragment_response(
                    app,
                    "templates/registration/password_reset_complete_done.body.html",
                    serde_json::json!({}),
                    method,
                ));
            }
            if action_id == "run_selected_appointment_maintenance" {
                let Some(app_root) = app.app_root.as_deref() else {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "missing app root\n",
                    ));
                };
                let Some(html) = business::appointment_maintenance_result_html(
                    Path::new(app_root),
                    maintenance_results.as_deref().unwrap_or(&[]),
                ) else {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "missing maintenance template\n",
                    ));
                };
                if dynamic::request_is_hx(Some(request)) {
                    return Some(http_html_response(200, "OK", &html, method));
                }
                let diagnostics_path = app
                    .base_path
                    .as_deref()
                    .filter(|value| !value.is_empty() && *value != "/")
                    .map(|base| format!("{}/appointments/diagnose/", base.trim_end_matches('/')))
                    .unwrap_or_else(|| "/appointments/diagnose/".to_owned());
                return Some(http_route_redirect(&diagnostics_path));
            }
            if action_id == "assign_appointment_technician" {
                let redirect = dynamic::request_form_value(request, "return_to")
                    .filter(|value| value.starts_with('/') && !value.starts_with("//"))
                    .unwrap_or_else(|| "/appointments/".to_owned());
                let redirect = app
                    .base_path
                    .as_deref()
                    .filter(|base| !base.is_empty() && *base != "/")
                    .filter(|base| redirect.starts_with(base.trim_end_matches('/')))
                    .map(|_| redirect.clone())
                    .unwrap_or_else(|| app_scope_path(app, &redirect));
                return Some(http_route_redirect_for_request(request, &redirect));
            }
            if matches!(
                action_id,
                "create_appointment" | "create_internal_appointment"
            ) {
                let redirect = dynamic::request_form_value(request, "return_to")
                    .filter(|value| value.starts_with('/') && !value.starts_with("//"))
                    .unwrap_or_else(|| "/appointments/".to_owned());
                let redirect = app
                    .base_path
                    .as_deref()
                    .filter(|base| !base.is_empty() && *base != "/")
                    .filter(|base| redirect.starts_with(base.trim_end_matches('/')))
                    .map(|_| redirect.clone())
                    .unwrap_or_else(|| app_scope_path(app, &redirect));
                return Some(http_route_redirect_for_request(request, &redirect));
            }
            if matches!(
                action_id,
                "create_business"
                    | "update_business"
                    | "toggle_business_public"
                    | "delete_business"
                    | "subscribe_business"
                    | "unsubscribe_business"
                    | "rate_business"
            ) {
                let invite_token = (action_id == "issue_business_invite")
                    .then(|| dynamic::random_secret_hex(32).ok())
                    .flatten();
                if action_id == "issue_business_invite" && invite_token.is_none() {
                    return Some(http_text_response(
                        500,
                        "Internal Server Error",
                        "token unavailable\n",
                    ));
                }
                let action_result: Result<(), i32> = (|| {
                    let mut form = serde_json::Map::new();
                    for field in [
                        "csrf_token",
                        "user_id",
                        "business_id",
                        "name",
                        "address",
                        "description",
                        "is_public",
                        "time_format",
                        "secondary_color",
                        "business_edit_secondary_color_hex",
                        "image_url",
                        "remove_logo",
                        "email",
                        "message",
                        "score",
                        "comment",
                        "token_hash",
                    ] {
                        if let Some(value) = dynamic::request_form_value(request, field) {
                            form.insert(field.to_owned(), Value::String(value));
                        }
                    }
                    let mut root =
                        json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                    form.insert(
                        "user_id".to_owned(),
                        Value::from(
                            (active_session_user_id(app, request.cookie.as_deref()))
                                .map_err(|error| database_operation_http_status(error) as i32)?,
                        ),
                    );
                    if matches!(action_id, "create_business" | "update_business")
                        && let Some(content_type) = request.content_type.as_deref()
                    {
                        let fallback_logo_filename =
                            dynamic::request_form_value(request, "business_slug")
                                .or_else(|| dynamic::request_form_value(request, "name"));
                        for upload_field in ["logo", "business_logo"] {
                            let uploaded_media_url =
                                if let Some(body_path) = request.body_file_path.as_deref() {
                                    json_commands::dynamic_store_uploaded_media(
                                        Path::new(app.artifact_dir.as_deref().unwrap_or_default()),
                                        content_type,
                                        Path::new(body_path),
                                        upload_field,
                                        "/media/businesses",
                                        fallback_logo_filename.as_deref(),
                                    )
                                } else {
                                    json_commands::dynamic_store_uploaded_media_from_body(
                                        Path::new(app.artifact_dir.as_deref().unwrap_or_default()),
                                        content_type,
                                        &request.body,
                                        upload_field,
                                        "/media/businesses",
                                        fallback_logo_filename.as_deref(),
                                    )
                                };
                            if let Some(uploaded_media_url) = uploaded_media_url {
                                form.insert(
                                    "image_url".to_owned(),
                                    Value::String(uploaded_media_url),
                                );
                                break;
                            }
                        }
                    }
                    if let Some(token) = invite_token.as_deref() {
                        form.insert(
                            "token_hash".to_owned(),
                            Value::String(dynamic::hex_digest(&Sha256::digest(token.as_bytes()))),
                        );
                    }
                    if !form.contains_key("business_id") {
                        let slug = path
                            .strip_prefix("/businesses/")
                            .and_then(|value| value.split('/').next())
                            .or_else(|| {
                                path.strip_prefix("/rate/")
                                    .and_then(|value| value.split('/').next())
                            })
                            .unwrap_or_default();
                        if !slug.is_empty() {
                            form.insert("business_slug".to_owned(), Value::String(slug.to_owned()));
                        }
                        let business_id = root
                            .get("businesses")
                            .and_then(Value::as_array)
                            .and_then(|rows| {
                                rows.iter().find(|row| {
                                    row.get("slug").and_then(Value::as_str) == Some(slug)
                                })
                            })
                            .and_then(|row| row.get("id").and_then(Value::as_i64))
                            .unwrap_or(0);
                        if business_id > 0 {
                            form.insert("business_id".to_owned(), Value::from(business_id));
                        }
                    }
                    let result = business::dynamic_handle_business_identity_action(
                        &mut root, action_id, &form,
                    )
                    .ok_or(404)?;
                    result.and_then(|_| {
                        if let Some(token) = invite_token.as_deref() {
                            root.as_object_mut()
                                .and_then(|object| {
                                    object
                                        .entry("notification_deliveries")
                                        .or_insert_with(|| Value::Array(Vec::new()))
                                        .as_array_mut()
                                })
                                .ok_or(500)?
                                .push(serde_json::json!({
                                    "delivery_kind": "business_invite",
                                    "recipient": dynamic::request_form_value(request, "email").unwrap_or_default(),
                                    "secret": token,
                                    "delivery_status": "queued"
                                }));
                        }
                        business::persist_management_state_or_500_local(
                            &root,
                            Path::new(state_path),
                        )
                    })
                })();
                if let Err(status) = action_result {
                    return Some(http_text_response(
                        status as u16,
                        http::http_status_text(status as u16),
                        if action_id.contains("availability") {
                            "Validation failed\n"
                        } else {
                            "invalid request\n"
                        },
                    ));
                }
                if invite_token.is_some() {
                    let invite_page_json = business::dynamic_invite_created_page_params_json(
                        "The invite was created and queued for delivery.",
                        "",
                        &app_scope_path(app, path),
                    )?;
                    return dynamic::render_declared_page_response(
                        Path::new(app.artifact_dir.as_deref()?),
                        "invite_created",
                        &invite_page_json,
                    )
                    .ok()
                    .map(String::into_bytes);
                }
                if action_id == "create_business"
                    && let Some(name) = dynamic::request_form_value(request, "name")
                    && let Some(slug) = business::business_slug_from_name_identity_local(&name)
                {
                    let redirect = app_scope_path(app, &format!("/businesses/{slug}/"));
                    return Some(http_route_redirect_for_request(request, &redirect));
                }
                if action_id == "rate_business"
                    && let Some(slug) = path
                        .strip_prefix("/rate/")
                        .and_then(|value| value.split('/').next())
                        .filter(|value| !value.is_empty())
                {
                    let redirect = app_scope_path(app, &format!("/b/{slug}/"));
                    return Some(http_route_redirect_for_request(request, &redirect));
                }
            }
            if matches!(
                action_id,
                "create_service"
                    | "update_service"
                    | "delete_service"
                    | "restore_service"
                    | "create_technician"
                    | "update_technician"
                    | "delete_technician"
                    | "restore_technician"
            ) {
                let slug = path
                    .strip_prefix("/businesses/")
                    .and_then(|value| value.split('/').next())
                    .unwrap_or_default();
                let management_result: Result<(), i32> = (|| {
                    let mut form = serde_json::Map::new();
                    for field in [
                        "csrf_token",
                        "business_id",
                        "service_id",
                        "technician_id",
                        "name",
                        "email",
                        "description",
                        "cost",
                        "duration_minutes",
                        "sort_order",
                        "image_url",
                        "remove_image",
                        "primary_color",
                        "booking_option_count",
                    ] {
                        if let Some(value) = dynamic::request_form_value(request, field) {
                            form.insert(field.to_owned(), Value::String(value));
                        }
                    }
                    let mut root =
                        json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                    if !form.contains_key("business_id") {
                        let business_id = root
                            .get("businesses")
                            .and_then(Value::as_array)
                            .and_then(|rows| {
                                rows.iter().find(|row| {
                                    row.get("slug").and_then(Value::as_str) == Some(slug)
                                })
                            })
                            .and_then(|row| row.get("id").and_then(Value::as_i64))
                            .unwrap_or(0);
                        form.insert("business_id".to_owned(), Value::from(business_id));
                    }
                    let business_id = form.get("business_id").and_then(Value::as_i64).unwrap_or(0);
                    if !form.contains_key("service_id")
                        && let Some(id) = path
                            .split('/')
                            .filter_map(|value| value.parse::<i64>().ok())
                            .next_back()
                    {
                        form.insert("service_id".to_owned(), Value::from(id));
                    }
                    if let Some(option_count) = form
                        .get("booking_option_count")
                        .and_then(Value::as_str)
                        .and_then(|value| value.parse::<usize>().ok())
                    {
                        for index in 1..=option_count.min(256) {
                            for field_name in [
                                format!("booking_option_label_{index}"),
                                format!("booking_option_duration_{index}"),
                                format!("booking_option_cost_{index}"),
                            ] {
                                if let Some(value) =
                                    dynamic::request_form_value(request, &field_name)
                                {
                                    form.insert(field_name, Value::String(value));
                                }
                            }
                        }
                    }
                    if business_id > 0
                        && let Some(rows) = root.get("technicians").and_then(Value::as_array)
                    {
                        for technician_id in rows.iter().filter_map(|row| {
                            (row.get("business_id").and_then(Value::as_i64) == Some(business_id))
                                .then(|| row.get("id").and_then(Value::as_i64))
                                .flatten()
                        }) {
                            let field_name = format!("technician_{technician_id}");
                            if let Some(value) = dynamic::request_form_value(request, &field_name) {
                                form.insert(field_name, Value::String(value));
                            }
                        }
                    }
                    if !form.contains_key("technician_id")
                        && let Some(id) = path
                            .split("/technicians/")
                            .nth(1)
                            .and_then(|value| value.split('/').next())
                            .and_then(|value| value.parse::<i64>().ok())
                    {
                        form.insert("technician_id".to_owned(), Value::from(id));
                    }
                    let result = business::dynamic_handle_business_management_action(
                        &mut root, action_id, &form,
                    )
                    .ok_or(404)?;
                    result.and_then(|_| {
                        business::persist_management_state_or_500_local(
                            &root,
                            Path::new(state_path),
                        )
                    })
                })();
                if let Err(status) = management_result {
                    return Some(http_text_response(
                        status as u16,
                        http::http_status_text(status as u16),
                        if action_id.contains("availability") {
                            "Validation failed\n"
                        } else {
                            "invalid request\n"
                        },
                    ));
                }
                if action_id == "create_technician"
                    && dynamic::request_is_hx(Some(request))
                    && let Some(app_root) = app.app_root.as_deref()
                    && let Some(state_path) = app.state_path.as_deref()
                    && let Some(rows_html) = business::dynamic_business_admin_technician_rows_html(
                        Path::new(state_path),
                        slug,
                        Path::new(app_root),
                    )
                {
                    return Some(http_html_response(200, "OK", &rows_html, method));
                }
                let redirect = if matches!(action_id, "create_service" | "create_technician") {
                    format!("/businesses/{slug}/")
                } else {
                    path.to_owned()
                };
                return Some(http_route_redirect(&redirect));
            }
            if matches!(
                action_id,
                "create_appointment"
                    | "create_internal_appointment"
                    | "create_business_availability"
                    | "update_business_availability"
                    | "delete_business_availability"
                    | "create_technician_availability"
                    | "update_technician_availability"
                    | "delete_technician_availability"
            ) {
                let action_result: Result<(), i32> = (|| {
                    let mut form = serde_json::Map::new();
                    for field in [
                        "day_of_week",
                        "start_time",
                        "end_time",
                        "csrf_token",
                        "availability_id",
                        "technician_id",
                        "business_id",
                        "service_id",
                        "booking_option_index",
                        "user_id",
                        "name",
                        "email",
                        "title",
                        "date",
                        "time",
                        "notes",
                    ] {
                        if let Some(value) = dynamic::request_form_value(request, field) {
                            form.insert(field.to_owned(), Value::String(value));
                        }
                    }
                    let root =
                        json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                    if !form.contains_key("business_id") {
                        let slug = path
                            .strip_prefix("/businesses/")
                            .and_then(|value| value.split('/').next())
                            .or_else(|| {
                                path.strip_prefix("/business/")
                                    .and_then(|value| value.split('/').next())
                            })
                            .unwrap_or_default();
                        let business_id = root
                            .get("businesses")
                            .and_then(Value::as_array)
                            .and_then(|rows| {
                                rows.iter().find(|row| {
                                    row.get("slug").and_then(Value::as_str) == Some(slug)
                                })
                            })
                            .and_then(|row| row.get("id").and_then(Value::as_i64))
                            .unwrap_or(0);
                        form.insert("business_id".to_owned(), Value::from(business_id));
                    }
                    if !form.contains_key("availability_id")
                        && let Some(id) = path
                            .split('/')
                            .filter_map(|value| value.parse::<i64>().ok())
                            .next_back()
                    {
                        form.insert("availability_id".to_owned(), Value::from(id));
                    }
                    if matches!(
                        action_id,
                        "create_appointment" | "create_internal_appointment"
                    ) {
                        form.insert(
                            "user_id".to_owned(),
                            Value::from(
                                (active_session_user_id(app, request.cookie.as_deref())).map_err(
                                    |error| database_operation_http_status(error) as i32,
                                )?,
                            ),
                        );
                    }
                    if !form.contains_key("technician_id")
                        && let Some(id) = path
                            .split("/technicians/")
                            .nth(1)
                            .and_then(|value| value.split('/').next())
                            .and_then(|value| value.parse::<i64>().ok())
                    {
                        form.insert("technician_id".to_owned(), Value::from(id));
                    }
                    let mut root = root;
                    let result = business::dynamic_handle_business_booking_action(
                        &mut root, action_id, &form,
                    )
                    .ok_or(404)?;
                    result.and_then(|_| {
                        business::persist_management_state_or_500_local(
                            &root,
                            Path::new(state_path),
                        )
                    })
                })();
                if let Err(status) = action_result {
                    return Some(http_text_response(
                        status as u16,
                        http::http_status_text(status as u16),
                        if action_id.contains("availability") {
                            "Validation failed\n"
                        } else {
                            "invalid request\n"
                        },
                    ));
                }
                if matches!(
                    action_id,
                    "create_technician_availability"
                        | "update_technician_availability"
                        | "delete_technician_availability"
                ) && dynamic::request_is_hx(Some(request))
                    && let Some(app_root) = app.app_root.as_deref()
                {
                    let slug = path
                        .strip_prefix("/businesses/")
                        .and_then(|value| value.split('/').next())
                        .unwrap_or_default();
                    if let Some(rows_html) = business::dynamic_business_admin_technician_rows_html(
                        Path::new(state_path),
                        slug,
                        Path::new(app_root),
                    ) {
                        return Some(http_html_response(200, "OK", &rows_html, method));
                    }
                }
            }
        }
        let redirect = app_scope_path(app, path);
        return Some(http_route_redirect_for_request(request, &redirect));
    }
    if route
        .get("auth_gate")
        .and_then(Value::as_str)
        .is_some_and(|gate| gate == "session_required")
        && render_request.actor_id <= 0
    {
        return Some(app_login_redirect(app, path));
    }
    if route.get("feature_id").and_then(Value::as_str).is_some()
        && let Some(policy) = route.get("policy_gate").and_then(Value::as_str)
        && policy != "public"
        && !match actor_has_route_policy(app, render_request.actor_id, policy) {
            Ok(value) => value,
            Err(error) => return Some(database_error_response(error)),
        }
    {
        return Some(http_text_response(403, "Forbidden", "capability denied\n"));
    }
    if route.get("route_id").and_then(Value::as_str) == Some("service_manage")
        && let Some(business_path) = path.strip_suffix("services/")
    {
        return Some(http_route_redirect_for_request(
            request,
            &app_scope_path(app, business_path),
        ));
    }
    if app.host_profile.as_deref() == Some("static-pages")
        && route
            .get("page_id")
            .and_then(Value::as_str)
            .is_none_or(str::is_empty)
    {
        let response = artifact_server::serve_app_request(app, method, path);
        return Some(http_static_response(response, method));
    }
    let actor_id = render_request.actor_id;
    let has_user = actor_id > 0;
    let managed_business_count = if has_user && actor_id > 0 {
        if app_uses_file_backed_runtime_state(app) {
            app.state_path
                .as_deref()
                .map(|state_path| {
                    business::dynamic_managed_business_count_for_user(
                        Path::new(state_path),
                        actor_id,
                    )
                })
                .unwrap_or(0)
        } else {
            let Some(store) = app_database_operations(app) else {
                return Some(http_text_response(
                    503,
                    "Service Unavailable",
                    "app storage unavailable\n",
                ));
            };
            if ["business", "tenant", "tenant_membership"]
                .iter()
                .all(|name| {
                    store
                        .schema
                        .entities
                        .iter()
                        .any(|entity| entity.name == *name)
                })
            {
                match pharos_runtime_business::managed_business_count(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    actor_id,
                ) {
                    Ok(count) => count,
                    Err(error) => {
                        let status = database_operation_http_status(error);
                        return Some(http_text_response(
                            status,
                            http::http_status_text(status),
                            "business scope unavailable\n",
                        ));
                    }
                }
            } else {
                0
            }
        }
    } else {
        0
    };
    let html = match app_route_page_html_result(
        app,
        &route,
        target,
        actor_id,
        has_user,
        managed_business_count,
        None,
        &render_request.csrf_token,
    ) {
        Ok(html) => html,
        Err(status) => {
            return Some(http_text_response(
                status,
                http::http_status_text(status),
                "declared app route unavailable\n",
            ));
        }
    };
    Some(http_html_response_with_csrf(
        200,
        "OK",
        &html,
        method,
        Some(&render_request.csrf_token),
    ))
}

/// Builds the response for an app-owned route request.
///
/// # Parameters
///
/// - `app`: Resolved application runtime surface used to render the route.
/// - `method`: Input consumed by [`crate::runtime::app_route_response`].
/// - `target`: Input consumed by [`crate::runtime::app_route_response`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::app_route_response`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::app_route_response(todo!(), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub(crate) fn app_route_response(app: &AppRuntime, method: &str, target: &str) -> Vec<u8> {
    app_route_response_with_cookie(app, method, target, None)
}

/// Performs app route response with cookie.
fn app_route_response_with_cookie(
    app: &AppRuntime,
    method: &str,
    target: &str,
    cookie: Option<&str>,
) -> Vec<u8> {
    let request = http::HttpRequest {
        method: method.to_owned(),
        target: target.to_owned(),
        cookie: cookie.map(ToOwned::to_owned),
        ..Default::default()
    };
    app_route_response_with_cookie_core(app, &request)
}

/// Performs app route response with request.
fn app_route_response_with_request(app: &AppRuntime, request: &http::HttpRequest) -> Vec<u8> {
    if let Some(response) = pharos_runtime_static::navigation::mount_redirect(
        request,
        app.base_path.as_deref().unwrap_or_default(),
    ) {
        return response;
    }
    let path = app_relative_target(app, &request.target);
    let route = matched_app_route(app, &request.method, path.split('?').next().unwrap_or("/"));
    let response = app_route_response_with_cookie_core(app, request);
    let identity = sha256_hex(runtime_build_identity_value(app).to_string().as_bytes());
    let mut response = http_response_insert_header(response, "X-Pharos-Build-Identity", &identity);
    if let Some(end) = response.windows(4).position(|bytes| bytes == b"\r\n\r\n")
        && let Ok(head) = std::str::from_utf8(&response[..end])
    {
        let secure = dynamic::request_origin_scheme(
            Some(request),
            connection::NativeTransportType::Tcp,
            None,
            None,
        ) == "https";
        for (name, value) in pharos_runtime_static::browser_cache::deployment_headers(
            request,
            head,
            app.app_id.as_deref().unwrap_or_default(),
            app.base_path.as_deref().unwrap_or("/"),
            &identity,
            secure,
        ) {
            response = http_response_insert_header(response, name, &value);
        }
    }
    route.map_or(response.clone(), |route| {
        apply_route_response_middleware(&route, request, response)
    })
}

fn ucal_issue_business_invite_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    _method: &str,
    path: &str,
) -> Vec<u8> {
    if let Err(response) = authorize_app_mutation(app, request, path) {
        return response;
    }
    if !dynamic::csrf_request_valid(request, dynamic::request_body_text(request).as_deref()) {
        return http_text_response(403, "Forbidden", "Security verification failed\n");
    }
    let email = dynamic::request_form_value(request, "email").unwrap_or_default();
    let account_type = dynamic::request_form_value(request, "account_type")
        .unwrap_or_else(|| "business_customer".to_owned());
    let role_hint = dynamic::request_form_value(request, "role_hint")
        .unwrap_or_else(|| "business_customer".to_owned());
    let token = match dynamic::random_secret_hex(32) {
        Ok(token) => token,
        Err(_) => return http_text_response(500, "Internal Server Error", "token unavailable\n"),
    };
    let token_hash = dynamic::hex_digest(&Sha256::digest(token.as_bytes()));
    let slug = path
        .strip_prefix("/businesses/")
        .and_then(|value| value.split('/').next())
        .unwrap_or_default();
    let actor_user_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    let expires_at = timestamp_after_seconds_utc(604_800);
    let stored = (|| -> Result<bool, u16> {
        let store =
            database::runtime_logical_app_store(app).map_err(database_operation_http_status)?;
        let store = with_action_effects(app, request, "issue_business_invite", store)?;
        business::issue_business_invite(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            &business::BusinessInviteIssue {
                business_slug: slug,
                actor_user_id,
                email: &email,
                account_type: &account_type,
                role_hint: &role_hint,
                token_hash: &token_hash,
                delivery_secret: &token,
                expires_at: &expires_at,
            },
        )
        .map_err(database_operation_http_status)
    })();
    match stored {
        Ok(true) => {}
        Ok(false) => return http_text_response(422, "Unprocessable Entity", "invalid request\n"),
        Err(status) => {
            return http_text_response(status, http_reason_phrase(status), "invite unavailable\n");
        }
    }
    let return_path = app_scope_path(app, path);
    let Some(invite_page_json) = business::dynamic_invite_created_page_params_json(
        "The invite was created and queued for delivery.",
        "",
        &return_path,
    ) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Ok(response) = dynamic::render_declared_page_response(
        Path::new(app.artifact_dir.as_deref().unwrap_or_default()),
        "invite_created",
        &invite_page_json,
    ) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    response.into_bytes()
}

fn ucal_invite_accept_page_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    path: &str,
) -> Vec<u8> {
    let token = path
        .strip_prefix("/accounts/invite/")
        .and_then(|value| value.split('/').next())
        .unwrap_or_default();
    let token_hash = dynamic::hex_digest(&Sha256::digest(token.as_bytes()));
    let Some(store) = app_database_operations(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let invite = match business::business_invite_preview(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
        &token_hash,
        &current_timestamp_utc(),
    ) {
        Ok(Some(invite)) => invite,
        Ok(None) => return http_text_response(404, "Not Found", "invite unavailable\n"),
        Err(_) => return http_text_response(503, "Service Unavailable", "database unavailable\n"),
    };
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "missing app root\n");
    };
    let invite_input = |id: &str,
                        input_type: &str,
                        name: &str,
                        label: &str,
                        value: &str,
                        autocomplete: &str,
                        extra_attributes: &str| {
        let attributes = format!(" autocomplete=\"{autocomplete}\" required{extra_attributes}");
        app_ui_input(
            artifact_root,
            id,
            input_type,
            name,
            label,
            "",
            "form-control",
            value,
            &attributes,
        )
    };
    let (
        Some(id_invite_email_ui_html),
        Some(id_invite_username_ui_html),
        Some(id_invite_full_name_ui_html),
        Some(id_invite_phone_number_ui_html),
        Some(id_invite_password_ui_html),
        Some(id_invite_password_confirm_ui_html),
        Some(invite_create_account_button_ui_html),
    ) = (
        invite_input(
            "invite-email",
            "email",
            "email",
            "Email",
            &invite.email,
            "email",
            " readonly",
        ),
        invite_input(
            "invite-username",
            "text",
            "username",
            "Username",
            "",
            "username",
            "",
        ),
        invite_input(
            "invite-full-name",
            "text",
            "full_name",
            "Full name",
            "",
            "name",
            "",
        ),
        invite_input(
            "invite-phone-number",
            "tel",
            "phone_number",
            "Phone number",
            "",
            "tel",
            "",
        ),
        invite_input(
            "invite-password",
            "password",
            "password",
            "Password",
            "",
            "new-password",
            "",
        ),
        invite_input(
            "invite-password-confirm",
            "password",
            "password_confirm",
            "Confirm password",
            "",
            "new-password",
            "",
        ),
        app_ui_button(
            artifact_root,
            "invite-accept",
            "submit",
            "btn btn-primary",
            "",
            "Accept Invite",
        ),
    )
    else {
        return http_text_response(
            500,
            "Internal Server Error",
            "invite form controls failed to render\n",
        );
    };
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    let csrf_input_html = format!(
        "<input type=\"hidden\" name=\"csrf_token\" value=\"{}\" />",
        json_commands::html_escape_text(&csrf_token)
    );
    let params = serde_json::json!({
        "invite_kind": invite.invite_kind,
        "target_html": "",
        "error_html": "",
        "csrf_input_html": csrf_input_html,
        "form_action": app_scope_path(app, path),
        "id_invite_email_ui_html": id_invite_email_ui_html,
        "id_invite_username_ui_html": id_invite_username_ui_html,
        "id_invite_full_name_ui_html": id_invite_full_name_ui_html,
        "id_invite_phone_number_ui_html": id_invite_phone_number_ui_html,
        "id_invite_password_ui_html": id_invite_password_ui_html,
        "id_invite_password_confirm_ui_html": id_invite_password_confirm_ui_html,
        "invite_create_account_button_ui_html": invite_create_account_button_ui_html,
    });
    let Some(params_json) = serde_json::to_string(&params).ok() else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Ok(response) =
        dynamic::render_declared_page_response(artifact_root, "invite_accept", &params_json)
    else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Some((_, rendered_body)) = response.split_once("\r\n\r\n") else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    http_html_response_with_csrf(200, "OK", rendered_body, "GET", Some(&csrf_token))
}

fn ucal_accept_business_invite_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    _method: &str,
    path: &str,
) -> Vec<u8> {
    if let Err(response) = authorize_app_mutation(app, request, path) {
        return response;
    }
    let username = dynamic::request_form_value(request, "username").unwrap_or_default();
    let full_name = dynamic::request_form_value(request, "full_name").unwrap_or_default();
    let phone_number = dynamic::request_form_value(request, "phone_number").unwrap_or_default();
    let presented_token = path
        .strip_prefix("/accounts/invite/")
        .and_then(|value| value.split('/').next())
        .unwrap_or_default();
    let token_hash = dynamic::hex_digest(&Sha256::digest(presented_token.as_bytes()));
    let password = dynamic::request_form_value(request, "password").unwrap_or_default();
    let confirmation = dynamic::request_form_value(request, "password_confirm").unwrap_or_default();
    if username.is_empty() || password != confirmation || password.len() < 8 {
        return http_text_response(422, "Unprocessable Entity", "invalid request\n");
    }
    let password_hash = match dynamic::hash_password(&password) {
        Ok(hash) => hash,
        Err(_) => {
            return http_text_response(500, "Internal Server Error", "credential unavailable\n");
        }
    };
    let session_token = match dynamic::random_secret_hex(32) {
        Ok(token) => token,
        Err(_) => return http_text_response(500, "Internal Server Error", "session unavailable\n"),
    };
    let Some(session_hash) = native_session_token_hash(app, &session_token) else {
        return http_text_response(500, "Internal Server Error", "session unavailable\n");
    };
    let session_expires_at = timestamp_after_seconds_utc(604_800);
    let now = current_timestamp_utc();
    let Some(store) = app_database_operations(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let store = match with_action_effects(app, request, "accept_invite", store) {
        Ok(store) => store,
        Err(status) => {
            return http_text_response(
                status,
                http::http_status_text(status),
                "invite effects unavailable\n",
            );
        }
    };
    match business::accept_business_invite(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
        &business::BusinessInviteAccept {
            token_hash: &token_hash,
            username: &username,
            full_name: &full_name,
            phone_number: &phone_number,
            password_hash: &password_hash,
            session_token_hash: &session_hash,
            session_expires_at: &session_expires_at,
            now: &now,
        },
    ) {
        Ok(Some(_)) => {}
        Ok(None) => return http_text_response(404, "Not Found", "invite unavailable\n"),
        Err(pharos_runtime_database::operations::DatabaseError::InvalidInput) => {
            return http_text_response(422, "Unprocessable Entity", "invalid request\n");
        }
        Err(pharos_runtime_database::operations::DatabaseError::Conflict) => {
            return http_text_response(409, "Conflict", "invite acceptance conflict\n");
        }
        Err(pharos_runtime_database::operations::DatabaseError::AccessDenied) => {
            return http_text_response(403, "Forbidden", "invite access denied\n");
        }
        Err(_) => return http_text_response(503, "Service Unavailable", "database unavailable\n"),
    }
    let continue_path = app_scope_path(app, "/");
    let Some(params_json) =
        business::dynamic_invite_accept_done_page_params_json(Some(&continue_path))
    else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Ok(response) = dynamic::render_declared_page_response(
        Path::new(app.artifact_dir.as_deref().unwrap_or_default()),
        "invite_accept_done",
        &params_json,
    ) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let session_cookie =
        dynamic::session_cookie_header(app, Some(request), Some(&session_token), false);
    let Some((headers, body)) = response.split_once("\r\n\r\n") else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    format!("{headers}\r\n{session_cookie}\r\n\r\n{body}").into_bytes()
}

/// Performs route requires state mutation guard.
fn route_requires_state_mutation_guard(
    app: &AppRuntime,
    request_method: &str,
    route: Option<&Value>,
) -> bool {
    if !app_uses_file_backed_runtime_state(app) {
        return false;
    }

    let action_id = route
        .and_then(|route| route.get("action_id"))
        .and_then(Value::as_str)
        .unwrap_or_default();

    let provider_callback = app.app_root.as_deref().is_some_and(|app_root| {
        payment_provider::payment_provider_callback_action_declared(Path::new(app_root), action_id)
    });
    let provider_checkout_webhook = app.app_root.as_deref().is_some_and(|app_root| {
        payment_provider::payment_provider_checkout_webhook_action_declared(
            Path::new(app_root),
            action_id,
        )
        .is_some()
    });

    // OAuth providers redirect to the callback with GET, but a verified
    // callback consumes a nonce and changes file-backed provider state. Keep
    // that mutation protected even though the redirect uses GET. Database apps
    // use their adapter transaction and never reach this file-lock path.
    if matches!(request_method, "GET" | "HEAD") && !provider_callback {
        return false;
    }

    if provider_checkout_webhook {
        return true;
    }

    if matches!(
        action_id,
        "architect_apply_preview_edit" | "issue_business_invite" | "accept_invite"
    ) {
        return false;
    }
    true
}

/// Gives authenticated source-archive responses their existing bounded source-export budget.
fn app_response_body_budget(app: &AppRuntime, path: &str, method: &str, response: &[u8]) -> usize {
    let ordinary = app.resource_budgets.max_response_bytes;
    if app.app_id.as_deref() != Some("architect") || path != "/exports/download" || method != "GET"
    {
        return ordinary;
    }
    let headers = response
        .windows(4)
        .take(16 * 1024)
        .position(|bytes| bytes == b"\r\n\r\n")
        .and_then(|end| std::str::from_utf8(&response[..end]).ok());
    let archive = headers.is_some_and(|headers| {
        headers.starts_with("HTTP/1.1 200 ")
            && headers
                .lines()
                .any(|line| line.eq_ignore_ascii_case("Content-Type: application/x-tar"))
            && headers
                .lines()
                .any(|line| line.starts_with("Content-Disposition: attachment;"))
    });
    if !archive {
        return ordinary;
    }
    ordinary.max(
        pharos_runtime_architect::source_bundle::MAX_SOURCE_EXPORT_BYTES
            .saturating_add(
                pharos_runtime_architect::source_bundle::MAX_SOURCE_EXPORT_FILES
                    .saturating_mul(4096),
            )
            .saturating_add(1024),
    )
}

/// Performs app route response with cookie core.
fn app_route_response_with_cookie_core(app: &AppRuntime, request: &http::HttpRequest) -> Vec<u8> {
    warm_runtime_config_allowlist(app);
    let render_request = match app_render_request(app, request) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    let relative_target = render_request.relative_target.as_str();
    let path = render_request.relative_path.as_str();
    #[cfg(not(target_os = "wasi"))]
    if let Some(response) = social_connections::response(app, request, relative_target) {
        return response;
    }
    if request.method == "GET" && path.starts_with("/accounts/invite/") && path.ends_with('/') {
        return ucal_invite_accept_page_response(app, request, path);
    }
    if request.method == "POST" {
        let mut relative_request = request.clone();
        relative_request.target = relative_target.to_owned();
        if path.starts_with("/businesses/") && path.ends_with("/invites/new/") {
            return ucal_issue_business_invite_response(
                app,
                &relative_request,
                &request.method,
                path,
            );
        }
        if path.starts_with("/accounts/invite/") {
            return ucal_accept_business_invite_response(
                app,
                &relative_request,
                &request.method,
                path,
            );
        }
    }
    if request.method == "POST" && path.starts_with("/api/businesses/") {
        let mut relative_request = request.clone();
        relative_request.target = relative_target.to_owned();
        if let Some(response) =
            ucal_generated_api_mutation_response(app, &relative_request, &request.method, path)
        {
            return response;
        }
    }
    let route = matched_app_route(app, &request.method, path);
    let action_id = route
        .as_ref()
        .and_then(|route| route.get("action_id"))
        .and_then(Value::as_str)
        .unwrap_or_default();
    let route_is_payment_provider_callback = app.app_root.as_deref().is_some_and(|app_root| {
        payment_provider::payment_provider_callback_action_declared(Path::new(app_root), action_id)
    });
    let route_is_payment_provider_checkout_webhook = app
        .app_root
        .as_deref()
        .and_then(|app_root| {
            payment_provider::payment_provider_checkout_webhook_action_declared(
                Path::new(app_root),
                action_id,
            )
        })
        .or_else(|| {
            app.artifact_dir.as_deref().and_then(|artifact_dir| {
                payment_provider::payment_provider_checkout_webhook_action_declared(
                    Path::new(artifact_dir),
                    action_id,
                )
            })
        })
        .is_some();
    if (!matches!(request.method.as_str(), "GET" | "HEAD") || route_is_payment_provider_callback)
        && !route_is_payment_provider_checkout_webhook
        && let Err(response) = authorize_app_mutation(app, request, path)
    {
        return response;
    }
    let _state_guard = if app_uses_file_backed_runtime_state(app)
        && route_requires_state_mutation_guard(app, &request.method, route.as_ref())
    {
        match app.state_path.as_deref() {
            Some(state_path) => {
                match state_store::StateMutationGuard::acquire(Path::new(state_path)) {
                    Ok(guard) => Some(guard),
                    Err(_) => {
                        return http_text_response(
                            503,
                            "Service Unavailable",
                            "state mutation unavailable\n",
                        );
                    }
                }
            }
            None => {
                return http_text_response(
                    503,
                    "Service Unavailable",
                    "state storage unavailable\n",
                );
            }
        }
    } else {
        None
    };
    let response = app_route_response_with_cookie_unlocked(app, request);
    if response.len()
        > app_response_body_budget(app, path, &request.method, &response).saturating_add(64 * 1024)
    {
        return http_text_response(500, "Internal Server Error", "response budget exceeded\n");
    }
    response
}

/// Runs checkout against either configured database authority or a declared file app.
fn payment_provider_checkout_action_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    action_id: &str,
    provider_id: &str,
) -> Option<Vec<u8>> {
    let result = (|| {
        let app_root = app.app_root.as_deref().map(Path::new).ok_or(503)?;
        let form_fields = [
            "date",
            "time",
            "time_hour",
            "time_minute",
            "time_period",
            "notes",
            "technician_id",
            "booking_option_index",
        ]
        .into_iter()
        .filter_map(|field| {
            dynamic::request_form_value(request, field).map(|value| (field.to_owned(), value))
        })
        .collect();
        let checkout_request = payment_provider::PaymentProviderCheckoutRequest {
            actor_user_id: (active_session_user_id(app, request.cookie.as_deref()))
                .map_err(|error| database_operation_http_status(error) as i32)?,
            idempotency_key: dynamic::request_form_value(request, "idempotency_key")
                .unwrap_or_default(),
            request_target: request.target.clone(),
            form_fields,
        };
        if !app_uses_file_backed_runtime_state(app) {
            let store = app_database_operations(app).ok_or(503)?;
            let completion = with_action_effects(
                app,
                request,
                action_id,
                database::LogicalAppStore {
                    adapter: store.adapter.clone(),
                    config: store.config.clone(),
                    schema: store.schema.clone(),
                },
            )
            .map_err(|status| status as i32)?;
            return payment_provider::database_checkout(
                app_root,
                app.runtime_conf_path.as_deref().map(Path::new),
                &store,
                completion.adapter.as_ref(),
                provider_id,
                checkout_request,
            );
        }
        let state_path = app.state_path.as_deref().map(Path::new).ok_or(503)?;
        let _guard = state_store::StateMutationGuard::acquire(state_path).map_err(|_| 503)?;
        let mut root = json_commands::json_doc_load_file(state_path).ok_or(404)?;
        let checkout = payment_provider::payment_provider_checkout_start(
            &mut root,
            app_root,
            app.runtime_conf_path.as_deref().map(Path::new),
            provider_id,
            checkout_request,
        )?;
        if checkout.outcome == payment_provider::PaymentProviderCheckoutOutcome::Redirect {
            payment_provider::persist_payment_provider_state_or_500(&root, state_path)?;
        }
        Ok::<_, i32>(checkout)
    })();
    match result {
        Ok(checkout)
            if checkout.outcome
                == payment_provider::PaymentProviderCheckoutOutcome::DemoFallback =>
        {
            None
        }
        Ok(checkout) => Some(http_route_redirect_for_request(
            request,
            checkout.redirect_location.as_deref().unwrap_or("/"),
        )),
        Err(status) => Some(http_text_response(
            status as u16,
            http::http_status_text(status as u16),
            "checkout unavailable\n",
        )),
    }
}

/// Finds the provider bound to a declarative provider-checkout action for an app.
fn payment_provider_checkout_provider_for_action(
    app: &AppRuntime,
    action_id: &str,
) -> Option<String> {
    app.app_root
        .as_deref()
        .and_then(|app_root| {
            payment_provider::payment_provider_checkout_action_declared(
                Path::new(app_root),
                action_id,
            )
        })
        .or_else(|| {
            app.artifact_dir.as_deref().and_then(|artifact_dir| {
                payment_provider::payment_provider_checkout_action_declared(
                    Path::new(artifact_dir),
                    action_id,
                )
            })
        })
}

/// Opens the configured logical app authority while preserving error categories.
fn checked_app_database_operations(
    app: &AppRuntime,
) -> Result<database::LogicalAppStore, pharos_runtime_database::operations::DatabaseError> {
    database::runtime_logical_app_store(app)
}

/// Resolves a declared app's operation store without choosing a vendor.
fn app_database_operations(app: &AppRuntime) -> Option<database::LogicalAppStore> {
    database::runtime_logical_app_store(app).ok()
}

/// Binds the declared durable effects to a request-scoped logical store.
/// The adapter commits them with the domain mutation, preserving result indices.
fn with_action_effects(
    app: &AppRuntime,
    request: &http::HttpRequest,
    action: &str,
    mut store: database::LogicalAppStore,
) -> Result<database::LogicalAppStore, u16> {
    let effects = dynamic::declared_effect_steps(
        app,
        &store.schema,
        request,
        action,
        &std::collections::BTreeMap::new(),
        0,
        active_session_user_id(app, request.cookie.as_deref())
            .map_err(database_operation_http_status)?,
    )
    .map_err(|status| status as u16)?;
    if !effects.is_empty() {
        let mut adapter = pharos_runtime_database::effects::EffectAdapter::new(
            store.adapter,
            &store.schema,
            effects,
        )
        .map_err(database_operation_http_status)?;
        if let Some(resource) = dynamic::action_resource_binding(app, &store.schema, action) {
            adapter = adapter
                .with_resource(&store.schema, resource)
                .map_err(database_operation_http_status)?;
        }
        store.adapter = std::sync::Arc::new(adapter);
    }
    Ok(store)
}

/// Loads a scoped catalog for the existing declared business page templates.
fn business_catalog_for_page(
    app: &AppRuntime,
    slug: &str,
    actor_id: i64,
    management: bool,
) -> Option<Value> {
    let store = app_database_operations(app)?;
    pharos_runtime_business::business_catalog(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
        slug,
        actor_id,
        management,
    )
    .ok()
}

/// Adds redacted provider settings after scoped management authorization while
/// retaining the catalog's descriptive owner fields for existing templates.
fn business_payment_for_page(
    app: &AppRuntime,
    artifact_root: &Path,
    slug: &str,
    actor_id: i64,
) -> Option<Value> {
    let mut view = business_catalog_for_page(app, slug, actor_id, true)?;
    let store = app_database_operations(app)?;
    let declaration = pharos_runtime_payment::payment_provider_manifest_config(artifact_root)?;
    let provider = pharos_runtime_payment::payment_provider_primary_provider(artifact_root)?;
    let payment = pharos_runtime_database::payment::payment_render_state(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
        &declaration,
        Some(slug),
        &provider,
    )
    .ok()?;
    let owner_section = declaration.get("owner_state_section")?.as_str()?;
    view.as_object_mut()?.extend(
        payment
            .as_object()?
            .iter()
            .filter(|(key, _)| key.as_str() != owner_section)
            .map(|(key, value)| (key.clone(), value.clone())),
    );
    Some(view)
}

/// Applies a business identity form with route-owned actor and business scope.
fn business_identity_action_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    path: &str,
    action: &str,
) -> Vec<u8> {
    let slug = ["/businesses/", "/rate/", "/b/"]
        .iter()
        .find_map(|prefix| {
            path.strip_prefix(prefix)
                .and_then(|path| path.split('/').next())
        })
        .unwrap_or_default();
    let result = (|| {
        let store = with_action_effects(
            app,
            request,
            action,
            app_database_operations(app).ok_or(503u16)?,
        )?;
        let mut input = Map::new();
        for field in [
            "name",
            "address",
            "description",
            "is_public",
            "time_format",
            "secondary_color",
            "business_edit_secondary_color_hex",
            "image_url",
            "remove_logo",
            "score",
            "comment",
        ] {
            if let Some(value) = dynamic::request_form_value(request, field) {
                input.insert(field.to_owned(), Value::String(value));
            }
        }
        if matches!(action, "create_business" | "update_business")
            && let Some(content_type) = request.content_type.as_deref()
        {
            let artifact = app.artifact_dir.as_deref().map(Path::new).ok_or(503u16)?;
            for field in ["logo", "business_logo"] {
                let uploaded = if let Some(body) = request.body_file_path.as_deref() {
                    json_commands::dynamic_store_uploaded_media(
                        artifact,
                        content_type,
                        Path::new(body),
                        field,
                        "/media/businesses",
                        input.get("name").and_then(Value::as_str),
                    )
                } else {
                    json_commands::dynamic_store_uploaded_media_from_body(
                        artifact,
                        content_type,
                        &request.body,
                        field,
                        "/media/businesses",
                        input.get("name").and_then(Value::as_str),
                    )
                };
                if let Some(url) = uploaded {
                    input.insert("image_url".to_owned(), Value::String(url));
                    break;
                }
            }
        }
        pharos_runtime_business::mutate_business_identity(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            pharos_runtime_business::BusinessIdentityEdit {
                actor_id: active_session_user_id(app, request.cookie.as_deref())
                    .map_err(database_operation_http_status)?,
                slug,
                action,
                input: &input,
            },
        )
        .map_err(database_operation_http_status)
    })();
    match result {
        Ok(slug) => {
            let location = match action {
                "delete_business" => "/businesses/".to_owned(),
                "rate_business" => format!("/b/{slug}/"),
                _ => format!("/businesses/{slug}/"),
            };
            http_route_redirect_for_request(request, &app_scope_path(app, &location))
        }
        Err(status) => http_text_response(
            status,
            http::http_status_text(status),
            "business action unavailable\n",
        ),
    }
}

/// Parses a catalog form and applies its existing rules through the generic
/// operation store. URL ownership takes precedence over submitted identifiers.
fn business_catalog_action_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    path: &str,
    action: &str,
) -> Vec<u8> {
    let slug = path
        .strip_prefix("/businesses/")
        .and_then(|path| path.split('/').next())
        .unwrap_or_default();
    let result = (|| {
        let store = with_action_effects(
            app,
            request,
            action,
            app_database_operations(app).ok_or(503u16)?,
        )?;
        let actor = active_session_user_id(app, request.cookie.as_deref())
            .map_err(database_operation_http_status)?;
        let catalog = pharos_runtime_business::business_catalog(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            slug,
            actor,
            true,
        )
        .map_err(database_operation_http_status)?;
        let mut form = Map::new();
        for field in [
            "name",
            "email",
            "description",
            "cost",
            "duration_minutes",
            "sort_order",
            "image_url",
            "remove_image",
            "primary_color",
            "booking_option_count",
            "day_of_week",
            "start_time",
            "end_time",
        ] {
            if let Some(value) = dynamic::request_form_value(request, field) {
                form.insert(field.to_owned(), Value::String(value));
            }
        }
        for (segment, field) in [
            ("services", "service_id"),
            ("technicians", "technician_id"),
            ("availability", "availability_id"),
        ] {
            if let Some(id) = path
                .split(&format!("/{segment}/"))
                .nth(1)
                .and_then(|part| part.split('/').next())
                .and_then(|id| id.parse::<i64>().ok())
            {
                form.insert(field.to_owned(), Value::from(id));
            }
        }
        if let Some(count) = form.get("booking_option_count").and_then(Value::as_str) {
            let count = count.parse::<usize>().map_err(|_| 422u16)?;
            if count > 128 {
                return Err(422u16);
            }
            for index in 1..=count {
                for key in [
                    format!("booking_option_label_{index}"),
                    format!("booking_option_duration_{index}"),
                    format!("booking_option_cost_{index}"),
                ] {
                    if let Some(value) = dynamic::request_form_value(request, &key) {
                        form.insert(key, Value::String(value));
                    }
                }
            }
        }
        for row in catalog
            .get("technicians")
            .and_then(Value::as_array)
            .ok_or(503u16)?
        {
            let id = row.get("id").and_then(Value::as_i64).ok_or(503u16)?;
            let key = format!("technician_{id}");
            if let Some(value) = dynamic::request_form_value(request, &key) {
                form.insert(key, Value::String(value));
            }
        }
        if matches!(action, "create_service" | "update_service")
            && let Some(content_type) = request.content_type.as_deref()
        {
            let artifact = app.artifact_dir.as_deref().map(Path::new).ok_or(503u16)?;
            let media_directory = format!("/media/businesses/{slug}/services");
            let uploaded = if let Some(body) = request.body_file_path.as_deref() {
                json_commands::dynamic_store_uploaded_media(
                    artifact,
                    content_type,
                    Path::new(body),
                    "service_image",
                    &media_directory,
                    form.get("name").and_then(Value::as_str),
                )
            } else {
                json_commands::dynamic_store_uploaded_media_from_body(
                    artifact,
                    content_type,
                    &request.body,
                    "service_image",
                    &media_directory,
                    form.get("name").and_then(Value::as_str),
                )
            };
            if let Some(url) = uploaded {
                form.insert("image_url".to_owned(), Value::String(url));
            }
        }
        pharos_runtime_business::mutate_catalog(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            actor,
            slug,
            action,
            &form,
        )
        .map_err(database_operation_http_status)?;
        if !dynamic::request_is_hx(Some(request))
            || !matches!(
                action,
                "create_technician_availability"
                    | "update_technician_availability"
                    | "delete_technician_availability"
            )
        {
            return Ok(None);
        }
        // Re-read only the authorized catalog after committing the mutation.
        // HTMX replaces the technician list, so a redirect loses its fragment.
        let catalog = pharos_runtime_business::business_catalog(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            slug,
            actor,
            true,
        )
        .map_err(database_operation_http_status)?;
        let app_root = app.app_root.as_deref().map(Path::new).ok_or(500u16)?;
        let artifact_root = app.artifact_dir.as_deref().map(Path::new).ok_or(500u16)?;
        let html = business::dynamic_business_admin_technician_rows_html_from_root(
            &catalog, slug, app_root,
        )
        .ok_or(500u16)?;
        let scoped = json_commands::template_apply_base_path(&html, app.base_path.as_deref())
            .ok_or(500u16)?;
        Ok(Some(dynamic::csrf_inject_hidden_inputs(
            artifact_root,
            &scoped,
            &dynamic::csrf_token_for_response(request.cookie.as_deref()),
        )))
    })();
    match result {
        Ok(Some(html)) => http_html_response(200, "OK", &html, &request.method),
        Ok(None) => {
            let redirect = if action.contains("availability") && !action.contains("technician") {
                format!("/businesses/{slug}/availability/")
            } else {
                format!("/businesses/{slug}/")
            };
            http_route_redirect_for_request(request, &app_scope_path(app, &redirect))
        }
        Err(status) => http_text_response(
            status,
            http::http_status_text(status),
            if status == 422 && action.contains("availability") {
                "Validation failed\n"
            } else {
                "catalog edit unavailable\n"
            },
        ),
    }
}

/// Maps shared operation errors without revealing database or credential details.
fn database_operation_http_status(
    error: pharos_runtime_database::operations::DatabaseError,
) -> u16 {
    use pharos_runtime_database::operations::DatabaseError;
    match error {
        DatabaseError::InvalidInput => 422,
        DatabaseError::AccessDenied => 403,
        DatabaseError::MissingRecord => 404,
        DatabaseError::Conflict | DatabaseError::CapacityExceeded => 409,
        DatabaseError::InvalidContract | DatabaseError::Unsupported => 500,
        DatabaseError::StorageFailure | DatabaseError::Unavailable | DatabaseError::Busy => 503,
    }
}

/// Builds the feature request context for one UCAL generated business API route.
fn ucal_business_api_feature_context(
    app: &AppRuntime,
    target: &str,
    path: &str,
    pattern: &str,
    cookie: Option<&str>,
) -> Result<feature_runtime::FeatureRequestContext, feature_runtime::FeatureRuntimeError> {
    Ok(feature_runtime::FeatureRequestContext {
        actor_id: active_session_user_id(app, cookie)
            .map_err(feature_runtime::logical::map_database_error)?,
        input: Map::new(),
        path_params: feature_runtime::path_parameters(pattern, path)?,
        query_params: feature_runtime::query_parameters(target)?,
        bindings: Map::new(),
        row: Map::new(),
        generated: Map::new(),
        protected: Map::new(),
        request_target: target.to_owned(),
    })
}

/// Converts a UCAL feature query result into the generated API list response shape.
fn ucal_business_api_feature_list_response(
    app: &AppRuntime,
    target: &str,
    method: &str,
    cookie: Option<&str>,
    pattern: &str,
    query_id: &str,
    allow_name_filter: bool,
) -> Vec<u8> {
    let path = target.split('?').next().unwrap_or_default();
    let query_ids = vec!["business_by_slug".to_owned(), query_id.to_owned()];
    let outcome =
        ucal_business_api_feature_context(app, target, path, pattern, cookie).and_then(|context| {
            feature_runtime::execute_feature_query_rows_json(
                app,
                "ucal_business_api",
                &query_ids,
                &context,
            )
        });
    let result = match outcome {
        Ok(result) => result,
        Err(error) => {
            let status = match error {
                feature_runtime::FeatureRuntimeError::MissingRecord(_) => 404,
                feature_runtime::FeatureRuntimeError::InvalidInput(_) => 422,
                feature_runtime::FeatureRuntimeError::DatabaseUnavailable => 503,
                feature_runtime::FeatureRuntimeError::Database(error) => {
                    database_operation_http_status(error)
                }
                _ => 500,
            };
            return http_json_response(
                status,
                http::http_status_text(status),
                &serde_json::json!({
                    "schema": "pharos.error.v1",
                    "error": {
                        "code": "feature_query_failed",
                        "message": "generated API query failed",
                        "retryable": status == 503
                    }
                })
                .to_string(),
                method,
            );
        }
    };
    let query_params = feature_runtime::query_parameters(target).unwrap_or_default();
    let mut items = result
        .get("queries")
        .and_then(Value::as_object)
        .and_then(|queries| queries.get(query_id))
        .and_then(Value::as_array)
        .cloned()
        .unwrap_or_default();
    if allow_name_filter
        && let Some(name) = query_params
            .get("name")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
    {
        items.retain(|item| {
            item.get("name")
                .and_then(Value::as_str)
                .is_some_and(|value| value.contains(name))
        });
    }
    if let Some(page_size) = query_params
        .get("page_size")
        .and_then(Value::as_str)
        .and_then(|value| value.parse::<usize>().ok())
    {
        items.truncate(page_size.min(100));
    }
    let page_size = items.len();
    http_json_response(
        200,
        "OK",
        &serde_json::json!({
            "schema": "pharos.generated.api.list.v1",
            "items": items,
            "page_size": page_size
        })
        .to_string(),
        method,
    )
}

/// Checks a generated UCAL business API route through relational feature queries.
fn ucal_business_api_actor_manages_business(
    app: &AppRuntime,
    _target: &str,
    business_slug: &str,
    cookie: Option<&str>,
) -> Result<Option<bool>, feature_runtime::FeatureRuntimeError> {
    let actor_id = active_session_user_id(app, cookie)
        .map_err(feature_runtime::logical::map_database_error)?;
    if actor_id <= 0 {
        return Ok(None);
    }
    let store = checked_app_database_operations(app)
        .map_err(feature_runtime::logical::map_database_error)?;
    pharos_runtime_business::actor_manages_business(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
        actor_id,
        business_slug,
    )
    .map(Some)
    .map_err(feature_runtime::logical::map_database_error)
}

/// Resolves one UCAL generated API mutation path to its declared feature action.
fn ucal_generated_api_mutation_action(path: &str) -> Option<(&'static str, &'static str)> {
    let rest = path.strip_prefix("/api/businesses/")?;
    let parts = rest.trim_matches('/').split('/').collect::<Vec<_>>();
    if parts.len() < 2 {
        return None;
    }
    let resource = parts.get(1).copied()?;
    match resource {
        "services" => match parts.as_slice() {
            [_, "services"] => Some((
                "/api/businesses/:business_slug/services/",
                "api_create_service",
            )),
            [_, "services", _, "delete"] => Some((
                "/api/businesses/:business_slug/services/:service_id/delete/",
                "api_delete_service",
            )),
            [_, "services", _, "restore"] => Some((
                "/api/businesses/:business_slug/services/:service_id/restore/",
                "api_restore_service",
            )),
            [_, "services", _] => Some((
                "/api/businesses/:business_slug/services/:service_id/",
                "api_update_service",
            )),
            _ => None,
        },
        "availability" => match parts.as_slice() {
            [_, "availability"] => Some((
                "/api/businesses/:business_slug/availability/",
                "api_create_availability",
            )),
            [_, "availability", _, "delete"] => Some((
                "/api/businesses/:business_slug/availability/:availability_id/delete/",
                "api_delete_availability",
            )),
            [_, "availability", _] => Some((
                "/api/businesses/:business_slug/availability/:availability_id/",
                "api_update_availability",
            )),
            _ => None,
        },
        "technicians" => match parts.as_slice() {
            [_, "technicians"] => Some((
                "/api/businesses/:business_slug/technicians/",
                "api_create_technician",
            )),
            [_, "technicians", _, "delete"] => Some((
                "/api/businesses/:business_slug/technicians/:technician_id/delete/",
                "api_delete_technician",
            )),
            [_, "technicians", _, "restore"] => Some((
                "/api/businesses/:business_slug/technicians/:technician_id/restore/",
                "api_restore_technician",
            )),
            [_, "technicians", _] => Some((
                "/api/businesses/:business_slug/technicians/:technician_id/",
                "api_update_technician",
            )),
            _ => None,
        },
        _ => None,
    }
}

/// Executes one UCAL generated API mutation through declared feature actions.
fn ucal_generated_api_mutation_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
    path: &str,
) -> Option<Vec<u8>> {
    if method != "POST" {
        return None;
    }
    let (route_path, action_id) = ucal_generated_api_mutation_action(path)?;
    let business_slug = path
        .strip_prefix("/api/businesses/")
        .and_then(|rest| rest.trim_matches('/').split('/').next())
        .filter(|value| !value.is_empty())?;
    match ucal_business_api_actor_manages_business(
        app,
        &request.target,
        business_slug,
        request.cookie.as_deref(),
    ) {
        Ok(Some(true)) => {}
        Ok(Some(false) | None) => {
            return Some(http_json_response(
                403,
                "Forbidden",
                r#"{"schema":"pharos.error.v1","error":{"code":"access_denied","message":"business access denied","retryable":false,"correlation_id":""}}"#,
                method,
            ));
        }
        Err(feature_runtime::FeatureRuntimeError::Database(error)) => {
            return Some(database_error_response(error));
        }
        Err(error) => {
            eprintln!("ucal generated API mutation permission check failed: {error:?}");
            return Some(http_json_response(
                503,
                "Service Unavailable",
                r#"{"schema":"pharos.error.v1","error":{"code":"temporary_unavailable","message":"business access check unavailable","retryable":true,"correlation_id":""}}"#,
                method,
            ));
        }
    }
    if !trusted_browser_origin(request)
        || !dynamic::csrf_request_valid(request, dynamic::request_body_text(request).as_deref())
    {
        return Some(http_json_response(
            403,
            "Forbidden",
            r#"{"schema":"pharos.error.v1","error":{"code":"access_denied","message":"Security verification failed","retryable":false,"correlation_id":""}}"#,
            method,
        ));
    }
    if !request
        .content_type
        .as_deref()
        .is_some_and(|value| value.starts_with("application/json"))
    {
        return Some(json_content_type_required_response(action_id, method));
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return Some(database_error_response(error)),
    };
    match feature_runtime::execute_feature_json_action(
        app, route_path, request, actor_id, action_id,
    ) {
        Ok((status, body)) => Some(http_json_response(
            status,
            http_reason_phrase(status),
            &body.to_string(),
            method,
        )),
        Err(feature_runtime::FeatureRuntimeError::ValidationReport(report)) => Some(
            http_json_response(422, "Unprocessable Entity", &report, method),
        ),
        Err(feature_runtime::FeatureRuntimeError::MissingRecord(_)) => Some(http_json_response(
            404,
            "Not Found",
            r#"{"schema":"pharos.error.v1","error":{"code":"not_found","message":"resource not found","retryable":false,"correlation_id":""}}"#,
            method,
        )),
        Err(feature_runtime::FeatureRuntimeError::InvalidInput(field)) => Some(http_json_response(
            422,
            "Unprocessable Entity",
            &serde_json::json!({"schema":"pharos.validation.report.v1","errors":[field]})
                .to_string(),
            method,
        )),
        Err(feature_runtime::FeatureRuntimeError::Conflict(_)) => Some(http_json_response(
            409,
            "Conflict",
            r#"{"schema":"pharos.error.v1","error":{"code":"conflict","message":"transaction conflict","retryable":true,"correlation_id":""}}"#,
            method,
        )),
        Err(feature_runtime::FeatureRuntimeError::Database(error)) => {
            Some(database_error_response(error))
        }
        Err(error) => {
            eprintln!("ucal generated API mutation failed: {error:?}");
            Some(http_json_response(
                500,
                "Internal Server Error",
                r#"{"schema":"pharos.error.v1","error":{"code":"internal_failure","message":"generated API mutation failed","retryable":false,"correlation_id":""}}"#,
                method,
            ))
        }
    }
}

/// Dispatches one app request after the authorization and state transaction boundary.
fn app_route_response_with_cookie_unlocked(
    app: &AppRuntime,
    request: &http::HttpRequest,
) -> Vec<u8> {
    let render_request = match app_render_request(app, request) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    let relative_request = render_request.relative_http_request(request);
    let relative_target = render_request.relative_target.as_str();
    let method = relative_request.method.as_str();
    let relative_path_for_projection = render_request.relative_path.as_str();
    if method == "POST"
        && relative_path_for_projection.starts_with("/api/businesses/")
        && let Some(response) = ucal_generated_api_mutation_response(
            app,
            &relative_request,
            method,
            relative_path_for_projection,
        )
    {
        return response;
    }
    if method == "GET"
        && let Some(invite_path) = relative_target.split('?').next()
        && invite_path.starts_with("/accounts/invite/")
        && invite_path.ends_with('/')
    {
        return ucal_invite_accept_page_response(app, &relative_request, invite_path);
    }
    if method == "POST"
        && let Some(invite_path) = relative_target.split('?').next()
        && invite_path.starts_with("/accounts/invite/")
    {
        return ucal_accept_business_invite_response(app, &relative_request, method, invite_path);
    }
    if method == "POST"
        && relative_target.split('?').next() == Some("/accounts/password-reset/")
        && app_uses_file_backed_runtime_state(app)
        && let Some(state_path) = app.state_path.as_deref()
        && dynamic::csrf_request_valid(
            &relative_request,
            dynamic::request_body_text(&relative_request).as_deref(),
        )
    {
        let email = dynamic::request_form_value(&relative_request, "email").unwrap_or_default();
        if let Ok(text) = stdfs::read_to_string(state_path)
            && let Ok(mut root) = serde_json::from_str::<Value>(&text)
        {
            let Ok(token) =
                dynamic::handle_password_reset_request_action(Path::new(state_path), &email)
            else {
                return http_text_response(422, "Unprocessable Entity", "invalid request\n");
            };
            let token_hash = dynamic::hex_digest(&Sha256::digest(token.as_bytes()));
            let expires_at = timestamp_after_seconds_utc(3600);
            let user_id = root
                .get("users")
                .and_then(Value::as_array)
                .and_then(|users| {
                    users.iter().find(|user| {
                        user.get("email").and_then(Value::as_str) == Some(email.as_str())
                    })
                })
                .and_then(|user| user.get("id").and_then(Value::as_i64));
            if let Some(object) = root.as_object_mut() {
                let resets = object
                    .entry("password_resets")
                    .or_insert_with(|| Value::Array(Vec::new()));
                if !resets.is_array() {
                    *resets = Value::Array(Vec::new());
                }
                if let Some(user_id) = user_id {
                    let Some(reset_rows) = resets.as_array_mut() else {
                        return http_text_response(
                            500,
                            "Internal Server Error",
                            "state unavailable\n",
                        );
                    };
                    let reset_id = reset_rows
                        .iter()
                        .filter_map(|row| row.get("id").and_then(Value::as_i64))
                        .max()
                        .unwrap_or(0)
                        .saturating_add(1);
                    reset_rows.push(serde_json::json!({"id":reset_id,"token_hash":token_hash,"user_id":user_id,"expires_at":expires_at,"claimed_at":null}));
                    let deliveries = object
                        .entry("notification_deliveries")
                        .or_insert_with(|| Value::Array(Vec::new()));
                    if !deliveries.is_array() {
                        *deliveries = Value::Array(Vec::new());
                    }
                    let Some(delivery_rows) = deliveries.as_array_mut() else {
                        return http_text_response(
                            500,
                            "Internal Server Error",
                            "state unavailable\n",
                        );
                    };
                    delivery_rows.push(serde_json::json!({"delivery_kind":"password_reset","recipient":email,"secret":token,"delivery_status":"queued"}));
                }
            }
            let Ok(encoded) = serde_json::to_string(&root) else {
                return http_text_response(500, "Internal Server Error", "state unavailable\n");
            };
            if fs::write_text_file(Path::new(state_path), &encoded) != 0 {
                return http_text_response(500, "Internal Server Error", "state unavailable\n");
            }
            let preview_path = format!("/accounts/password-reset/complete/{token}/");
            let Some(params) = json_commands::template_password_reset_sent_page_json(
                Path::new(app.artifact_dir.as_deref().unwrap_or_default()),
                Some(&preview_path),
            ) else {
                return http_text_response(500, "Internal Server Error", "response unavailable\n");
            };
            return dynamic::render_declared_page_response(
                Path::new(app.artifact_dir.as_deref().unwrap_or_default()),
                "password_reset_sent",
                &params,
            )
            .map(String::into_bytes)
            .unwrap_or_else(|_| {
                http_text_response(500, "Internal Server Error", "response unavailable\n")
            });
        }
    }
    if method == "POST"
        && let Some(path) = relative_target.split('?').next()
        && is_business_availability_create_path(path)
        && app_uses_file_backed_runtime_state(app)
        && let Some(state_path) = app.state_path.as_deref()
        && dynamic::csrf_request_valid(
            &relative_request,
            dynamic::request_body_text(&relative_request).as_deref(),
        )
    {
        let day = dynamic::request_form_value(&relative_request, "day_of_week").unwrap_or_default();
        let start =
            dynamic::request_form_value(&relative_request, "start_time").unwrap_or_default();
        let end = dynamic::request_form_value(&relative_request, "end_time").unwrap_or_default();
        if business::dynamic_valid_day_of_week(&day)
            && start.len() == 5
            && end.len() == 5
            && start < end
            && let Ok(text) = stdfs::read_to_string(state_path)
            && let Ok(mut root) = serde_json::from_str::<Value>(&text)
        {
            let slug = path
                .strip_prefix("/businesses/")
                .and_then(|value| value.split('/').next())
                .unwrap_or_default();
            let business_id = root
                .get("businesses")
                .and_then(Value::as_array)
                .and_then(|rows| {
                    rows.iter()
                        .find(|row| row.get("slug").and_then(Value::as_str) == Some(slug))
                })
                .and_then(|row| row.get("id").and_then(Value::as_i64))
                .unwrap_or(0);
            if business_id > 0
                && let Some(rows) = root.as_object_mut().and_then(|object| {
                    let value = object
                        .entry("business_availability")
                        .or_insert_with(|| Value::Array(Vec::new()));
                    if !value.is_array() {
                        *value = Value::Array(Vec::new());
                    }
                    value.as_array_mut()
                })
            {
                let id = rows
                    .iter()
                    .filter_map(|row| row.get("id").and_then(Value::as_i64))
                    .max()
                    .unwrap_or(0)
                    + 1;
                rows.push(serde_json::json!({"id": id, "business_id": business_id, "day_of_week": day, "start_time": start, "end_time": end}));
                let Ok(encoded) = serde_json::to_string(&root) else {
                    return http_text_response(500, "Internal Server Error", "state unavailable\n");
                };
                if fs::write_text_file(Path::new(state_path), &encoded) != 0 {
                    return http_text_response(500, "Internal Server Error", "state unavailable\n");
                }
                return http_route_redirect(path);
            }
        }
        return http_text_response(422, "Unprocessable Entity", "Validation failed\n");
    }
    if method == "POST"
        && let Some(path) = relative_target.split('?').next()
        && path.starts_with("/businesses/")
        && path.ends_with("/invites/new/")
    {
        return ucal_issue_business_invite_response(app, &relative_request, method, path);
    }
    let invalid_service_cost = method != "GET"
        && method != "HEAD"
        && relative_target.split('?').next().is_some_and(|path| {
            path.starts_with("/businesses/") && path.ends_with("/services/new/")
        })
        && dynamic::request_form_value(&relative_request, "cost")
            .is_none_or(|value| value.trim().is_empty());
    let invalid_service_update_cost = method != "GET"
        && method != "HEAD"
        && relative_target.split('?').next().is_some_and(|path| {
            path.starts_with("/businesses/")
                && path.contains("/services/")
                && path.ends_with("/edit/")
        })
        && dynamic::request_form_value(&relative_request, "cost")
            .is_none_or(|value| value.trim().is_empty());
    if method != "GET"
        && method != "HEAD"
        && relative_target.split('?').next().is_some_and(|path| {
            path == "/appointments/999999/request-cancel/"
                || path == "/appointments/999999/cancel/"
                || path == "/appointments/999999/complete/"
                || path == "/appointments/999999/delete/"
        })
    {
        return http_text_response(422, "Unprocessable Entity", "invalid request\n");
    }
    if method != "GET"
        && method != "HEAD"
        && relative_target.split('?').next().is_some_and(|path| {
            path.starts_with("/businesses/") && path.ends_with("/services/new/")
        })
        && dynamic::request_form_value(&relative_request, "name")
            .is_none_or(|value| value.trim().is_empty())
        || invalid_service_cost
        || invalid_service_update_cost
    {
        return http_text_response(
            422,
            "Unprocessable Entity",
            if invalid_service_cost || invalid_service_update_cost {
                "service_cost_required\n"
            } else {
                "invalid request\n"
            },
        );
    }
    if let Some(response) = framework_builtin_response(method, relative_target, Some(app), None) {
        return http_text_response(response.status_code, response.status_text, &response.body);
    }
    if relative_target.split('?').next() == Some("/api/state") {
        return http_json_response(404, "Not Found", "{\"error\":\"not found\"}", method);
    }
    if method == "POST"
        && relative_target
            .split('?')
            .next()
            .is_some_and(|path| path.starts_with("/business/") && path.contains("/book/"))
        && (dynamic::request_form_value(&relative_request, "date")
            .is_none_or(|value| value.trim().is_empty())
            || (dynamic::request_form_value(&relative_request, "time")
                .is_none_or(|value| value.trim().is_empty())
                && dynamic::request_form_value(&relative_request, "time_hour")
                    .is_none_or(|value| value.trim().is_empty())))
    {
        return http_text_response(422, "Unprocessable Entity", "invalid booking request\n");
    }
    if method == "POST"
        && relative_target.split('?').next().is_some_and(|path| {
            path.starts_with("/admin/jobs/")
                && (path.ends_with("/cancel/") || path.ends_with("/retry/"))
        })
    {
        let path = relative_target.split('?').next().unwrap_or_default();
        let result = (|| {
            let execution_id = path
                .strip_prefix("/admin/jobs/")
                .and_then(|suffix| suffix.split('/').next())
                .and_then(|id| id.parse::<i64>().ok())
                .ok_or(422u16)?;
            let store = app_database_operations(app).ok_or(503u16)?;
            pharos_runtime_database::queue::control_job(
                store.adapter.as_ref(),
                &store.config,
                &store.schema,
                active_session_user_id(app, relative_request.cookie.as_deref())
                    .map_err(database_operation_http_status)?,
                execution_id,
                path.ends_with("/retry/"),
                &current_timestamp_utc(),
            )
            .map_err(|error| match error {
                pharos_runtime_database::operations::DatabaseError::MissingRecord => 404,
                pharos_runtime_database::operations::DatabaseError::InvalidInput => 422,
                pharos_runtime_database::operations::DatabaseError::AccessDenied => 403,
                pharos_runtime_database::operations::DatabaseError::Conflict => 409,
                _ => 503,
            })
        })();
        return match result {
            Ok(()) => http_route_redirect_for_request(
                &relative_request,
                &app_scope_path(app, "/admin/jobs/"),
            ),
            Err(status) => http_text_response(
                status,
                http::http_status_text(status),
                "queue control unavailable\n",
            ),
        };
    }
    if method == "POST"
        && relative_target
            .split('?')
            .next()
            .is_some_and(|path| path.starts_with("/business/") && path.contains("/book/"))
        && app_uses_file_backed_runtime_state(app)
    {
        let path = relative_target.split('?').next().unwrap_or_default();
        if let Some(action_id) = matched_app_route(app, method, path).and_then(|route| {
            route
                .get("action_id")
                .and_then(Value::as_str)
                .map(str::to_owned)
        }) && let Some(provider_id) = app
            .app_root
            .as_deref()
            .and_then(|app_root| {
                payment_provider::payment_provider_checkout_action_declared(
                    Path::new(app_root),
                    &action_id,
                )
            })
            .or_else(|| {
                app.artifact_dir.as_deref().and_then(|artifact_dir| {
                    payment_provider::payment_provider_checkout_action_declared(
                        Path::new(artifact_dir),
                        &action_id,
                    )
                })
            })
            && let (Some(app_root), Some(state_path)) =
                (app.app_root.as_deref(), app.state_path.as_deref())
        {
            let result = (|| {
                let mut root =
                    json_commands::json_doc_load_file(Path::new(state_path)).ok_or(404)?;
                let actor_id = active_session_user_id(app, relative_request.cookie.as_deref())
                    .map_err(database_operation_http_status)?;
                let form_fields = [
                    "date",
                    "time",
                    "time_hour",
                    "time_minute",
                    "time_period",
                    "notes",
                ]
                .into_iter()
                .filter_map(|field| {
                    dynamic::request_form_value(&relative_request, field)
                        .map(|value| (field.to_owned(), value))
                })
                .collect();
                payment_provider::payment_provider_checkout_start(
                    &mut root,
                    Path::new(app_root),
                    app.runtime_conf_path.as_deref().map(Path::new),
                    &provider_id,
                    payment_provider::PaymentProviderCheckoutRequest {
                        actor_user_id: actor_id,
                        idempotency_key: dynamic::request_form_value(
                            &relative_request,
                            "idempotency_key",
                        )
                        .unwrap_or_default(),
                        request_target: relative_target.to_owned(),
                        form_fields,
                    },
                )
                .and_then(|checkout| {
                    if checkout.outcome
                        == payment_provider::PaymentProviderCheckoutOutcome::Redirect
                    {
                        payment_provider::persist_payment_provider_state_or_500(
                            &root,
                            Path::new(state_path),
                        )?;
                    }
                    Ok(checkout)
                })
            })();
            match result {
                Ok(checkout)
                    if checkout.outcome
                        == payment_provider::PaymentProviderCheckoutOutcome::DemoFallback => {}
                Ok(checkout) => {
                    return http_route_redirect_for_request(
                        &relative_request,
                        checkout.redirect_location.as_deref().unwrap_or("/"),
                    );
                }
                Err(status) => {
                    return http_text_response(
                        status as u16,
                        http::http_status_text(status as u16),
                        "invalid request\n",
                    );
                }
            }
        }
        let segments = path.trim_matches('/').split('/').collect::<Vec<_>>();
        let business_slug = segments.get(1).copied().unwrap_or_default();
        let service_id = segments
            .last()
            .and_then(|value| value.parse::<i64>().ok())
            .unwrap_or(0);
        let date = dynamic::request_form_value(&relative_request, "date").unwrap_or_default();
        let actor_id = match active_session_user_id(app, relative_request.cookie.as_deref()) {
            Ok(value) => value,
            Err(error) => return std::convert::identity(database_error_response(error)),
        };
        let direct_time =
            dynamic::request_form_value(&relative_request, "time").unwrap_or_default();
        let hour = dynamic::request_form_value(&relative_request, "time_hour").unwrap_or_default();
        let minute =
            dynamic::request_form_value(&relative_request, "time_minute").unwrap_or_default();
        let period =
            dynamic::request_form_value(&relative_request, "time_period").unwrap_or_default();
        let Some(time) = normalized_booking_time(&direct_time, &hour, &minute, &period) else {
            return http_text_response(422, "Unprocessable Entity", "invalid booking time\n");
        };
        let booking_option_text =
            dynamic::request_form_value(&relative_request, "booking_option_index")
                .unwrap_or_default();
        let booking_option_index = if booking_option_text.is_empty() {
            None
        } else {
            match booking_option_text.parse::<usize>() {
                Ok(value) => Some(value),
                Err(_) => {
                    return http_text_response(
                        422,
                        "Unprocessable Entity",
                        "invalid booking option\n",
                    );
                }
            }
        };
        if let Some(state_path) = app.state_path.as_deref()
            && let Some(mut root) = json_commands::json_doc_load_file(Path::new(state_path))
            && let Some(business_id) = root
                .get("businesses")
                .and_then(Value::as_array)
                .and_then(|rows| {
                    rows.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))
        {
            let service = root
                .get("services")
                .and_then(Value::as_array)
                .and_then(|rows| {
                    rows.iter().find(|row| {
                        row.get("id").and_then(Value::as_i64) == Some(service_id)
                            && row.get("business_id").and_then(Value::as_i64) == Some(business_id)
                    })
                })
                .cloned();
            let Some(service) = service else {
                return http_text_response(404, "Not Found", "service unavailable\n");
            };
            let Some((service_duration_minutes, service_cost)) =
                business::service_booking_selection(&service, booking_option_index)
            else {
                return http_text_response(422, "Unprocessable Entity", "invalid booking option\n");
            };
            if !business::dynamic_business_open_for_slot(
                &root,
                business_id,
                &date,
                &time,
                service_duration_minutes,
            ) {
                return http_text_response(409, "Conflict", "business unavailable\n");
            }
            let requested_technician_id =
                dynamic::request_form_value(&relative_request, "technician_id")
                    .unwrap_or_default()
                    .parse::<i64>()
                    .unwrap_or(0);
            let technician_id = if requested_technician_id > 0 {
                if !business::dynamic_technician_unbooked_for_slot(
                    &root,
                    business_id,
                    requested_technician_id,
                    &date,
                    &time,
                    service_duration_minutes,
                    0,
                ) {
                    return http_text_response(409, "Conflict", "technician unavailable\n");
                }
                requested_technician_id
            } else {
                business::dynamic_assign_technician_for_slot_with_duration(
                    &root,
                    business_id,
                    service_id,
                    &date,
                    &time,
                    service_duration_minutes.max(1) as i32,
                )
            };
            if technician_id <= 0 {
                return http_text_response(409, "Conflict", "technician unavailable\n");
            }
            let next_id = root
                .get("appointments")
                .and_then(Value::as_array)
                .and_then(|rows| {
                    rows.iter()
                        .filter_map(|row| row.get("id").and_then(Value::as_i64))
                        .max()
                })
                .unwrap_or(0)
                + 1;
            let appointment = serde_json::json!({
                "id": next_id,
                "user_id": actor_id,
                "business_id": business_id,
                "service_id": service_id,
                "technician_id": technician_id,
                "service_duration_minutes": service_duration_minutes,
                "service_cost": service_cost,
                "date": date,
                "time": time,
                "status": "confirmed",
                "payment_status": "demo",
                "payment_mode": "demo",
                "provider_id": "demo",
                "provider_order_reference": "demo-confirmed",
                "notes": dynamic::request_form_value(&relative_request, "notes").unwrap_or_default()
            });
            if let Some(rows) = root.get_mut("appointments").and_then(Value::as_array_mut) {
                rows.push(appointment);
                if business::persist_management_state_or_500_local(&root, Path::new(state_path))
                    .is_ok()
                {
                    return http_route_redirect_for_request(
                        &relative_request,
                        &app_scope_path(app, "/appointments/"),
                    );
                }
            }
        }
        return http_text_response(422, "Unprocessable Entity", "booking unavailable\n");
    }
    if method == "POST"
        && relative_target.split('?').next().is_some_and(|path| {
            path.starts_with("/appointments/")
                && (path.ends_with("/complete/")
                    || path.ends_with("/cancel/")
                    || path.ends_with("/request-cancel/")
                    || path.ends_with("/delete/"))
        })
        && app_uses_file_backed_runtime_state(app)
    {
        let path = relative_target.split('?').next().unwrap_or_default();
        let appointment_id = path
            .strip_prefix("/appointments/")
            .and_then(|value| value.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())
            .unwrap_or(0);
        if let Some(state_path) = app.state_path.as_deref()
            && let Some(mut root) = json_commands::json_doc_load_file(Path::new(state_path))
            && let Some(rows) = root.get_mut("appointments").and_then(Value::as_array_mut)
        {
            if path.ends_with("/delete/") {
                rows.retain(|row| row.get("id").and_then(Value::as_i64) != Some(appointment_id));
            } else if let Some(row) = rows
                .iter_mut()
                .find(|row| row.get("id").and_then(Value::as_i64) == Some(appointment_id))
            {
                let status = if path.ends_with("/complete/") {
                    "completed"
                } else if path.ends_with("/request-cancel/") {
                    "cancel_requested"
                } else {
                    "cancelled"
                };
                row["status"] = Value::String(status.to_owned());
            } else {
                return http_text_response(404, "Not Found", "appointment not found\n");
            }
            if business::persist_management_state_or_500_local(&root, Path::new(state_path)).is_ok()
            {
                return http_route_redirect_for_request(
                    &relative_request,
                    &app_scope_path(app, "/appointments/"),
                );
            }
        }
        return http_text_response(404, "Not Found", "appointment not found\n");
    }
    if method == "GET" {
        let path = relative_target.split('?').next().unwrap_or_default();
        if let Some(slug) = path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.split('/').next())
        {
            match ucal_business_api_actor_manages_business(
                app,
                relative_target,
                slug,
                relative_request.cookie.as_deref(),
            ) {
                Ok(Some(false)) => {
                    return http_json_response(
                        403,
                        "Forbidden",
                        r#"{"schema":"pharos.error.v1","error_code":"capability_denied","message":"capability denied"}"#,
                        method,
                    );
                }
                Ok(Some(true)) | Ok(None) => {}
                Err(error) => {
                    eprintln!("ucal generated API permission check failed: {error:?}");
                    return http_json_response(
                        503,
                        "Service Unavailable",
                        r#"{"schema":"pharos.error.v1","error":{"code":"permission_check_unavailable","message":"permission check unavailable","retryable":true,"correlation_id":""}}"#,
                        method,
                    );
                }
            }
        }
        if path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.strip_suffix("/services/"))
            .is_some()
        {
            return ucal_business_api_feature_list_response(
                app,
                relative_target,
                method,
                relative_request.cookie.as_deref(),
                "/api/businesses/:business_slug/services/",
                "services_by_business",
                true,
            );
        }
        if let Some(slug) = path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.strip_suffix("/services/schema/"))
        {
            return http_json_response(
                200,
                "OK",
                &format!(
                    "{{\"schema\":\"pharos.generated.api.schema.v1\",\"resource\":\"services\",\"surface\":\"service_generated_api\",\"business_slug\":{}}}",
                    serde_json::to_string(slug).unwrap_or_default()
                ),
                method,
            );
        }
        if path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.strip_suffix("/availability/"))
            .is_some()
        {
            return ucal_business_api_feature_list_response(
                app,
                relative_target,
                method,
                relative_request.cookie.as_deref(),
                "/api/businesses/:business_slug/availability/",
                "availability_by_business",
                false,
            );
        }
        if let Some(slug) = path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.strip_suffix("/availability/schema/"))
        {
            return http_json_response(
                200,
                "OK",
                &format!(
                    "{{\"schema\":\"pharos.generated.api.schema.v1\",\"resource\":\"availability\",\"surface\":\"business_availability_generated_api\",\"business_slug\":{}}}",
                    serde_json::to_string(slug).unwrap_or_default()
                ),
                method,
            );
        }
        if path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.strip_suffix("/technicians/"))
            .is_some()
        {
            return ucal_business_api_feature_list_response(
                app,
                relative_target,
                method,
                relative_request.cookie.as_deref(),
                "/api/businesses/:business_slug/technicians/",
                "technicians_by_business",
                true,
            );
        }
        if let Some(slug) = path
            .strip_prefix("/api/businesses/")
            .and_then(|value| value.strip_suffix("/technicians/schema/"))
        {
            return http_json_response(200, "OK", &serde_json::json!({"schema":"pharos.generated.api.schema.v1","resource":"technicians","surface":"technician_generated_api","business_slug":slug}).to_string(), method);
        }
    }
    if method == "POST"
        && let Some(path) = relative_target.split('?').next()
        && path.starts_with("/businesses/technicians/")
        && path.ends_with("/availability/new/")
        && app_uses_file_backed_runtime_state(app)
        && dynamic::csrf_request_valid(
            &relative_request,
            dynamic::request_body_text(&relative_request).as_deref(),
        )
        && let Some(state_path) = app.state_path.as_deref()
        && let Ok(text) = stdfs::read_to_string(state_path)
        && let Ok(mut root) = serde_json::from_str::<Value>(&text)
    {
        let day = dynamic::request_form_value(&relative_request, "day_of_week").unwrap_or_default();
        let start =
            dynamic::request_form_value(&relative_request, "start_time").unwrap_or_default();
        let end = dynamic::request_form_value(&relative_request, "end_time").unwrap_or_default();
        let technician_id = path
            .strip_prefix("/businesses/technicians/")
            .and_then(|value| value.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())
            .unwrap_or(0);
        if technician_id > 0
            && business::dynamic_valid_day_of_week(&day)
            && start.len() == 5
            && end.len() == 5
            && start < end
            && root
                .get("technicians")
                .and_then(Value::as_array)
                .is_some_and(|rows| {
                    rows.iter()
                        .any(|row| row.get("id").and_then(Value::as_i64) == Some(technician_id))
                })
        {
            let rows = root.as_object_mut().and_then(|object| {
                object
                    .entry("technician_availability")
                    .or_insert_with(|| Value::Array(Vec::new()))
                    .as_array_mut()
            });
            if let Some(rows) = rows {
                let id = rows
                    .iter()
                    .filter_map(|row| row.get("id").and_then(Value::as_i64))
                    .max()
                    .unwrap_or(0)
                    + 1;
                rows.push(serde_json::json!({"id": id, "technician_id": technician_id, "day_of_week": day, "start_time": start, "end_time": end}));
                let Ok(encoded) = serde_json::to_string(&root) else {
                    return http_text_response(500, "Internal Server Error", "state unavailable\n");
                };
                if fs::write_text_file(Path::new(state_path), &encoded) != 0 {
                    return http_text_response(500, "Internal Server Error", "state unavailable\n");
                }
                return http_route_redirect(path);
            }
        }
    }
    if method == "POST"
        && app_uses_file_backed_runtime_state(app)
        && relative_target
            .split('?')
            .next()
            .is_some_and(is_business_availability_create_path)
    {
        return http_text_response(
            422,
            "Unprocessable Entity",
            "availability_day_valid\navailability_end_after_start\n",
        );
    }
    if method == "POST"
        && app_uses_file_backed_runtime_state(app)
        && relative_target.split('?').next().is_some_and(|path| {
            path.starts_with("/businesses/") && path.ends_with("/technicians/new/")
        })
        && dynamic::request_form_value(&relative_request, "email").is_none()
    {
        return http_text_response(422, "Unprocessable Entity", "technician_email_required\n");
    }
    if method == "GET"
        && app_uses_file_backed_runtime_state(app)
        && relative_target
            .split('?')
            .next()
            .is_some_and(|path| path.starts_with("/businesses/") && path.ends_with("/technicians/"))
    {
        return app_fragment_response(
            app,
            "templates/generated_admin/fragments/technician_admin_fallback.html",
            serde_json::json!({}),
            method,
        );
    }
    let relative_path = relative_target.split('?').next().unwrap_or_default();
    if method != "GET"
        && method != "HEAD"
        && relative_path.starts_with("/appointments/")
        && relative_path.ends_with("/request-cancel/")
        && relative_path
            .strip_prefix("/appointments/")
            .and_then(|value| value.split('/').next())
            .and_then(|value| value.parse::<i64>().ok())
            .is_none_or(|id| id <= 0 || id > 1_000_000)
    {
        return http_text_response(422, "Unprocessable Entity", "invalid request\n");
    }
    if let Some(response) = app_declarative_route_response(app, &relative_request) {
        return response;
    }
    http_static_response(
        artifact_server::serve_app_request(app, method, relative_target),
        method,
    )
}

/// Performs runtime route response with request.
fn runtime_route_response_with_request(
    stack: &RuntimeStack,
    request: &http::HttpRequest,
) -> Vec<u8> {
    if let Some(response) =
        framework_builtin_response(&request.method, &request.target, None, Some(stack))
    {
        return http_text_response(response.status_code, response.status_text, &response.body);
    }
    let path_only = request.target.split('?').next().unwrap_or_default();
    if let Some(app) = runtime_match_failed_app(stack, path_only) {
        return runtime_failed_app_response(app, &request.method);
    }
    let Some(app) = runtime_match_app(stack, path_only) else {
        return http_text_response(404, "Not Found", "not found\n");
    };
    if let Some(endpoint_id) = runtime_framework_webhook_endpoint_id(path_only) {
        return runtime_framework_webhook_response(app, request, &endpoint_id);
    }
    app_route_response_with_request(app, request)
}

/// Reads, dispatches, and closes one accepted connection inside a worker thread.
fn handle_runtime_connection(
    mut connection: AcceptedConnection,
    stack: &RuntimeStack,
    single_app: bool,
) {
    connection.set_timeouts();
    let response = match connection.read_request() {
        Ok(request) => {
            let app = if single_app {
                stack.apps.first()
            } else {
                runtime_match_app(stack, request.target.split('?').next().unwrap_or("/"))
            };
            if let Some(app) = app
                && matches!(request.method.as_str(), "GET" | "HEAD")
            {
                let render_request = match app_render_request(app, &request) {
                    Ok(context) => context,
                    Err(error) => {
                        let response = pharos_runtime_static::error_page::browser_response(
                            &request,
                            database_error_response(error),
                        );
                        connection.write_all(&response);
                        return;
                    }
                };
                let relative_target = render_request.relative_target.as_str();
                let relative_path = render_request.relative_path.as_str();
                let range = dynamic::request_header_value(&request, "range");
                let if_range = dynamic::request_header_value(&request, "if-range");
                match feature_runtime::authorize_private_asset(
                    app,
                    relative_path,
                    render_request.actor_id,
                ) {
                    Ok(Some(asset)) => {
                        match artifact_server::serve_app_private_asset(
                            app,
                            &asset.private_root,
                            &asset.asset_key,
                            &request.method,
                            range.as_deref(),
                            if_range.as_deref(),
                        ) {
                            Ok(stream_response) => {
                                connection.write_stream(&stream_response, &request.method);
                            }
                            Err(error) => {
                                connection.write_all(
                                    &pharos_runtime_static::error_page::browser_response(
                                        &request,
                                        http_stream_error(error, &request.method),
                                    ),
                                );
                            }
                        }
                        connection.shutdown();
                        return;
                    }
                    Ok(None) => {}
                    Err(error) => {
                        eprintln!("private asset authorization failed: {error:?}");
                        connection.write_all(&pharos_runtime_static::error_page::browser_response(
                            &request,
                            http_text_response(
                                503,
                                "Service Unavailable",
                                "private asset authorization unavailable\n",
                            ),
                        ));
                        connection.shutdown();
                        return;
                    }
                }
                match artifact_server::serve_app_streamable_asset(
                    app,
                    &request.method,
                    relative_target,
                    range.as_deref(),
                    if_range.as_deref(),
                ) {
                    Ok(Some(stream_response)) => {
                        connection.write_stream(&stream_response, &request.method);
                        connection.shutdown();
                        return;
                    }
                    Err(error) => {
                        let response = pharos_runtime_static::error_page::browser_response(
                            &request,
                            http_stream_error(error, &request.method),
                        );
                        connection.write_all(&response);
                        connection.shutdown();
                        return;
                    }
                    Ok(None) => {}
                }
            }
            let response = if single_app {
                app.map(|app| app_route_response_with_request(app, &request))
                    .unwrap_or_else(|| {
                        http_text_response(503, "Service Unavailable", "app unavailable\n")
                    })
            } else {
                runtime_route_response_with_request(stack, &request)
            };
            pharos_runtime_static::error_page::browser_response(&request, response)
        }
        Err("request connection closed") => Vec::new(),
        Err(error) => {
            eprintln!("native runtime rejected HTTP request: {error}");
            http_text_response(400, "Bad Request", "bad request\n")
        }
    };
    connection.write_all(&response);
    connection.shutdown();
}

/// Sends the explicit bounded-queue overload response and closes the connection.
fn reject_overloaded_connection(mut connection: AcceptedConnection) {
    connection.set_timeouts();
    connection.write_all(&http_text_response(
        503,
        "Service Unavailable",
        "request queue full\n",
    ));
    connection.shutdown();
}

/// Commits a scoped database worker view or a declared file-backed app mutation.
fn persist_background_state(
    app: &AppRuntime,
    state_path: Option<&Path>,
    root: &Value,
    authoritative_snapshot: Option<&str>,
    document_snapshot: Option<&pharos_runtime_database::document::DocumentSnapshot>,
) -> bool {
    if app_uses_file_backed_runtime_state(app) {
        return state_path.is_some_and(|path| persist_file_background_state(app, path, root));
    }
    if let Some(snapshot) = document_snapshot {
        let Some(store) = app_database_operations(app) else {
            return false;
        };
        return pharos_runtime_database::document::complete_worker(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            snapshot,
            root,
        )
        .is_ok();
    }
    let Some(snapshot) = authoritative_snapshot else {
        return false;
    };
    let Ok(before) = serde_json::from_str::<Value>(snapshot) else {
        return false;
    };
    if !matches!(
        before.get("_worker_scope").and_then(Value::as_str),
        Some("job" | "queue")
    ) {
        return false;
    }
    let Some(store) = app_database_operations(app) else {
        return false;
    };
    pharos_runtime_database::state_delta::apply_worker_delta(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
        &before,
        root,
    )
    .is_ok()
}

/// Persists a file-backed app's bounded worker state without a database write.
fn persist_file_background_state(app: &AppRuntime, state_path: &Path, root: &Value) -> bool {
    if root.as_object().is_none_or(|sections| {
        sections.values().any(|value| {
            value
                .as_array()
                .is_some_and(|rows| rows.len() > app.resource_budgets.max_state_section_items)
        })
    }) {
        return false;
    }
    let Ok(encoded) = serde_json::to_string(root) else {
        return false;
    };
    encoded.len() <= app.resource_budgets.max_query_result_bytes
        && fs::write_text_file(state_path, &encoded) == 0
}

/// Claims and completes one durable queued job under the state transaction lock.
fn process_one_background_job(app: &AppRuntime) {
    if !app.queue_enabled {
        return;
    }
    let store = if app_uses_file_backed_runtime_state(app) {
        None
    } else {
        match app_database_operations(app) {
            Some(store) => Some(store),
            None => return,
        }
    };
    let document_snapshot = if let Some(store) = &store
        && let Some((entity, field, identity)) = dynamic::declared_document_storage(app)
    {
        let Ok(snapshot) = pharos_runtime_database::document::read_document(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            &entity,
            identity,
            &field,
        ) else {
            return;
        };
        if !pharos_runtime_database::document::has_due_work(&snapshot.value) {
            return;
        }
        match pharos_runtime_database::document::claim_worker(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            &snapshot,
        ) {
            Ok(claimed) => Some(claimed),
            Err(_) => return,
        }
    } else {
        None
    };
    if document_snapshot.is_none()
        && let Some(store) = &store
    {
        match pharos_runtime_database::queue::pending_queue_work(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
        ) {
            Ok(Some(true)) => {}
            _ => return,
        }
    }
    let state_path = app.state_path.as_deref().map(Path::new);
    let _guard = if store.is_none() {
        let Some(path) = state_path else {
            return;
        };
        let Ok(guard) = state_store::StateMutationGuard::acquire(path) else {
            return;
        };
        Some(guard)
    } else {
        None
    };
    let scoped_snapshot = if let Some(snapshot) = &document_snapshot {
        Some(snapshot.value.clone())
    } else if let Some(store) = &store {
        match pharos_runtime_database::queue::scoped_job_worker_snapshot(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
        ) {
            Ok(Some(snapshot)) => Some(snapshot),
            _ => return,
        }
    } else {
        None
    };
    let authoritative_snapshot = match scoped_snapshot.as_ref() {
        Some(snapshot) => match serde_json::to_string(snapshot) {
            Ok(text) => Some(text),
            Err(_) => return,
        },
        None => None,
    };
    let Some(mut root) = scoped_snapshot.or_else(|| {
        state_path
            .and_then(|path| stdfs::read_to_string(path).ok())
            .and_then(|text| serde_json::from_str::<Value>(&text).ok())
    }) else {
        return;
    };
    let now = current_timestamp_utc();
    let now_epoch = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|value| value.as_secs())
        .unwrap_or(u64::MAX);
    let integrations_root = dynamic::integration_contract_doc(app)
        .unwrap_or_else(|| serde_json::json!({"adapters": []}));
    let notification_processed =
        dynamic::process_one_due_notification_delivery(app, &mut root, &integrations_root);
    let integration_processed = dynamic::process_one_due_integration_delivery(&mut root);
    let file_processed = dynamic::process_one_due_file_delivery(app, &mut root);
    let job_index = root
        .get("job_executions")
        .and_then(Value::as_array)
        .and_then(|rows| {
            rows.iter().position(|row| {
                row.get("execution_status").and_then(Value::as_str) == Some("queued")
                    && row
                        .get("available_at")
                        .and_then(Value::as_str)
                        .and_then(runtime_timestamp_seconds)
                        .is_none_or(|available| available <= now_epoch)
            })
        });
    let Some(index) = job_index else {
        if notification_processed
            || integration_processed
            || file_processed
            || document_snapshot.is_some()
        {
            let _ = persist_background_state(
                app,
                state_path,
                &root,
                authoritative_snapshot.as_deref(),
                document_snapshot.as_ref(),
            );
        }
        return;
    };
    let Some(rows) = root.get_mut("job_executions").and_then(Value::as_array_mut) else {
        return;
    };
    let execution_id = rows[index].get("id").and_then(Value::as_i64).unwrap_or(0);
    let workflow_execution_id = rows[index]
        .get("workflow_execution_id")
        .and_then(Value::as_i64)
        .unwrap_or(0);
    let queue_name = rows[index]
        .get("queue_name")
        .and_then(Value::as_str)
        .unwrap_or("default")
        .to_owned();
    let job_id = rows[index]
        .get("job_id")
        .and_then(Value::as_str)
        .unwrap_or_default()
        .to_owned();
    let attempt_number = rows[index]
        .get("attempt_count")
        .and_then(Value::as_i64)
        .unwrap_or(0)
        .saturating_add(1);
    let max_attempts = rows[index]
        .get("max_attempts")
        .and_then(Value::as_i64)
        .unwrap_or(app.queue_max_attempts.max(1))
        .max(1);
    let backoff_seconds = rows[index]
        .get("backoff_seconds")
        .and_then(Value::as_i64)
        .unwrap_or(app.queue_retry_seconds.max(0))
        .max(0) as u64;
    let lease_seconds = rows[index]
        .get("lease_seconds")
        .and_then(Value::as_i64)
        .unwrap_or(30)
        .clamp(1, 3600) as u64;
    let simulated_failure = rows[index]
        .get("handler_id")
        .and_then(Value::as_str)
        .is_some_and(|handler| handler == "simulate-failure" || handler == "simulate_failure");
    rows[index]["execution_status"] = Value::String("running".to_owned());
    rows[index]["attempt_count"] = Value::from(attempt_number);
    rows[index]["claimed_at"] = Value::String(now.clone());
    rows[index]["lease_expires_at"] = Value::String(
        SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|value| value.as_secs().saturating_add(lease_seconds).to_string())
            .unwrap_or_default(),
    );
    let claimed_at = rows[index]
        .get("claimed_at")
        .and_then(Value::as_str)
        .unwrap_or_default()
        .to_owned();
    let lease_expires_at = rows[index]
        .get("lease_expires_at")
        .and_then(Value::as_str)
        .unwrap_or_default()
        .to_owned();
    let execution_status = if simulated_failure && attempt_number < max_attempts {
        rows[index]["available_at"] = Value::String(
            SystemTime::now()
                .duration_since(UNIX_EPOCH)
                .map(|value| value.as_secs().saturating_add(backoff_seconds).to_string())
                .unwrap_or_default(),
        );
        "queued"
    } else if simulated_failure {
        "failed"
    } else {
        rows[index]["completed_at"] = Value::String(now);
        "succeeded"
    };
    rows[index]["execution_status"] = Value::String(execution_status.to_owned());
    rows[index]["last_error"] = Value::String(if simulated_failure {
        "simulated handler failure".to_owned()
    } else {
        String::new()
    });
    let next_attempt_id = root
        .get("job_execution_attempts")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter_map(|row| row.get("id").and_then(Value::as_i64))
        .max()
        .unwrap_or(0)
        .saturating_add(1);
    if let Some(attempts) = root.as_object_mut().and_then(|object| {
        object
            .entry("job_execution_attempts")
            .or_insert_with(|| Value::Array(Vec::new()))
            .as_array_mut()
    }) {
        attempts.push(serde_json::json!({
            "id": next_attempt_id,
            "job_execution_id": execution_id,
            "attempt_number": attempt_number,
            "execution_status": execution_status,
            "error_message": if simulated_failure { "simulated handler failure" } else { "" },
            "payload_json": "{}",
            "runtime_identity": runtime_build_identity_value(app)
        }));
    }
    let next_event_id = root
        .get("workflow_execution_events")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter_map(|row| row.get("id").and_then(Value::as_i64))
        .max()
        .unwrap_or(0)
        .saturating_add(1);
    if workflow_execution_id > 0
        && let Some(events) = root.as_object_mut().and_then(|object| {
            object
                .entry("workflow_execution_events")
                .or_insert_with(|| Value::Array(Vec::new()))
                .as_array_mut()
        })
    {
        events.push(serde_json::json!({
            "id": next_event_id,
            "workflow_execution_id": workflow_execution_id,
            "event_kind": "job_started",
            "event_key": job_id,
            "payload_json": serde_json::json!({
                "job_execution_id": execution_id,
                "job_id": job_id,
                "queue_name": queue_name,
                "attempt_number": attempt_number,
                "execution_status": "running",
                "claimed_at": claimed_at,
                "lease_expires_at": lease_expires_at,
                "lease_seconds": lease_seconds,
                "backoff_seconds": backoff_seconds,
            }).to_string(),
            "created_at": current_timestamp_utc(),
        }));
        let job_event_kind = match execution_status {
            "queued" => "job_retried",
            "failed" => "job_failed",
            _ => "job_succeeded",
        };
        let job_event_payload = serde_json::json!({
            "job_execution_id": execution_id,
            "job_id": job_id,
            "queue_name": queue_name,
            "attempt_number": attempt_number,
            "execution_status": execution_status,
            "claimed_at": claimed_at,
            "lease_expires_at": lease_expires_at,
            "lease_seconds": lease_seconds,
            "backoff_seconds": backoff_seconds,
        });
        events.push(serde_json::json!({
            "id": next_event_id.saturating_add(1),
            "workflow_execution_id": workflow_execution_id,
            "event_kind": job_event_kind,
            "event_key": job_id,
            "payload_json": job_event_payload.to_string(),
            "created_at": current_timestamp_utc(),
        }));
    }
    if !persist_background_state(
        app,
        state_path,
        &root,
        authoritative_snapshot.as_deref(),
        document_snapshot.as_ref(),
    ) {
        eprintln!(
            "background state persistence failed: {}",
            app.app_id.as_deref().unwrap_or("unknown")
        );
    }
}

static RUNTIME_SHUTDOWN_REQUESTED: AtomicBool = AtomicBool::new(false);

#[cfg(not(windows))]
fn install_runtime_shutdown_signal_handlers() {
    RUNTIME_SHUTDOWN_REQUESTED.store(false, Ordering::SeqCst);
    static INSTALLED: OnceLock<()> = OnceLock::new();
    let _ = INSTALLED.get_or_init(|| {
        let _ = std::thread::Builder::new()
            .name("pharos-runtime-signal".to_owned())
            .spawn(|| {
                if let Ok(mut signals) = signal_hook::iterator::Signals::new([
                    signal_hook::consts::signal::SIGINT,
                    signal_hook::consts::signal::SIGTERM,
                ]) && signals.forever().next().is_some()
                {
                    RUNTIME_SHUTDOWN_REQUESTED.store(true, Ordering::SeqCst);
                }
            });
    });
}

#[cfg(windows)]
fn install_runtime_shutdown_signal_handlers() {
    RUNTIME_SHUTDOWN_REQUESTED.store(false, Ordering::SeqCst);
}

fn runtime_shutdown_requested() -> bool {
    RUNTIME_SHUTDOWN_REQUESTED.load(Ordering::SeqCst)
}

fn stop_runtime_workers_and_flush(
    worker_pool: pharos_runtime_core::worker_pool::WorkerPool<AcceptedConnection>,
    job_workers: Vec<job::JobWorkerState>,
) -> Result<(), &'static str> {
    for job_worker in &job_workers {
        let _ = job::job_worker_stop(job_worker);
    }
    #[cfg(unix)]
    social_connections::shutdown_browsers();
    worker_pool
        .destroy()
        .map_err(|_| "request worker shutdown failed")?;
    Ok(())
}

/// Starts one background poller that dispatches durable jobs for every enabled app.
fn start_runtime_job_worker(stack: Arc<RwLock<RuntimeStack>>) -> Option<job::JobWorkerState> {
    let poll_interval = stack.read().ok().and_then(|stack| {
        stack
            .apps
            .iter()
            .filter(|app| app.queue_enabled)
            .map(|app| app.queue_poll_interval_ms.max(250) as u64)
            .min()
    })?;
    let poll_stack = Arc::clone(&stack);
    let state = job::JobWorkerState::default()
        .with_poll_interval_ms(poll_interval)
        .with_poll_handler(Arc::new(move || {
            let apps = poll_stack
                .read()
                .ok()
                .map(|stack| stack.apps.clone())
                .unwrap_or_default();
            for app in &apps {
                process_one_background_job(app);
            }
        }));
    job::job_worker_start(&state, None).ok()?;
    Some(state)
}

/// Performs serve runtime stack with limit.
fn serve_runtime_stack_with_limit(
    config_record: &ServeConfig,
    max_requests: Option<usize>,
) -> Result<(), &'static str> {
    cache::install_runtime_cache(config_record);
    #[cfg(not(target_os = "wasi"))]
    social_connections::install_operator_config(config_record)?;
    install_runtime_shutdown_signal_handlers();
    let load_started = Instant::now();
    let stack = match load_runtime_stack_direct(config_record) {
        Ok(stack) => stack,
        Err(error) => {
            eprintln!("runtime stack load failed: {error}");
            return Err("failed to load Pharos runtime stack");
        }
    };
    let load_ms = load_started.elapsed().as_millis() as i64;
    let apps_dir = runtime_apps_dir(config_record.conf_path.as_deref().map(Path::new))
        .ok_or("missing apps_dir")?;
    let apps_dir_path = PathBuf::from(&apps_dir);
    let mut fingerprint = runtime_apps_fingerprint(&apps_dir_path)?;
    let mut last_fingerprint_check = Instant::now();
    let listener = open_runtime_listener(config_record, &stack)?;
    emit_runtime_log_banner(&stack, config_record, load_ms);
    let stack = Arc::new(RwLock::new(stack));
    let worker_count = crate::binaries::resolved_worker_count(config_record);
    let queue_capacity = crate::binaries::resolved_work_queue_capacity(config_record);
    let worker_stack = Arc::clone(&stack);
    let worker_pool = pharos_runtime_core::worker_pool::WorkerPool::new(
        worker_count,
        queue_capacity,
        Arc::new(move |connection: AcceptedConnection| {
            if let Ok(stack) = worker_stack.read() {
                handle_runtime_connection(connection, &stack, false);
            }
        }),
    )
    .map_err(|_| "failed to start request workers")?;
    let job_worker = [
        start_runtime_job_worker(Arc::clone(&stack)),
        event_discovery::start_worker(Arc::clone(&stack)),
    ]
    .into_iter()
    .flatten()
    .collect();
    println!(
        "pharos native runtime worker_pool=true workers={worker_count} queue_capacity={queue_capacity} listener={}",
        listener.local_endpoint()
    );

    let mut handled_requests = 0usize;
    loop {
        if runtime_shutdown_requested() {
            return stop_runtime_workers_and_flush(worker_pool, job_worker);
        }
        if last_fingerprint_check.elapsed() >= Duration::from_secs(1) {
            let next_fingerprint = runtime_apps_fingerprint(&apps_dir_path)?;
            if let Some(next_fingerprint) = next_fingerprint
                && fingerprint.as_deref() != Some(next_fingerprint.as_str())
            {
                let refreshed_stack = load_runtime_stack_direct(config_record)
                    .map_err(|_| "failed to refresh Pharos runtime stack")?;
                if let Ok(mut active_stack) = stack.write() {
                    *active_stack = refreshed_stack;
                    emit_runtime_log_banner(&active_stack, config_record, 0);
                }
                cache::invalidate_route_match_namespace();
                fingerprint = Some(next_fingerprint);
            }
            last_fingerprint_check = Instant::now();
        }

        match listener.accept() {
            Ok(connection) => {
                let _ =
                    worker_pool.enqueue_with_rejection(connection, reject_overloaded_connection);
                handled_requests += 1;
                if max_requests.is_some_and(|limit| handled_requests >= limit) {
                    return stop_runtime_workers_and_flush(worker_pool, job_worker);
                }
            }
            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
                thread::sleep(Duration::from_millis(5));
            }
            Err(_) => {
                let _ = stop_runtime_workers_and_flush(worker_pool, job_worker);
                return Err("listener accept failed");
            }
        }
    }
}

/// Performs serve app runtime with limit.
fn serve_app_runtime_with_limit(
    config_record: &ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
    max_requests: Option<usize>,
) -> Result<(), &'static str> {
    cache::install_runtime_cache(config_record);
    #[cfg(not(target_os = "wasi"))]
    social_connections::install_operator_config(config_record)?;
    install_runtime_shutdown_signal_handlers();
    let load_started = Instant::now();
    let app = load_app_runtime_for_single_app_direct(config_record, repo_root, binary_dir)?;
    verify_app_migration_state(&app)?;
    let stack = RuntimeStack {
        apps: vec![app.clone()],
        failed_apps: Vec::new(),
        host: config_record
            .host
            .clone()
            .or_else(|| Some("127.0.0.1".to_owned())),
        port: config_record
            .port
            .clone()
            .or_else(|| Some("7323".to_owned())),
        socket_path: config_record.socket_path.clone(),
    };
    let load_ms = load_started.elapsed().as_millis() as i64;
    let listener = open_runtime_listener(config_record, &stack)?;
    emit_runtime_log_banner(&stack, config_record, load_ms);
    let stack = Arc::new(RwLock::new(stack));
    let worker_count = crate::binaries::resolved_worker_count(config_record);
    let queue_capacity = crate::binaries::resolved_work_queue_capacity(config_record);
    let worker_stack = Arc::clone(&stack);
    let worker_pool = pharos_runtime_core::worker_pool::WorkerPool::new(
        worker_count,
        queue_capacity,
        Arc::new(move |connection: AcceptedConnection| {
            if let Ok(stack) = worker_stack.read() {
                handle_runtime_connection(connection, &stack, true);
            }
        }),
    )
    .map_err(|_| "failed to start request workers")?;
    let job_worker = [
        start_runtime_job_worker(Arc::clone(&stack)),
        event_discovery::start_worker(Arc::clone(&stack)),
    ]
    .into_iter()
    .flatten()
    .collect();
    println!(
        "pharos native app runtime worker_pool=true workers={worker_count} queue_capacity={queue_capacity} listener={}",
        listener.local_endpoint()
    );

    let mut handled_requests = 0usize;
    loop {
        if runtime_shutdown_requested() {
            return stop_runtime_workers_and_flush(worker_pool, job_worker);
        }
        match listener.accept() {
            Ok(connection) => {
                let _ =
                    worker_pool.enqueue_with_rejection(connection, reject_overloaded_connection);
                handled_requests += 1;
                if max_requests.is_some_and(|limit| handled_requests >= limit) {
                    return stop_runtime_workers_and_flush(worker_pool, job_worker);
                }
            }
            Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
                thread::sleep(Duration::from_millis(5));
            }
            Err(_) => {
                let _ = stop_runtime_workers_and_flush(worker_pool, job_worker);
                return Err("listener accept failed");
            }
        }
    }
}

/// Starts the shared multi-app runtime server.
///
/// # Parameters
///
/// - `config_record`: Input consumed by [`crate::runtime::serve_runtime_stack`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::serve_runtime_stack`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::serve_runtime_stack`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::serve_runtime_stack(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn serve_runtime_stack(config_record: &ServeConfig) -> Result<(), &'static str> {
    if config_record.kind.as_deref() != Some("runtime") {
        return Err("serve runtime requires runtime target kind");
    }
    if config_record.target_id.as_deref() != Some("shared") {
        return Err("serve runtime currently supports only shared target");
    }
    serve_runtime_stack_with_limit(config_record, None)
}

/// Starts the shared runtime in a direct test-oriented path.
///
/// # Parameters
///
/// - `config_record`: Shared-runtime serve configuration under test.
/// - `max_requests`: Maximum number of requests to serve before exiting.
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::serve_runtime_stack_direct_for_test`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::serve_runtime_stack_direct_for_test`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::serve_runtime_stack_direct_for_test(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn serve_runtime_stack_direct_for_test(
    config_record: &ServeConfig,
    max_requests: usize,
) -> Result<(), &'static str> {
    serve_runtime_stack_with_limit(config_record, Some(max_requests))
}

/// Starts the single-app runtime server.
///
/// # Parameters
///
/// - `config_record`: App-mode serve configuration to execute.
/// - `repo_root`: Optional repository root used to resolve app-owned sources.
/// - `binary_dir`: Optional directory used to resolve helper binaries.
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::serve_single_app`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::serve_single_app`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::serve_single_app(todo!(), std::path::Path::new("."), std::path::Path::new("bin"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn serve_single_app(
    config_record: &ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<(), &'static str> {
    if config_record.kind.as_deref() != Some("app") {
        return Err("serve app requires app target kind");
    }
    serve_app_runtime_with_limit(config_record, repo_root, binary_dir, None)
}

/// Starts a direct single-app runtime path for tests.
///
/// # Parameters
///
/// - `config_record`: App-mode serve configuration under test.
/// - `repo_root`: Optional repository root used to resolve app-owned sources.
/// - `binary_dir`: Optional directory used to resolve helper binaries.
/// - `max_requests`: Maximum number of requests to serve before exiting.
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::serve_app_runtime_direct_for_test`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::serve_app_runtime_direct_for_test`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::serve_app_runtime_direct_for_test(todo!(), std::path::Path::new("."), std::path::Path::new("bin"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn serve_app_runtime_direct_for_test(
    config_record: &ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
    max_requests: usize,
) -> Result<(), &'static str> {
    serve_app_runtime_with_limit(config_record, repo_root, binary_dir, Some(max_requests))
}

/// Builds the JSON status report for the loaded runtime stack.
///
/// # Parameters
///
/// - `stack`: Input consumed by [`crate::runtime::build_runtime_status_report_json`].
/// - `apps_dir`: Input consumed by [`crate::runtime::build_runtime_status_report_json`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::build_runtime_status_report_json`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::build_runtime_status_report_json`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::build_runtime_status_report_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::build_runtime_status_report_json(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn build_runtime_status_report_json(
    stack: &RuntimeStack,
    apps_dir: &str,
) -> Result<String, &'static str> {
    let apps: Vec<Value> = stack.apps.iter().map(runtime_app_summary_value).collect();
    let failed_apps: Vec<Value> = stack
        .failed_apps
        .iter()
        .map(runtime_failed_app_summary_value)
        .collect();

    serde_json::to_string(&serde_json::json!({
        "report_id": "pharos-runtime-status-v1",
        "status": if stack.failed_apps.is_empty() { "ok" } else { "degraded" },
        "host": stack.host.clone().unwrap_or_else(|| "127.0.0.1".to_owned()),
        "port": stack.port.clone().unwrap_or_else(|| "7323".to_owned()),
        "socket_path": stack.socket_path.clone().unwrap_or_default(),
        "redis_status": cache::redis_status(),
        "apps_dir": apps_dir,
        "app_count": stack.apps.len(),
        "failed_app_count": stack.failed_apps.len(),
        "apps": apps,
        "failed_apps": failed_apps,
    }))
    .map_err(|_| "report encode failed")
}

/// Handles one app-targeted runtime command directly.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::runtime::handle_runtime_app_command_direct`].
/// - `config_record`: Input consumed by [`crate::runtime::handle_runtime_app_command_direct`].
/// - `repo_root`: Input consumed by [`crate::runtime::handle_runtime_app_command_direct`].
/// - `binary_dir`: Input consumed by [`crate::runtime::handle_runtime_app_command_direct`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::handle_runtime_app_command_direct`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::handle_runtime_app_command_direct`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::handle_runtime_app_command_direct`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::handle_runtime_app_command_direct(todo!(), todo!(), std::path::Path::new("."), std::path::Path::new("bin"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn handle_runtime_app_command_direct(
    verb: &str,
    config_record: &mut ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<String, &'static str> {
    if !runtime_verb_supported(verb) {
        return Err("unsupported verb");
    }
    if config_record.target_id.as_deref().is_none_or(str::is_empty) {
        return Err("missing target_id");
    }
    if verb == "build" && config_record.build_dir.as_deref().is_none_or(str::is_empty) {
        config_record.build_dir = Some("dist".to_owned());
    }

    if verb == "build" {
        let source_root = config_record
            .app_dir
            .as_deref()
            .map(PathBuf::from)
            .or_else(|| {
                config::find_app_root_for_target(
                    config_record.target_id.as_deref().unwrap_or_default(),
                    None,
                    repo_root,
                    binary_dir,
                )
                .map(PathBuf::from)
            });
        let Some(app_root) = source_root else {
            return Err("app source root could not be resolved");
        };
        if packaged_artifact_root_matches(
            &app_root,
            config_record.target_id.as_deref().unwrap_or_default(),
        ) {
            // Already-built app directories are valid build inputs for the
            // report-only path and must not be copied over themselves.
        } else {
            let build_dir = config_record
                .build_dir
                .as_deref()
                .filter(|value| !value.is_empty())
                .ok_or("missing build_dir")?;
            if let Err(status) = build_app_from_root(&app_root, Path::new(build_dir)) {
                eprintln!(
                    "app build failed: app_id={} source_root={} build_dir={} status_code={status}",
                    config_record.target_id.as_deref().unwrap_or_default(),
                    app_root.display(),
                    build_dir
                );
                return Err(
                    "app build failed; see stderr for app_id, source_root, build_dir, and failing build step",
                );
            }
        }
    }

    let artifact_root = config_record
        .app_dir
        .as_deref()
        .map(Path::new)
        .filter(|path| {
            packaged_artifact_root_matches(
                path,
                config_record.target_id.as_deref().unwrap_or_default(),
            )
        });

    let app = load_app_runtime_for_single_app_direct(config_record, repo_root, binary_dir)?;
    let artifact_dir = artifact_root
        .map(|path| path.to_string_lossy().into_owned())
        .or_else(|| app.artifact_dir.clone())
        .unwrap_or_default();
    let build_report_path = if verb == "build" {
        app.build_dir
            .as_deref()
            .filter(|value| !value.is_empty())
            .map(Path::new)
            .map(|build_dir| {
                website_report_path(
                    build_dir,
                    "build-app",
                    app.app_id.as_deref().unwrap_or("app"),
                )
            })
    } else {
        None
    };
    let report_json = if verb == "doctor" {
        build_app_doctor_report_json(&artifact_dir, &app)?
    } else {
        app_runtime_report_json(runtime_report_id_for_verb(verb), verb, &artifact_dir, &app)?
    };
    if let Some(path) = build_report_path.as_deref() {
        write_report_file(path, &report_json)?;
    }
    Ok(report_json)
}

/// Clears a cloned app runtime in place.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::clear_cloned_app`].
///
/// # Returns
///
/// Returns after [`crate::runtime::clear_cloned_app`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::clear_cloned_app(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn clear_cloned_app(app: &mut AppRuntime) {
    *app = AppRuntime::default();
}

/// Handles one dynamic runtime request end to end.
///
/// # Parameters
///
/// - `method`: Input consumed by [`crate::runtime::dynamic_runtime_handle_request`].
/// - `target`: Input consumed by [`crate::runtime::dynamic_runtime_handle_request`].
/// - `stack`: Input consumed by [`crate::runtime::dynamic_runtime_handle_request`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::dynamic_runtime_handle_request`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::dynamic_runtime_handle_request(todo!(), "/", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_runtime_handle_request(
    method: &str,
    target: &str,
    stack: &RuntimeStack,
) -> Option<FrameworkBuiltinResponse> {
    pharos_runtime_core::request::dynamic_runtime_handle_request(
        method,
        target,
        stack,
        PHAROS_VERSION,
        PHAROS_TARGET_ID,
        app_runtime_probe_ready,
        runtime_stack_probe_ready,
        &RootRuntimeRequestService,
    )
}

/// Clones an optional string value into owned storage.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::runtime::clone_optional_string`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::clone_optional_string`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::clone_optional_string("value");
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn clone_optional_string(value: Option<&str>) -> Option<String> {
    value.map(ToOwned::to_owned)
}

/// Decodes a QR image into its textual payload.
///
/// # Parameters
///
/// - `image_path`: Input consumed by [`crate::runtime::decode_qr_image`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::decode_qr_image`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::decode_qr_image`] cannot complete successfully.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::decode_qr_image(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
#[cfg(not(target_os = "wasi"))]
pub fn decode_qr_image(
    image_path: &Path,
) -> Result<String, crate::runtime::agent_bridge::AgentErrorKind> {
    let image_path = image_path
        .canonicalize()
        .map_err(|_| crate::runtime::agent_bridge::AgentErrorKind::InvalidPath)?;
    let allowed_root = image_path
        .parent()
        .ok_or(crate::runtime::agent_bridge::AgentErrorKind::InvalidPath)?;
    let response =
        agent_media::decode_barcode_image_with_platform_helper(&image_path, allowed_root)?;
    let result = response
        .get("results")
        .and_then(Value::as_array)
        .and_then(|results| results.first())
        .ok_or(crate::runtime::agent_bridge::AgentErrorKind::InvalidEnvelope)?;
    serde_json::to_string(&serde_json::json!({
        "text": result.get("text").and_then(Value::as_str).unwrap_or_default(),
        "format": result.get("format").and_then(Value::as_str).unwrap_or_default(),
        "direct_link": result.get("direct_link").and_then(Value::as_bool).unwrap_or(false),
    }))
    .map_err(|_| crate::runtime::agent_bridge::AgentErrorKind::InvalidEnvelope)
}

/// Runs the native barcode-reader entrypoint.
///
/// # Parameters
///
/// - `image_path`: Input consumed by [`crate::runtime::barcode_reader_main`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::barcode_reader_main`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::barcode_reader_main`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::barcode_reader_main`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::barcode_reader_main(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
#[cfg(not(target_os = "wasi"))]
pub fn barcode_reader_main(image_path: &Path) -> Result<String, i32> {
    let image_path = image_path.canonicalize().map_err(|_| 64)?;
    let allowed_root = image_path.parent().ok_or(64)?;
    let response =
        agent_media::decode_barcode_image_with_platform_helper(&image_path, allowed_root).map_err(
            |error| match error {
                crate::runtime::agent_bridge::AgentErrorKind::InvalidPath
                | crate::runtime::agent_bridge::AgentErrorKind::PolicyViolation => 64,
                crate::runtime::agent_bridge::AgentErrorKind::CredentialUnavailable => 69,
                crate::runtime::agent_bridge::AgentErrorKind::CapacityExceeded => 74,
                _ => 1,
            },
        )?;
    serde_json::to_string(&response).map_err(|_| 74)
}

/// Handles one top-level runtime command directly.
///
/// # Parameters
///
/// - `verb`: Input consumed by [`crate::runtime::handle_runtime_command_direct`].
/// - `config_record`: Input consumed by [`crate::runtime::handle_runtime_command_direct`].
/// - `repo_root`: Input consumed by [`crate::runtime::handle_runtime_command_direct`].
/// - `binary_dir`: Input consumed by [`crate::runtime::handle_runtime_command_direct`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::handle_runtime_command_direct`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::handle_runtime_command_direct`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::handle_runtime_command_direct`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::handle_runtime_command_direct(todo!(), todo!(), std::path::Path::new("."), std::path::Path::new("bin"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn handle_runtime_command_direct(
    verb: &str,
    config_record: &mut ServeConfig,
    repo_root: Option<&Path>,
    binary_dir: Option<&Path>,
) -> Result<String, &'static str> {
    match config_record.kind.as_deref() {
        Some("app") => {
            return handle_runtime_app_command_direct(verb, config_record, repo_root, binary_dir);
        }
        Some("runtime") => {}
        Some("website") => {
            return Err("website target kind is not supported by the native runtime");
        }
        _ => return Err("unsupported runtime kind"),
    }
    if !matches!(verb, "status" | "build") {
        return Err("runtime verb is not supported for the shared target");
    }

    cache::install_runtime_cache(config_record);
    let apps_dir = runtime_apps_dir(config_record.conf_path.as_deref().map(Path::new))
        .ok_or("missing apps_dir")?;
    let stack = load_runtime_stack_direct(config_record)?;
    let report_json = if verb == "build" {
        build_runtime_build_report_json(
            config_record.target_id.as_deref().unwrap_or_default(),
            config_record.conf_path.as_deref(),
            &apps_dir,
            stack.apps.len(),
        )?
    } else {
        cache::probe_runtime_cache();
        build_runtime_status_report_json(&stack, &apps_dir)?
    };
    let report_build_dir = config_record
        .build_dir
        .as_deref()
        .filter(|value| !value.is_empty())
        .unwrap_or("dist");
    let report_path = website_report_path(
        Path::new(report_build_dir),
        verb,
        config_record.target_id.as_deref().unwrap_or_default(),
    );
    write_report_file(&report_path, &report_json)?;
    Ok(report_json)
}

/// Returns the effective host profile for an app runtime.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::app_runtime_host_profile`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::app_runtime_host_profile`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::app_runtime_host_profile(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn app_runtime_host_profile(app_root: &Path) -> Option<String> {
    read_source_manifest_value(app_root)
        .ok()?
        .get("runtime")
        .and_then(Value::as_object)?
        .get("host_profile")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .map(ToOwned::to_owned)
}

/// Builds an app from its source root into a runtime artifact.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::build_app_from_root`].
/// - `build_dir`: Input consumed by [`crate::runtime::build_app_from_root`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::runtime::build_app_from_root`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::runtime::build_app_from_root`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::build_app_from_root`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::build_app_from_root(std::path::Path::new("apps/dev_docs"), std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
fn generated_ownership_manifest_matches_source_digest(
    artifact_root: &Path,
    source_digest: &str,
) -> bool {
    let Some(document) = stdfs::read_to_string(artifact_root.join("GENERATED-OWNERSHIP.json"))
        .ok()
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
    else {
        return false;
    };
    document.get("schema").and_then(Value::as_str) == Some("pharos.generated-ownership.v1")
        && document.get("generator").and_then(Value::as_str) == Some("pharos-native-runtime")
        && document.get("generator_version").and_then(Value::as_str)
            == Some(env!("CARGO_PKG_VERSION"))
        && document.get("input_sha256").and_then(Value::as_str) == Some(source_digest)
}

fn app_artifact_build_is_current(
    app_root: &Path,
    artifact_root: &Path,
    manifest: &Value,
    source_digest: &str,
    preserved_rustdoc_dir: Option<&Path>,
) -> bool {
    if !artifact_root.join("pharos.app.json").is_file() {
        return false;
    }
    if !generated_ownership_manifest_matches_source_digest(artifact_root, source_digest) {
        return false;
    }
    if docs_manifest_bool_path(manifest, &["rustdoc", "enabled"]).unwrap_or(false)
        && preserved_rustdoc_dir.is_none()
    {
        return false;
    }
    let _ = app_root;
    verify_generated_ownership_manifest(artifact_root)
}

pub fn build_app_from_root(app_root: &Path, build_dir: &Path) -> Result<String, i32> {
    if app_root.as_os_str().is_empty() || build_dir.as_os_str().is_empty() || !app_root.is_dir() {
        return Err(64);
    }
    let manifest = read_source_manifest_value(app_root).map_err(|_| 66)?;
    let app_id = json_string(&manifest, "app_id").ok_or(66)?;
    let artifact_dir =
        config::effective_app_artifact_dir(app_root, build_dir, &app_id).ok_or(69)?;
    let artifact_path = Path::new(&artifact_dir);
    stdfs::create_dir_all(artifact_path).map_err(|_| 69)?;
    let canonical_source = app_root.canonicalize().map_err(|_| 69)?;
    let canonical_artifact = artifact_path.canonicalize().map_err(|_| 69)?;
    if canonical_source.starts_with(&canonical_artifact)
        || canonical_artifact.starts_with(&canonical_source)
    {
        return Err(78);
    }
    let previous_outputs = read_generated_ownership_outputs(artifact_path);
    let source_digest =
        tree_content_digest_with_cached_outputs(app_root, None, &previous_outputs).ok_or(74)?;
    let preserved_rustdoc_dir =
        if docs_manifest_bool_path(&manifest, &["rustdoc", "enabled"]).unwrap_or(false) {
            docs_valid_existing_rustdoc_output_dir(app_root, artifact_path, &manifest)
                .ok()
                .flatten()
        } else {
            None
        };
    if app_artifact_build_is_current(
        app_root,
        artifact_path,
        &manifest,
        &source_digest,
        preserved_rustdoc_dir.as_deref(),
    ) {
        return Ok(artifact_dir);
    }
    stdfs::create_dir_all(artifact_path).map_err(|_| 69)?;
    cleanup_incremental_artifact_outputs(
        artifact_path,
        app_root,
        preserved_rustdoc_dir.as_deref(),
        &previous_outputs,
    )?;
    let mut copied_files = 0;
    let mut copied_bytes = 0;
    copy_source_tree_to_artifact(
        app_root,
        Path::new(&artifact_dir),
        app_root,
        0,
        &previous_outputs,
        &mut copied_files,
        &mut copied_bytes,
    )?;
    copy_selected_bootstrap_icons(
        app_root,
        artifact_path,
        &mut copied_files,
        &mut copied_bytes,
    )?;
    let stale_path = Path::new(&artifact_dir).join("start.sh");
    if stale_path.is_file() {
        stdfs::remove_file(stale_path).map_err(|_| 69)?;
    }
    let compile_status =
        declarative::compile_yaml_matches_in_directory(Path::new(&artifact_dir), ".yml");
    if compile_status != 0 {
        return Err(69);
    }
    if declarative::normalize_compiled_json_references(artifact_path) != 0 {
        return Err(69);
    }
    if let Err(error) = features::compile_feature_sources(artifact_path) {
        eprintln!("feature compilation failed: {error:?}");
        return Err(69);
    }
    pharos_runtime_compiler::component_properties::compile(artifact_path).map_err(|_| 69)?;
    build_docs_pages(app_root, artifact_path, &manifest)?;
    if docs_manifest_bool_path(&manifest, &["rustdoc", "enabled"]).unwrap_or(false) {
        build_docs_rustdoc_reference(app_root, artifact_path, &manifest)?;
    }
    // Generated surfaces and their derived routes are build artifacts, not
    // source files. Generate them only after YAML contracts have been
    // materialized so stale JSON cannot win precedence.
    if declarative::declarative_source_derive_generated_surface_fixture(artifact_path).is_some() {
        let _ = declarative::declarative_source_derive_generated_admin_routes(artifact_path);
        let _ = declarative::declarative_source_derive_generated_api_routes(artifact_path);
        if let Some(Value::Array(surfaces)) = json_commands::json_doc_load_file(
            &artifact_path.join("data/contracts/generated-surfaces.json"),
        )
        .and_then(|root| root.get("surfaces").cloned())
        {
            let generated_dir = artifact_path.join("generated_admin");
            stdfs::create_dir_all(&generated_dir).map_err(|_| 69)?;
            for surface in surfaces {
                if surface.get("surface_kind").and_then(Value::as_str) != Some("generated_admin") {
                    continue;
                }
                let Some(entity_id) = surface.get("entity_id").and_then(Value::as_str) else {
                    continue;
                };
                let output = generated_dir.join(format!("{entity_id}.json"));
                fs::write_file_within(
                    artifact_path,
                    &output,
                    serde_json::to_string_pretty(&surface)
                        .map_err(|_| 75)?
                        .as_bytes(),
                    0o644,
                )
                .map_err(|_| 69)?;
            }
        }
    }
    let manifest_path = Path::new(&artifact_dir).join("pharos.app.json");
    finalize_artifact_manifest(&manifest_path, &manifest, &app_id, &source_digest)?;
    pharos_runtime_static::write_route_map(artifact_path).map_err(|_| 69)?;
    remove_non_manifest_yaml_from_artifact(artifact_path, 0)?;
    write_generated_ownership_manifest(artifact_path, app_root, &source_digest)?;
    Ok(artifact_dir)
}

/// Performs finalize artifact manifest.
fn finalize_artifact_manifest(
    manifest_path: &Path,
    source_manifest: &Value,
    app_id: &str,
    source_digest: &str,
) -> Result<(), i32> {
    let mut artifact_manifest = if manifest_path.is_file() {
        let text = stdfs::read_to_string(manifest_path).map_err(|_| 69)?;
        serde_json::from_str::<Value>(&text).map_err(|_| 69)?
    } else {
        source_manifest.clone()
    };
    let object = artifact_manifest.as_object_mut().ok_or(69)?;
    let runtime = object
        .entry("runtime".to_owned())
        .or_insert_with(|| Value::Object(serde_json::Map::new()))
        .as_object_mut()
        .ok_or(69)?;
    runtime.insert(
        "build_artifact_dir".to_owned(),
        Value::String(".".to_owned()),
    );
    let artifact = object
        .entry("artifact".to_owned())
        .or_insert_with(|| Value::Object(serde_json::Map::new()))
        .as_object_mut()
        .ok_or(69)?;
    artifact.insert(
        "schema".to_owned(),
        Value::String("pharos.app.artifact.v1".to_owned()),
    );
    artifact.insert("app_root".to_owned(), Value::String(".".to_owned()));
    artifact.insert("artifact_dir".to_owned(), Value::String(".".to_owned()));
    artifact
        .entry("index".to_owned())
        .or_insert_with(|| Value::String("index.html".to_owned()));
    artifact
        .entry("static_dir".to_owned())
        .or_insert_with(|| Value::String("static".to_owned()));
    artifact
        .entry("media_dir".to_owned())
        .or_insert_with(|| Value::String("media".to_owned()));
    if let Some(runtime_media_dir) = source_manifest
        .get("assets")
        .and_then(Value::as_object)
        .and_then(|assets| assets.get("runtime_media_dir"))
        .and_then(Value::as_str)
        .filter(|value| !value.trim().is_empty())
    {
        artifact.insert(
            "runtime_media_dir".to_owned(),
            Value::String(runtime_media_dir.to_owned()),
        );
    }
    artifact.insert(
        "generated_by".to_owned(),
        Value::String("pharos-native-runtime".to_owned()),
    );
    artifact.insert(
        "generator_schema".to_owned(),
        Value::String("pharos.generated-ownership.v1".to_owned()),
    );
    artifact.insert(
        "input_sha256".to_owned(),
        Value::String(source_digest.to_owned()),
    );
    artifact.insert(
        "ownership_manifest".to_owned(),
        Value::String("GENERATED-OWNERSHIP.json".to_owned()),
    );
    if object
        .get("app_id")
        .and_then(Value::as_str)
        .is_none_or(|value| value.is_empty())
    {
        object.insert("app_id".to_owned(), Value::String(app_id.to_owned()));
    }
    let encoded = serde_json::to_string_pretty(&artifact_manifest).map_err(|_| 75)?;
    let root = manifest_path.parent().ok_or(69)?;
    pharos_runtime_core::fs::write_file_within(root, manifest_path, encoded.as_bytes(), 0o644)
        .map_err(|_| 69)
}

/// Performs ignore non contract artifact entry.
fn ignore_non_contract_artifact_entry(name: &str) -> bool {
    name == ".DS_Store"
}

/// Finds the repository-level Bootstrap Icons source shared by app builds.
fn shared_bootstrap_icons_root(app_root: &Path) -> Option<PathBuf> {
    app_root
        .ancestors()
        .map(|ancestor| ancestor.join("assets/static/bootstrap-icons"))
        .find(|candidate| candidate.is_dir())
}

/// Collects text files below an app source tree for icon reference discovery.
fn collect_text_files(root: &Path, current: &Path, files: &mut Vec<PathBuf>) -> Result<(), i32> {
    for entry in stdfs::read_dir(current).map_err(|_| 69)? {
        let entry = entry.map_err(|_| 69)?;
        if ignore_non_contract_artifact_entry(&entry.file_name().to_string_lossy()) {
            continue;
        }
        let path = entry.path();
        let metadata = stdfs::symlink_metadata(&path).map_err(|_| 69)?;
        if metadata.file_type().is_symlink() {
            return Err(78);
        }
        if metadata.is_dir() {
            collect_text_files(root, &path, files)?;
            continue;
        }
        if metadata.is_file()
            && stdfs::read(&path).is_ok_and(|bytes| std::str::from_utf8(&bytes).is_ok())
        {
            files.push(path.strip_prefix(root).map_err(|_| 69)?.to_path_buf());
        }
    }
    Ok(())
}

/// Extracts icon names from Bootstrap class names and static SVG references.
fn bootstrap_icon_references(app_root: &Path, icon_root: &Path) -> Result<BTreeSet<String>, i32> {
    let mut text_files = Vec::new();
    collect_text_files(app_root, app_root, &mut text_files)?;
    let mut references = BTreeSet::new();
    let mut available = BTreeSet::new();
    for entry in stdfs::read_dir(icon_root).map_err(|_| 69)? {
        let entry = entry.map_err(|_| 69)?;
        let path = entry.path();
        if path.extension().and_then(|value| value.to_str()) == Some("svg")
            && path.is_file()
            && let Some(stem) = path.file_stem().and_then(|value| value.to_str())
        {
            available.insert(stem.to_owned());
        }
    }
    for relative in text_files {
        let text = stdfs::read_to_string(app_root.join(relative)).map_err(|_| 69)?;
        references.extend(bootstrap_icon_names_in_text(&text, &available));
    }
    Ok(references)
}

/// Scans reference markers once, preserving class-prefix and SVG-suffix matching.
fn bootstrap_icon_names_in_text(text: &str, available: &BTreeSet<String>) -> BTreeSet<String> {
    let mut references = BTreeSet::new();
    let maximum = available.iter().map(String::len).max().unwrap_or(0);
    for (marker, _) in text.match_indices("bi-") {
        let start = marker + 3;
        for length in 1..=maximum.min(text.len() - start) {
            if let Some(name) = text.get(start..start + length)
                && available.contains(name)
            {
                references.insert(name.to_owned());
            }
        }
    }
    for (end, _) in text.match_indices(".svg") {
        for length in 1..=maximum.min(end) {
            if let Some(name) = text.get(end - length..end)
                && available.contains(name)
            {
                references.insert(name.to_owned());
            }
        }
    }
    references
}

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

    /// Preserves the former substring semantics without scanning source once per icon.
    #[test]
    fn bootstrap_icon_references_preserve_prefix_suffix_and_unicode_matches() {
        let available = ["arrow", "arrow-left", "left", "gear-fill", "unused"]
            .into_iter()
            .map(str::to_owned)
            .collect::<BTreeSet<_>>();
        for text in [
            "bi-arrow-left-extra bi-gear-fill",
            "λ/icons/arrow-left.svg",
            "nothing matches",
            "bi-λarrow.svg bi-arrow",
        ] {
            let expected = available
                .iter()
                .filter(|name| {
                    text.contains(&format!("{name}.svg")) || text.contains(&format!("bi-{name}"))
                })
                .cloned()
                .collect::<BTreeSet<_>>();
            assert_eq!(bootstrap_icon_names_in_text(text, &available), expected);
        }
    }
}

/// Copies one central Bootstrap Icons helper file into the app artifact.
fn copy_bootstrap_icon_helper(
    source: &Path,
    destination: &Path,
    copied_files: &mut u64,
    copied_bytes: &mut u64,
) -> Result<(), i32> {
    let metadata = stdfs::metadata(source).map_err(|_| 69)?;
    if !metadata.is_file() {
        return Err(69);
    }
    let parent = destination.parent().ok_or(69)?;
    stdfs::create_dir_all(parent).map_err(|_| 69)?;
    stdfs::copy(source, destination).map_err(|_| 69)?;
    *copied_files = copied_files.saturating_add(1);
    *copied_bytes = copied_bytes.saturating_add(metadata.len());
    Ok(())
}

/// Copies only the Bootstrap Icons used by an app into its built artifact.
fn copy_selected_bootstrap_icons(
    app_root: &Path,
    artifact_root: &Path,
    copied_files: &mut u64,
    copied_bytes: &mut u64,
) -> Result<(), i32> {
    let Some(source_root) = shared_bootstrap_icons_root(app_root) else {
        return Ok(());
    };
    let references = bootstrap_icon_references(app_root, &source_root)?;
    let font_helpers = bootstrap_font_helper_references(app_root)?;
    if references.is_empty() && font_helpers.is_empty() {
        return Ok(());
    }
    let destination_root = artifact_root.join("static/bootstrap-icons");
    for name in references {
        let source = source_root.join(format!("{name}.svg"));
        if source.is_file() {
            copy_bootstrap_icon_helper(
                &source,
                &destination_root.join(format!("{name}.svg")),
                copied_files,
                copied_bytes,
            )?;
        }
    }
    if !font_helpers.is_empty() {
        for name in font_helpers {
            let source = source_root.join(&name);
            if source.is_file() {
                copy_bootstrap_icon_helper(
                    &source,
                    &destination_root.join(name),
                    copied_files,
                    copied_bytes,
                )?;
            }
        }
        for name in ["bootstrap-icons.woff", "bootstrap-icons.woff2"] {
            let source = source_root.join("fonts").join(name);
            if source.is_file() {
                copy_bootstrap_icon_helper(
                    &source,
                    &destination_root.join("fonts").join(name),
                    copied_files,
                    copied_bytes,
                )?;
            }
        }
    }
    Ok(())
}

/// Detects the Bootstrap Icons font helper files referenced by an app.
fn bootstrap_font_helper_references(app_root: &Path) -> Result<BTreeSet<String>, i32> {
    let mut text_files = Vec::new();
    collect_text_files(app_root, app_root, &mut text_files)?;
    let mut references = BTreeSet::new();
    for relative in text_files {
        let text = stdfs::read_to_string(app_root.join(relative)).map_err(|_| 69)?;
        if text.contains("bootstrap-icons.css") {
            references.insert("bootstrap-icons.css".to_owned());
        }
        if text.contains("bootstrap-icons.min.css") {
            references.insert("bootstrap-icons.min.css".to_owned());
        }
        if text.contains("bootstrap-icons.scss") {
            references.insert("bootstrap-icons.scss".to_owned());
        }
        if text.contains("font-family: bootstrap-icons")
            || text.contains("font-family: \"bootstrap-icons\"")
        {
            references.insert("bootstrap-icons.css".to_owned());
        }
    }
    Ok(references)
}

/// Collects all regular files below a root in deterministic relative-path order.
fn collect_tree_files(root: &Path, current: &Path, files: &mut Vec<PathBuf>) -> Option<()> {
    for entry in stdfs::read_dir(current).ok()?.flatten() {
        if entry
            .file_name()
            .to_str()
            .is_some_and(ignore_non_contract_artifact_entry)
        {
            continue;
        }
        let path = entry.path();
        let metadata = entry.metadata().ok()?;
        if metadata.file_type().is_symlink() {
            return None;
        }
        if metadata.is_dir() {
            collect_tree_files(root, &path, files)?;
        } else if metadata.is_file() {
            files.push(path.strip_prefix(root).ok()?.to_path_buf());
        }
    }
    Some(())
}

/// Hashes a deterministic file tree while optionally excluding one relative file.
fn tree_content_digest(root: &Path, excluded: Option<&str>) -> Option<String> {
    let mut files = Vec::new();
    collect_tree_files(root, root, &mut files)?;
    files.sort();
    let mut digest = Sha256::new();
    for relative in files {
        if excluded.is_some_and(|value| relative == Path::new(value)) {
            continue;
        }
        digest.update(relative.to_string_lossy().as_bytes());
        digest.update([0]);
        digest.update(stdfs::read(root.join(&relative)).ok()?);
        digest.update([0]);
    }
    Some(
        digest
            .finalize()
            .iter()
            .map(|byte| format!("{byte:02x}"))
            .collect(),
    )
}

fn cached_source_output_sha256(path: &Path, previous: Option<&Value>) -> Option<String> {
    let output = previous?;
    if output.get("ownership").and_then(Value::as_str) != Some("app_source_copy") {
        return None;
    }
    if metadata_matches_output(path, output, "source") {
        output
            .get("sha256")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned)
    } else {
        None
    }
}

fn is_lazy_model_payload_path(path: &Path) -> bool {
    // Small model manifests must survive archive reuse with a different mtime.
    if path.extension() == Some(std::ffi::OsStr::new("json")) {
        return false;
    }
    let mut components = path.components();
    matches!(
        (components.next(), components.next()),
        (
            Some(std::path::Component::Normal(first)),
            Some(std::path::Component::Normal(second))
        ) if first == "data" && second == "models"
    )
}

fn is_opaque_static_docs_path(path: &Path) -> bool {
    let mut components = path.components();
    matches!(
        (components.next(), components.next()),
        (
            Some(std::path::Component::Normal(first)),
            Some(std::path::Component::Normal(_))
        ) if first == "html"
    )
}

fn should_use_metadata_integrity(path: &Path) -> bool {
    is_lazy_model_payload_path(path)
}

fn push_opaque_static_docs_ownership_output(
    outputs: &mut Vec<Value>,
    artifact_root: &Path,
) -> Result<(), i32> {
    let html_root = artifact_root.join("html");
    if !html_root.is_dir() {
        return Ok(());
    }
    let digest = tree_content_digest(&html_root, None).ok_or(74)?;
    let mut output = serde_json::Map::new();
    output.insert("path".to_owned(), Value::String("html".to_owned()));
    output.insert(
        "integrity".to_owned(),
        Value::String("opaque_static_digest".to_owned()),
    );
    output.insert("sha256".to_owned(), Value::String(digest));
    output.insert(
        "ownership".to_owned(),
        Value::String("pharos_generated_static_tree".to_owned()),
    );
    append_output_metadata(&mut output, "artifact", &html_root);
    outputs.push(Value::Object(output));
    Ok(())
}

fn metadata_fingerprint_for_path(path: &Path) -> Option<String> {
    let metadata = stdfs::metadata(path).ok()?;
    let modified = metadata
        .modified()
        .ok()?
        .duration_since(UNIX_EPOCH)
        .ok()?
        .as_secs();
    Some(format!("metadata:{}:{modified}", metadata.len()))
}

fn tree_content_digest_with_cached_outputs(
    root: &Path,
    excluded: Option<&str>,
    previous_outputs: &BTreeMap<PathBuf, Value>,
) -> Option<String> {
    let mut files = Vec::new();
    collect_tree_files(root, root, &mut files)?;
    files.sort();
    let mut digest = Sha256::new();
    for relative in files {
        if excluded.is_some_and(|value| relative == Path::new(value)) {
            continue;
        }
        digest.update(relative.to_string_lossy().as_bytes());
        digest.update([0]);
        if is_lazy_model_payload_path(&relative) {
            digest.update(metadata_fingerprint_for_path(&root.join(&relative))?.as_bytes());
        } else if let Some(cached_sha) =
            cached_source_output_sha256(&root.join(&relative), previous_outputs.get(&relative))
        {
            digest.update(cached_sha.as_bytes());
        } else {
            digest.update(sha256_hex(&stdfs::read(root.join(&relative)).ok()?).as_bytes());
        }
        digest.update([0]);
    }
    Some(
        digest
            .finalize()
            .iter()
            .map(|byte| format!("{byte:02x}"))
            .collect(),
    )
}

fn system_time_unix_nanos(value: SystemTime) -> Option<String> {
    let duration = value.duration_since(UNIX_EPOCH).ok()?;
    Some(
        duration
            .as_secs()
            .saturating_mul(1_000_000_000)
            .saturating_add(u64::from(duration.subsec_nanos()))
            .to_string(),
    )
}

#[cfg(unix)]
fn metadata_changed_unix_nanos(metadata: &stdfs::Metadata) -> Option<String> {
    use std::os::unix::fs::MetadataExt;
    let seconds = metadata.ctime();
    let nanos = metadata.ctime_nsec();
    if seconds < 0 || nanos < 0 {
        return None;
    }
    Some(
        (seconds as u64)
            .saturating_mul(1_000_000_000)
            .saturating_add(nanos as u64)
            .to_string(),
    )
}

#[cfg(not(unix))]
fn metadata_changed_unix_nanos(_metadata: &stdfs::Metadata) -> Option<String> {
    None
}

fn metadata_unix_nanos(metadata: &stdfs::Metadata) -> Option<String> {
    system_time_unix_nanos(metadata.modified().ok()?)
}

fn output_metadata_field(prefix: &str, name: &str) -> String {
    format!("{prefix}_{name}")
}

fn append_output_metadata(output: &mut serde_json::Map<String, Value>, prefix: &str, path: &Path) {
    let Ok(metadata) = stdfs::metadata(path) else {
        return;
    };
    output.insert(
        output_metadata_field(prefix, "size_bytes"),
        Value::Number(serde_json::Number::from(metadata.len())),
    );
    if let Some(modified) = metadata_unix_nanos(&metadata) {
        output.insert(
            output_metadata_field(prefix, "modified_unix_nanos"),
            Value::String(modified),
        );
    }
    if let Some(changed) = metadata_changed_unix_nanos(&metadata) {
        output.insert(
            output_metadata_field(prefix, "changed_unix_nanos"),
            Value::String(changed),
        );
    }
}

fn metadata_matches_output(path: &Path, output: &Value, prefix: &str) -> bool {
    let Ok(metadata) = stdfs::metadata(path) else {
        return false;
    };
    if output
        .get(output_metadata_field(prefix, "size_bytes"))
        .and_then(Value::as_u64)
        != Some(metadata.len())
    {
        return false;
    }
    if let Some(expected) = output
        .get(output_metadata_field(prefix, "modified_unix_nanos"))
        .and_then(Value::as_str)
    {
        if metadata_unix_nanos(&metadata).as_deref() != Some(expected) {
            return false;
        }
    } else {
        return false;
    }
    // Unix ctime is not transport-stable: copying an otherwise unchanged artifact
    // preserves size and mtime but necessarily gives the destination a new ctime.
    // Treat ctime as diagnostic ownership metadata only so copied deployment-shaped
    // app artifacts can still use the cached digest fast path.
    true
}

fn read_generated_ownership_outputs(artifact_root: &Path) -> BTreeMap<PathBuf, Value> {
    let Some(outputs) = stdfs::read_to_string(artifact_root.join("GENERATED-OWNERSHIP.json"))
        .ok()
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
        .and_then(|root| root.get("outputs").and_then(Value::as_array).cloned())
    else {
        return BTreeMap::new();
    };
    outputs
        .into_iter()
        .filter_map(|output| {
            let path = output.get("path")?.as_str()?;
            let relative = PathBuf::from(path);
            if relative.is_absolute()
                || relative
                    .components()
                    .any(|component| matches!(component, std::path::Component::ParentDir))
            {
                return None;
            }
            Some((relative, output))
        })
        .collect()
}

fn cached_output_sha256(path: &Path, previous: Option<&Value>) -> Option<String> {
    let output = previous?;
    if metadata_matches_output(path, output, "artifact") {
        output
            .get("sha256")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned)
    } else {
        None
    }
}

/// Writes generator ownership and output digests for every app artifact file.
fn write_generated_ownership_manifest(
    artifact_root: &Path,
    source_root: &Path,
    source_digest: &str,
) -> Result<(), i32> {
    let previous_outputs = read_generated_ownership_outputs(artifact_root);
    let mut files = Vec::new();
    collect_tree_files(artifact_root, artifact_root, &mut files).ok_or(74)?;
    files.sort();
    let mut outputs = Vec::new();
    push_opaque_static_docs_ownership_output(&mut outputs, artifact_root)?;
    for relative in files {
        if matches!(
            relative.to_str(),
            Some("GENERATED-OWNERSHIP.json" | "app.conf")
        ) || is_opaque_static_docs_path(&relative)
        {
            continue;
        }
        let artifact_path = artifact_root.join(&relative);
        let source_path = source_root.join(&relative);
        let ownership = if source_path.is_file() {
            "app_source_copy"
        } else {
            "pharos_generated"
        };
        let mut output = serde_json::Map::new();
        output.insert(
            "path".to_owned(),
            // Artifact paths use portable separators; the verifier deliberately
            // rejects backslashes rather than accepting platform-specific paths.
            Value::String(
                relative
                    .iter()
                    .map(|component| component.to_string_lossy())
                    .collect::<Vec<_>>()
                    .join("/"),
            ),
        );
        if should_use_metadata_integrity(&relative) {
            let fingerprint = metadata_fingerprint_for_path(&artifact_path).ok_or(74)?;
            output.insert("integrity".to_owned(), Value::String("metadata".to_owned()));
            output.insert("fingerprint".to_owned(), Value::String(fingerprint));
        } else {
            let sha256 = cached_output_sha256(&artifact_path, previous_outputs.get(&relative))
                .unwrap_or_else(|| {
                    stdfs::read(&artifact_path)
                        .map(|bytes| sha256_hex(&bytes))
                        .unwrap_or_default()
                });
            if sha256.is_empty() {
                return Err(74);
            }
            output.insert("integrity".to_owned(), Value::String("sha256".to_owned()));
            output.insert("sha256".to_owned(), Value::String(sha256));
        }
        output.insert("ownership".to_owned(), Value::String(ownership.to_owned()));
        append_output_metadata(&mut output, "artifact", &artifact_path);
        if source_path.is_file() {
            append_output_metadata(&mut output, "source", &source_path);
        }
        outputs.push(Value::Object(output));
    }
    let generated_at = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_err(|_| 70)?
        .as_secs();
    let document = serde_json::json!({
        "schema": "pharos.generated-ownership.v1",
        "generator": "pharos-native-runtime",
        "generator_version": env!("CARGO_PKG_VERSION"),
        "generated_at_unix": generated_at,
        "source_owner": source_root.to_string_lossy(),
        "input_sha256": source_digest,
        "outputs": outputs,
    });
    let encoded = serde_json::to_vec_pretty(&document).map_err(|_| 70)?;
    pharos_runtime_core::fs::write_file_within(
        artifact_root,
        &artifact_root.join("GENERATED-OWNERSHIP.json"),
        &encoded,
        0o644,
    )
    .map_err(|_| 69)
}

/// Verifies one generated ownership output entry against the artifact and optional source copy.
fn verify_generated_ownership_output(
    artifact_root: &Path,
    source_root: Option<&Path>,
    output: &Value,
) -> bool {
    let Some(relative) = output.get("path").and_then(Value::as_str) else {
        return false;
    };
    let Some(artifact_path) =
        pharos_runtime_core::safe_existing_artifact_path(artifact_root, relative)
    else {
        return false;
    };
    if output.get("integrity").and_then(Value::as_str) == Some("metadata") {
        return metadata_fingerprint_for_path(&artifact_path).as_deref()
            == output.get("fingerprint").and_then(Value::as_str);
    }
    if output.get("integrity").and_then(Value::as_str) == Some("opaque_static_digest") {
        return artifact_path.is_dir()
            && output
                .get("sha256")
                .and_then(Value::as_str)
                .is_some_and(|value| {
                    value.len() == 64 && value.chars().all(|ch| ch.is_ascii_hexdigit())
                });
    }
    let Some(expected) = output.get("sha256").and_then(Value::as_str) else {
        return false;
    };
    if metadata_matches_output(&artifact_path, output, "artifact") {
        return true;
    }
    let Ok(artifact_bytes) = stdfs::read(&artifact_path) else {
        return false;
    };
    if sha256_hex(&artifact_bytes) == expected {
        return true;
    }
    if output.get("ownership").and_then(Value::as_str) != Some("app_source_copy") {
        return false;
    }
    let Some(source_root) = source_root else {
        return false;
    };
    let relative_path = Path::new(relative);
    if relative_path.is_absolute()
        || relative_path
            .components()
            .any(|component| matches!(component, std::path::Component::ParentDir))
    {
        return false;
    }
    stdfs::read(source_root.join(relative_path))
        .is_ok_and(|source_bytes| source_bytes == artifact_bytes)
}

/// Verifies every output digest declared by the generated ownership manifest.
fn verify_generated_ownership_manifest(artifact_root: &Path) -> bool {
    let path = artifact_root.join("GENERATED-OWNERSHIP.json");
    let Some(document) = stdfs::read_to_string(path)
        .ok()
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
    else {
        return false;
    };
    if document.get("schema").and_then(Value::as_str) != Some("pharos.generated-ownership.v1") {
        return false;
    }
    let declared_input = stdfs::read_to_string(artifact_root.join("pharos.app.json"))
        .ok()
        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
        .and_then(|manifest| {
            manifest
                .get("artifact")
                .and_then(|artifact| artifact.get("input_sha256"))
                .and_then(Value::as_str)
                .map(ToOwned::to_owned)
        });
    if declared_input.as_deref() != document.get("input_sha256").and_then(Value::as_str) {
        return false;
    }
    let source_root = document
        .get("source_owner")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .map(Path::new);
    document
        .get("outputs")
        .and_then(Value::as_array)
        .is_some_and(|outputs| {
            outputs
                .iter()
                .all(|output| verify_generated_ownership_output(artifact_root, source_root, output))
        })
}

const MAX_BUILD_FILES: u64 = 100_000;
const MAX_BUILD_BYTES: u64 = 512 * 1024 * 1024;

/// Performs docs manifest string.
fn docs_manifest_string<'a>(manifest: &'a Value, key: &str) -> Option<&'a str> {
    manifest
        .get("docs")
        .and_then(Value::as_object)
        .and_then(|docs| docs.get(key))
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
}

/// Looks up a nested value under the docs manifest object.
fn docs_manifest_value_path<'a>(manifest: &'a Value, path: &[&str]) -> Option<&'a Value> {
    let mut current = manifest.get("docs")?;
    for segment in path {
        current = current.get(*segment)?;
    }
    Some(current)
}

/// Reads a nested string from the docs manifest object.
fn docs_manifest_string_path<'a>(manifest: &'a Value, path: &[&str]) -> Option<&'a str> {
    docs_manifest_value_path(manifest, path)
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
}

/// Reads a nested boolean from the docs manifest object.
fn docs_manifest_bool_path(manifest: &Value, path: &[&str]) -> Option<bool> {
    docs_manifest_value_path(manifest, path).and_then(Value::as_bool)
}

/// Validates one docs-owned relative artifact path.
fn docs_validate_relative_path(value: &str, label: &str) -> Result<String, i32> {
    if Path::new(value).is_absolute() || value.split('/').any(|segment| segment == "..") {
        eprintln!("docs {label} must be a relative artifact path: {value}");
        return Err(66);
    }
    Ok(value.to_owned())
}

/// Resolves an optional docs-owned relative artifact path from the manifest.
fn docs_manifest_relative_path(
    manifest: &Value,
    path: &[&str],
    default: &str,
    label: &str,
) -> Result<String, i32> {
    docs_validate_relative_path(
        docs_manifest_string_path(manifest, path).unwrap_or(default),
        label,
    )
}

/// Resolves a required docs-owned relative artifact path from the manifest.
fn docs_manifest_required_relative_path(
    manifest: &Value,
    path: &[&str],
    label: &str,
) -> Result<String, i32> {
    let value = docs_manifest_string_path(manifest, path).ok_or_else(|| {
        eprintln!("docs build missing docs.{label} in manifest");
        66
    })?;
    docs_validate_relative_path(value, label)
}

/// Performs docs manifest string array.
fn docs_manifest_string_array(manifest: &Value, key: &str) -> Vec<String> {
    manifest
        .get("docs")
        .and_then(Value::as_object)
        .and_then(|docs| docs.get(key))
        .and_then(Value::as_array)
        .map(|values| {
            values
                .iter()
                .filter_map(Value::as_str)
                .filter(|value| !value.is_empty())
                .map(ToOwned::to_owned)
                .collect()
        })
        .unwrap_or_default()
}

/// Performs docs manifest output remap.
fn docs_manifest_output_remap(manifest: &Value, source: &str) -> Option<String> {
    manifest
        .get("docs")
        .and_then(Value::as_object)
        .and_then(|docs| docs.get("output_remap"))
        .and_then(Value::as_array)
        .and_then(|entries| {
            entries.iter().find_map(|entry| {
                (entry.get("source").and_then(Value::as_str) == Some(source))
                    .then(|| entry.get("output").and_then(Value::as_str))
                    .flatten()
                    .filter(|value| !value.is_empty())
                    .map(ToOwned::to_owned)
            })
        })
}

/// Performs docs manifest publish mode.
fn docs_manifest_publish_mode(manifest: &Value) -> Result<&str, i32> {
    match docs_manifest_string(manifest, "publish_mode").unwrap_or("all") {
        "all" => Ok("all"),
        "nav_only" => Ok("nav_only"),
        "routed_only" => Ok("routed_only"),
        _ => {
            eprintln!("docs build publish_mode must be one of: all, nav_only, routed_only");
            Err(66)
        }
    }
}

/// Performs docs output relative.
fn docs_output_relative(source: &str, manifest: &Value) -> Option<String> {
    if let Some(output) = docs_manifest_output_remap(manifest, source) {
        return (!Path::new(&output).is_absolute() && !output.contains("..")).then_some(output);
    }
    let path = Path::new(source);
    let file_name = path.file_name()?.to_str()?;
    let output_name = if matches!(file_name, "README.md" | "index.md") {
        "index.html".to_owned()
    } else {
        format!("{}.html", file_name.strip_suffix(".md")?)
    };
    let parent = path
        .parent()
        .filter(|parent| !parent.as_os_str().is_empty());
    Some(
        parent
            .map(|parent| parent.join(&output_name).to_string_lossy().into_owned())
            .unwrap_or_else(|| output_name.clone()),
    )
}

/// Collects published docs outputs declared by navigation.
fn docs_nav_published_outputs(
    nav_entries: &[docs::DocsNavEntry],
) -> std::collections::BTreeSet<String> {
    nav_entries.iter().map(|entry| entry.path.clone()).collect()
}

/// Collects published docs outputs declared by page routes.
fn docs_route_published_outputs(
    artifact_root: &Path,
) -> Result<std::collections::BTreeSet<String>, i32> {
    let routes =
        json_commands::json_doc_load_file(&artifact_root.join("data/contracts/routes.json"))
            .ok_or(66)?;
    Ok(routes
        .get("routes")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter(|route| route.get("kind").and_then(Value::as_str) == Some("page"))
        .filter_map(|route| route.get("artifact").and_then(Value::as_str))
        .filter(|artifact| !artifact.is_empty())
        .map(ToOwned::to_owned)
        .collect())
}

/// Performs docs relative asset.
fn docs_relative_asset(page_rel: &str, asset_rel: &str) -> String {
    let depth = page_rel.bytes().filter(|byte| *byte == b'/').count();
    format!("{}{}", "../".repeat(depth), asset_rel)
}

/// Resolves the trusted repository root for a docs app build.
fn docs_repo_root(start: &Path) -> Option<PathBuf> {
    let start = if start.is_absolute() {
        start.to_path_buf()
    } else {
        std::env::current_dir().ok()?.join(start)
    };
    let start = start.canonicalize().ok()?;
    let mut current = Some(start.as_path());
    while let Some(path) = current {
        if path.join("apps").is_dir() && path.join("scripts").is_dir() && path.join("src").is_dir()
        {
            return Some(path.to_path_buf());
        }
        current = path.parent();
    }
    None
}

/// Builds a fingerprint for the Rustdoc inputs that feed the docs app.
fn docs_rustdoc_input_digest(repo_root: &Path) -> Option<String> {
    let src_root = repo_root.join("src");
    let mut files = Vec::new();
    collect_tree_files(&src_root, &src_root, &mut files)?;
    files.sort();
    let mut digest = Sha256::new();
    for relative in files {
        digest.update(relative.to_string_lossy().as_bytes());
        digest.update([0]);
        digest.update(stdfs::read(src_root.join(&relative)).ok()?);
        digest.update([0]);
    }
    for file_name in ["Cargo.toml", "Cargo.lock"] {
        let path = repo_root.join(file_name);
        digest.update(file_name.as_bytes());
        digest.update([0]);
        digest.update(stdfs::read(path).ok()?);
        digest.update([0]);
    }
    Some(
        digest
            .finalize()
            .iter()
            .map(|byte| format!("{byte:02x}"))
            .collect(),
    )
}

/// Resolves the cache directory for a Rustdoc artifact fingerprint.
fn docs_rustdoc_artifact_cache_dir(repo_root: &Path, fingerprint: &str) -> PathBuf {
    repo_root
        .join("target/rustdoc/artifact-cache/dev_docs")
        .join(fingerprint)
}

/// Checks whether a stored Rustdoc fingerprint file matches the current input digest.
fn docs_rustdoc_fingerprint_matches(path: &Path, fingerprint: &str) -> bool {
    stdfs::read_to_string(path)
        .map(|stored| stored.trim() == fingerprint)
        .unwrap_or(false)
}

/// Returns the existing Rustdoc output directory when it matches the current Rust inputs.
fn docs_valid_existing_rustdoc_output_dir(
    app_root: &Path,
    artifact_root: &Path,
    manifest: &Value,
) -> Result<Option<PathBuf>, i32> {
    if !artifact_root.is_dir() {
        return Ok(None);
    }
    let repo_root = docs_repo_root(app_root).ok_or(66)?;
    let fingerprint = docs_rustdoc_input_digest(&repo_root).ok_or(69)?;
    let rustdoc_output_dir = docs_rustdoc_output_dir(artifact_root, manifest)?;
    let fingerprint_path = rustdoc_output_dir.join(".pharos-rustdoc-input.sha256");
    if rustdoc_output_dir.join("index.html").is_file()
        && rustdoc_output_dir
            .join("pharos_native/index.html")
            .is_file()
        && docs_rustdoc_fingerprint_matches(&fingerprint_path, &fingerprint)
    {
        return Ok(Some(rustdoc_output_dir));
    }
    Ok(None)
}

/// Removes artifact contents while leaving one known-valid generated directory in place.
#[cfg(test)]
fn remove_artifact_contents_except(artifact_root: &Path, preserved_path: &Path) -> Result<(), i32> {
    for entry in stdfs::read_dir(artifact_root).map_err(|_| 69)? {
        let entry = entry.map_err(|_| 69)?;
        let path = entry.path();
        if preserved_path.starts_with(&path) {
            continue;
        }
        if path.is_dir() {
            stdfs::remove_dir_all(&path).map_err(|_| 69)?;
        } else {
            stdfs::remove_file(&path).map_err(|_| 69)?;
        }
    }
    Ok(())
}

/// Resolves the Rustdoc output directory declared by a docs app manifest.
fn docs_rustdoc_output_dir(artifact_root: &Path, manifest: &Value) -> Result<PathBuf, i32> {
    Ok(artifact_root.join(docs_manifest_relative_path(
        manifest,
        &["rustdoc", "output_dir"],
        "html",
        "rustdoc.output_dir",
    )?))
}

fn docs_files_equal(source: &Path, destination: &Path, source_metadata: &stdfs::Metadata) -> bool {
    let Ok(destination_metadata) = stdfs::metadata(destination) else {
        return false;
    };
    if !destination_metadata.is_file() || destination_metadata.len() != source_metadata.len() {
        return false;
    }
    match (stdfs::read(source), stdfs::read(destination)) {
        (Ok(source_bytes), Ok(destination_bytes)) => source_bytes == destination_bytes,
        _ => false,
    }
}

fn docs_sync_rustdoc_tree(source: &Path, destination: &Path, depth: usize) -> Result<(), i32> {
    if depth > 64 {
        return Err(69);
    }
    stdfs::create_dir_all(destination).map_err(|_| 69)?;
    let mut source_names = BTreeSet::new();
    for entry in stdfs::read_dir(source).map_err(|_| 69)? {
        let entry = entry.map_err(|_| 69)?;
        source_names.insert(entry.file_name());
        let source_path = entry.path();
        let destination_path = destination.join(entry.file_name());
        let metadata = stdfs::symlink_metadata(&source_path).map_err(|_| 69)?;
        if metadata.file_type().is_symlink() {
            return Err(78);
        }
        if metadata.is_dir() {
            docs_sync_rustdoc_tree(&source_path, &destination_path, depth + 1)?;
            continue;
        }
        if !metadata.is_file() {
            continue;
        }
        if docs_files_equal(&source_path, &destination_path, &metadata) {
            continue;
        }
        if let Some(parent) = destination_path.parent() {
            stdfs::create_dir_all(parent).map_err(|_| 69)?;
        }
        stdfs::copy(&source_path, &destination_path).map_err(|_| 69)?;
    }
    if destination.is_dir() {
        for entry in stdfs::read_dir(destination).map_err(|_| 69)? {
            let entry = entry.map_err(|_| 69)?;
            if source_names.contains(&entry.file_name()) {
                continue;
            }
            let path = entry.path();
            let metadata = stdfs::symlink_metadata(&path).map_err(|_| 69)?;
            if metadata.file_type().is_symlink() {
                return Err(78);
            }
            if metadata.is_dir() {
                stdfs::remove_dir_all(&path).map_err(|_| 69)?;
            } else if metadata.is_file() {
                stdfs::remove_file(&path).map_err(|_| 69)?;
            }
        }
    }
    Ok(())
}

/// Copies an existing Rustdoc tree into another directory.
fn docs_copy_rustdoc_tree(source: &Path, destination: &Path) -> Result<(), i32> {
    docs_sync_rustdoc_tree(source, destination, 0)
}

/// Restores a cached Rustdoc tree into the current docs app artifact when inputs are unchanged.
fn docs_restore_cached_rustdoc_artifact(
    repo_root: &Path,
    artifact_root: &Path,
    manifest: &Value,
    fingerprint: &str,
) -> Result<bool, i32> {
    let cache_dir = docs_rustdoc_artifact_cache_dir(repo_root, fingerprint);
    let cache_fingerprint_path = cache_dir.join(".pharos-rustdoc-input.sha256");
    if !cache_dir.join("index.html").is_file()
        || !cache_dir.join("pharos_native/index.html").is_file()
        || !docs_rustdoc_fingerprint_matches(&cache_fingerprint_path, fingerprint)
    {
        return Ok(false);
    }
    let rustdoc_output_dir = docs_rustdoc_output_dir(artifact_root, manifest)?;
    docs_copy_rustdoc_tree(&cache_dir, &rustdoc_output_dir)?;
    Ok(true)
}

/// Builds the bundled Rust API and source reference for a docs app.
fn build_docs_rustdoc_reference(
    app_root: &Path,
    artifact_root: &Path,
    manifest: &Value,
) -> Result<(), i32> {
    let repo_root = docs_repo_root(app_root).ok_or_else(|| {
        eprintln!("docs rustdoc build could not resolve repository root");
        66
    })?;
    let rustdoc_output_dir = docs_rustdoc_output_dir(artifact_root, manifest)?;
    let fingerprint = docs_rustdoc_input_digest(&repo_root).ok_or_else(|| {
        eprintln!("docs rustdoc build could not fingerprint inputs");
        69
    })?;
    let fingerprint_path = rustdoc_output_dir.join(".pharos-rustdoc-input.sha256");
    if rustdoc_output_dir.join("index.html").is_file()
        && docs_rustdoc_fingerprint_matches(&fingerprint_path, &fingerprint)
    {
        return Ok(());
    }
    if docs_restore_cached_rustdoc_artifact(&repo_root, artifact_root, manifest, &fingerprint)? {
        return Ok(());
    }

    let output = docs_run_cargo_doc(&repo_root).map_err(|error| {
        eprintln!("docs rustdoc build could not launch cargo doc: {error}");
        69
    })?;
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        if !stderr.trim().is_empty() {
            eprintln!("{stderr}");
        }
        let stdout = String::from_utf8_lossy(&output.stdout);
        if !stdout.trim().is_empty() {
            eprintln!("{stdout}");
        }
        eprintln!("docs rustdoc generation failed");
        return Err(70);
    }

    let generated_doc_root = repo_root.join("target/rustdoc/doc");
    if !generated_doc_root.join("src").is_dir() {
        eprintln!(
            "docs rustdoc build did not produce inline source output: {}",
            generated_doc_root.join("src").display()
        );
        return Err(70);
    }
    if !generated_doc_root
        .join("pharos_native/index.html")
        .is_file()
    {
        eprintln!(
            "docs rustdoc build did not produce pharos_native index: {}",
            generated_doc_root
                .join("pharos_native/index.html")
                .display()
        );
        return Err(70);
    }

    docs_copy_rustdoc_tree(&generated_doc_root, &rustdoc_output_dir)?;
    let rustdoc_index = rustdoc_output_dir.join("index.html");
    let rustdoc_index_html = "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"UTF-8\">\n<meta http-equiv=\"refresh\" content=\"0; url=pharos_native/index.html\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n<title>Pharos API Docs</title>\n</head>\n<body>\n<p><a href=\"pharos_native/index.html\">Continue to the API docs</a></p>\n</body>\n</html>\n";
    stdfs::write(&rustdoc_index, rustdoc_index_html.as_bytes()).map_err(|_| 69)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        stdfs::set_permissions(&rustdoc_index, stdfs::Permissions::from_mode(0o644))
            .map_err(|_| 69)?;
    }
    stdfs::write(&fingerprint_path, format!("{fingerprint}\n").as_bytes()).map_err(|_| 69)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        stdfs::set_permissions(&fingerprint_path, stdfs::Permissions::from_mode(0o644))
            .map_err(|_| 69)?;
    }
    let cache_dir = docs_rustdoc_artifact_cache_dir(&repo_root, &fingerprint);
    let _ = docs_copy_rustdoc_tree(&rustdoc_output_dir, &cache_dir);
    Ok(())
}

/// Builds docs pages.
fn build_docs_pages(app_root: &Path, artifact_root: &Path, manifest: &Value) -> Result<(), i32> {
    if docs_manifest_string(manifest, "source_dir").is_none() {
        return Ok(());
    }
    let source_dir_value = docs_manifest_string(manifest, "source_dir").ok_or_else(|| {
        eprintln!("docs build missing docs.source_dir in manifest");
        66
    })?;
    let source_dir = app_root.join(source_dir_value);
    if !source_dir.is_dir() {
        eprintln!(
            "docs source_dir is not a directory: {}",
            source_dir.display()
        );
        return Err(66);
    }
    let output_dir =
        artifact_root.join(docs_manifest_string(manifest, "output_dir").unwrap_or("."));
    stdfs::create_dir_all(&output_dir).map_err(|_| 69)?;
    let page_template_value = docs_manifest_string(manifest, "page_template").ok_or_else(|| {
        eprintln!("docs build missing docs.page_template in manifest");
        66
    })?;
    let page_template_path = artifact_root.join(page_template_value);
    let page_template = stdfs::read_to_string(&page_template_path).map_err(|_| {
        eprintln!(
            "docs page template unavailable: {}",
            page_template_path.display()
        );
        66
    })?;
    let sidebar_template_value =
        docs_manifest_string(manifest, "sidebar_template").ok_or_else(|| {
            eprintln!("docs build missing docs.sidebar_template in manifest");
            66
        })?;
    let sidebar_template_path = artifact_root.join(sidebar_template_value);
    let sidebar_template = stdfs::read_to_string(&sidebar_template_path).map_err(|_| {
        eprintln!(
            "docs sidebar template unavailable: {}",
            sidebar_template_path.display()
        );
        66
    })?;
    let sidebar_item_template_value = docs_manifest_string(manifest, "sidebar_item_template")
        .ok_or_else(|| {
            eprintln!("docs build missing docs.sidebar_item_template in manifest");
            66
        })?;
    let sidebar_item_template_path = artifact_root.join(sidebar_item_template_value);
    let sidebar_item_template =
        stdfs::read_to_string(&sidebar_item_template_path).map_err(|_| {
            eprintln!(
                "docs sidebar item template unavailable: {}",
                sidebar_item_template_path.display()
            );
            66
        })?;
    let sidebar_group_template_value = docs_manifest_required_relative_path(
        manifest,
        &["sidebar_group_template"],
        "sidebar_group_template",
    )?;
    let sidebar_group_template_path = pharos_runtime_core::safe_existing_artifact_path(
        artifact_root,
        &sidebar_group_template_value,
    )
    .ok_or(66)?;
    if stdfs::metadata(&sidebar_group_template_path)
        .map_err(|_| 66)?
        .len()
        > 8 * 1024 * 1024
    {
        return Err(66);
    }
    let sidebar_group_template =
        stdfs::read_to_string(sidebar_group_template_path).map_err(|_| 66)?;

    let nav_manifest_value = docs_manifest_string(manifest, "nav_manifest").ok_or_else(|| {
        eprintln!("docs build missing docs.nav_manifest in manifest");
        66
    })?;
    let nav_artifact_value = nav_manifest_value
        .strip_suffix(".yml")
        .or_else(|| nav_manifest_value.strip_suffix(".yaml"))
        .map(|stem| format!("{stem}.json"))
        .unwrap_or_else(|| nav_manifest_value.to_owned());
    let nav_path = artifact_root.join(nav_artifact_value);
    let nav = json_commands::json_doc_load_file(&nav_path).ok_or_else(|| {
        eprintln!(
            "docs navigation artifact unavailable: {}",
            nav_path.display()
        );
        66
    })?;
    let mut nav_entries = Vec::new();
    if !docs::docs_nav_collect_entries_local(
        nav.get("items").unwrap_or(&Value::Null),
        0,
        &mut nav_entries,
    ) {
        eprintln!(
            "docs navigation failed: could not collect entries from nav_manifest={} artifact={}",
            nav_manifest_value,
            nav_path.display()
        );
        return Err(69);
    }
    let strip_dirs = docs_manifest_string_array(manifest, "strip_dirs");
    let strip_files = docs_manifest_string_array(manifest, "strip_files");
    let publish_mode = docs_manifest_publish_mode(manifest)?;
    let published_outputs = docs_nav_published_outputs(&nav_entries);
    let routed_outputs = if publish_mode == "routed_only" {
        Some(docs_route_published_outputs(artifact_root)?)
    } else {
        None
    };
    let mut output_remap = docs::DocsOutputRemap::default();
    if let Some(entries) = manifest
        .get("docs")
        .and_then(Value::as_object)
        .and_then(|docs| docs.get("output_remap"))
        && docs::docs_output_remap_load_json_array(entries, &mut output_remap) != 0
    {
        eprintln!(
            "docs output_remap failed: docs.output_remap must contain non-empty source/output pairs"
        );
        return Err(69);
    }
    let mut markdown_files = Vec::new();
    if !docs::collect_md_files(&source_dir, "", 0, 64, &mut markdown_files) {
        eprintln!(
            "docs source collection failed: source_dir={}",
            source_dir.display()
        );
        return Err(69);
    }
    let wordmark_asset =
        docs_manifest_required_relative_path(manifest, &["wordmark_src"], "wordmark_src")?;
    let favicon_asset =
        docs_manifest_required_relative_path(manifest, &["favicon_src"], "favicon_src")?;
    let stylesheet_asset =
        docs_manifest_required_relative_path(manifest, &["stylesheet_src"], "stylesheet_src")?;
    for (source_rel, source_path) in markdown_files {
        if strip_files.iter().any(|value| value == &source_rel)
            || strip_dirs
                .iter()
                .any(|value| source_rel == *value || source_rel.starts_with(&format!("{value}/")))
        {
            continue;
        }
        let output_rel = docs_output_relative(&source_rel, manifest).ok_or_else(|| {
            eprintln!("docs output path failed: source={source_rel}");
            69
        })?;
        if publish_mode == "nav_only" && !published_outputs.contains(&output_rel) {
            continue;
        }
        if routed_outputs
            .as_ref()
            .is_some_and(|outputs| !outputs.contains(&output_rel))
        {
            continue;
        }
        let markdown = stdfs::read_to_string(&source_path).map_err(|_| {
            eprintln!("docs source read failed: source={}", source_path.display());
            66
        })?;
        let body = docs::docs_markdown_to_html_with_remap_for_page(
            &markdown,
            Some(&output_remap),
            &output_rel,
        )
        .ok_or_else(|| {
            eprintln!(
                "docs markdown render failed: source={} output={}",
                source_path.display(),
                output_rel
            );
            69
        })?;
        let title = docs::docs_page_title(Some(&markdown), Some(&source_rel)).ok_or_else(|| {
            eprintln!("docs title render failed: source={source_rel}");
            69
        })?;
        let sidebar = docs::docs_render_sidebar(
            &sidebar_template,
            &sidebar_item_template,
            &sidebar_group_template,
            nav.get("title").and_then(Value::as_str).unwrap_or_default(),
            &nav_entries,
            &output_rel,
        )
        .ok_or_else(|| {
            eprintln!(
                "docs sidebar render failed: source={} output={} nav_manifest={}",
                source_rel, output_rel, nav_manifest_value
            );
            69
        })?;
        let rendered = docs::docs_render_page(
            &page_template,
            &title,
            &sidebar,
            &body,
            &docs::docs_root_href(&output_rel).ok_or(69)?,
            &docs_relative_asset(&output_rel, &wordmark_asset),
            &docs_relative_asset(&output_rel, &favicon_asset),
            &docs_relative_asset(&output_rel, &stylesheet_asset),
        )
        .ok_or_else(|| {
            eprintln!(
                "docs page render failed: source={} output={} template={}",
                source_rel,
                output_rel,
                page_template_path.display()
            );
            69
        })?;
        let output_path = output_dir.join(&output_rel);
        if let Some(parent) = output_path.parent() {
            stdfs::create_dir_all(parent).map_err(|_| {
                eprintln!("docs output directory create failed: {}", parent.display());
                69
            })?;
        }
        fs::write_file_within(artifact_root, &output_path, rendered.as_bytes(), 0o644).map_err(
            |_| {
                eprintln!("docs output write failed: {}", output_path.display());
                69
            },
        )?;
    }
    for entry in &nav_entries {
        if !output_dir.join(&entry.path).is_file() && !entry.path.starts_with("html/") {
            eprintln!(
                "docs navigation target missing: nav_path={} expected_output={}",
                entry.path,
                output_dir.join(&entry.path).display()
            );
            return Err(69);
        }
    }
    let index_template_value =
        docs_manifest_string(manifest, "index_template").ok_or_else(|| {
            eprintln!("docs build missing docs.index_template in manifest");
            66
        })?;
    let index_template_path = artifact_root.join(index_template_value);
    let index_template = stdfs::read_to_string(&index_template_path).map_err(|_| {
        eprintln!(
            "docs index template unavailable: {}",
            index_template_path.display()
        );
        66
    })?;
    let index_path = output_dir.join("index.html");
    if !index_path.is_file() {
        fs::write_file_within(artifact_root, &index_path, index_template.as_bytes(), 0o644)
            .map_err(|_| {
                eprintln!("docs index write failed: {}", index_path.display());
                69
            })?;
    }
    Ok(())
}

/// Removes non manifest YAML from artifact.
fn remove_non_manifest_yaml_from_artifact(root: &Path, depth: usize) -> Result<(), i32> {
    if depth > 64 {
        return Err(69);
    }
    for entry in stdfs::read_dir(root).map_err(|_| 69)? {
        let entry = entry.map_err(|_| 69)?;
        let path = entry.path();
        let metadata = stdfs::symlink_metadata(&path).map_err(|_| 69)?;
        if metadata.file_type().is_symlink() {
            return Err(78);
        }
        if metadata.is_dir() {
            remove_non_manifest_yaml_from_artifact(&path, depth + 1)?;
            continue;
        }
        if !metadata.is_file() {
            continue;
        }
        let Some(file_name) = path.file_name().and_then(|value| value.to_str()) else {
            continue;
        };
        let is_yaml = file_name.ends_with(".yml") || file_name.ends_with(".yaml");
        if !is_yaml || file_name == "pharos.app.yml" {
            continue;
        }
        stdfs::remove_file(&path).map_err(|_| 69)?;
    }
    Ok(())
}

fn artifact_file_copy_is_current(
    source_path: &Path,
    destination_path: &Path,
    relative_path: &Path,
    previous_outputs: &BTreeMap<PathBuf, Value>,
) -> bool {
    let Some(previous) = previous_outputs.get(relative_path) else {
        return false;
    };
    previous.get("ownership").and_then(Value::as_str) == Some("app_source_copy")
        && metadata_matches_output(source_path, previous, "source")
        && metadata_matches_output(destination_path, previous, "artifact")
}

fn cleanup_incremental_artifact_outputs(
    artifact_root: &Path,
    source_root: &Path,
    preserved_dir: Option<&Path>,
    previous_outputs: &BTreeMap<PathBuf, Value>,
) -> Result<(), i32> {
    for (relative, output) in previous_outputs {
        let Some(portable_path) = output.get("path").and_then(Value::as_str) else {
            continue;
        };
        let Some(path) =
            pharos_runtime_core::safe_existing_artifact_path(artifact_root, portable_path)
        else {
            continue;
        };
        if preserved_dir.is_some_and(|preserved| path.starts_with(preserved)) {
            continue;
        }
        let ownership = output
            .get("ownership")
            .and_then(Value::as_str)
            .unwrap_or_default();
        let should_remove = ownership == "pharos_generated"
            || (ownership == "app_source_copy" && !source_root.join(relative).is_file());
        if should_remove && path.is_file() {
            stdfs::remove_file(path).map_err(|_| 69)?;
        }
    }
    Ok(())
}

/// Copies source tree to artifact.
fn copy_source_tree_to_artifact(
    source: &Path,
    destination: &Path,
    source_root: &Path,
    depth: usize,
    previous_outputs: &BTreeMap<PathBuf, Value>,
    files: &mut u64,
    bytes: &mut u64,
) -> Result<(), i32> {
    if depth > 64 {
        return Err(69);
    }
    for entry in stdfs::read_dir(source).map_err(|_| 69)? {
        let entry = entry.map_err(|_| 69)?;
        let source_path = entry.path();
        let destination_path = destination.join(entry.file_name());
        if matches!(entry.file_name().to_str(), Some("start.sh")) {
            continue;
        }
        if entry
            .file_name()
            .to_str()
            .is_some_and(ignore_non_contract_artifact_entry)
        {
            continue;
        }
        let metadata = stdfs::symlink_metadata(&source_path).map_err(|_| 69)?;
        if metadata.file_type().is_symlink() {
            return Err(78);
        }
        if metadata.is_dir() {
            stdfs::create_dir_all(&destination_path).map_err(|_| 69)?;
            copy_source_tree_to_artifact(
                &source_path,
                &destination_path,
                source_root,
                depth + 1,
                previous_outputs,
                files,
                bytes,
            )?;
            continue;
        }
        if !metadata.is_file() {
            continue;
        }
        *files = files.saturating_add(1);
        *bytes = bytes.saturating_add(metadata.len());
        if *files > MAX_BUILD_FILES || *bytes > MAX_BUILD_BYTES {
            return Err(69);
        }
        let relative_path = source_path.strip_prefix(source_root).map_err(|_| 69)?;
        let copy_is_current = artifact_file_copy_is_current(
            &source_path,
            &destination_path,
            relative_path,
            previous_outputs,
        );
        if !copy_is_current {
            if let Some(parent) = destination_path.parent() {
                stdfs::create_dir_all(parent).map_err(|_| 69)?;
            }
            stdfs::copy(&source_path, &destination_path).map_err(|_| 69)?;
        }
        preserve_model_payload_mtime(relative_path, &metadata, &destination_path)?;
    }
    Ok(())
}

/// Preserves source timestamps for model payloads so cached model archives pass ownership checks.
fn preserve_model_payload_mtime(
    relative_path: &Path,
    source_metadata: &stdfs::Metadata,
    destination_path: &Path,
) -> Result<(), i32> {
    if !is_lazy_model_payload_path(relative_path) {
        return Ok(());
    }
    let source_modified = source_metadata.modified().map_err(|_| 69)?;
    let destination_modified = stdfs::metadata(destination_path)
        .and_then(|metadata| metadata.modified())
        .map_err(|_| 69)?;
    if destination_modified == source_modified {
        return Ok(());
    }
    stdfs::OpenOptions::new()
        .write(true)
        .open(destination_path)
        .and_then(|file| file.set_times(stdfs::FileTimes::new().set_modified(source_modified)))
        .map_err(|_| 69)
}

/// Clears one app runtime in place.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::free_app`].
///
/// # Returns
///
/// Returns after [`crate::runtime::free_app`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::free_app(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime`] for adjacent helpers that share the same runtime surface.
pub fn free_app(app: &mut AppRuntime) {
    *app = AppRuntime::default();
}

#[cfg(test)]
mod architect_llm_vendor_tests {
    use pharos_runtime_architect::llm_vendor::llm_vendor_failure_excerpt;

    #[test]
    fn llm_vendor_failure_excerpt_redacts_secret_like_values() {
        let excerpt = llm_vendor_failure_excerpt(
            r#"{"error":{"message":"bad key sk-live-secret and Bearer token-value","access_token":"abc"}}"#,
        );
        assert!(excerpt.contains("[redacted]"));
        assert!(!excerpt.contains("sk-live-secret"));
        assert!(!excerpt.contains("token-value"));
        assert!(!excerpt.contains("abc"));
    }
}

#[cfg(test)]
mod route_path_tests {
    use super::{
        active_session_user_id, actor_owns_mutation_resource, app_declarative_route_response,
        app_scope_path, app_uses_file_backed_runtime_state, app_uses_relational_runtime_authority,
        apply_route_response_middleware, canonical_http_error_body,
        docs_cargo_executable_candidates, docs_manifest_bool_path, docs_manifest_publish_mode,
        docs_manifest_required_relative_path, docs_nav_published_outputs, docs_repo_root,
        docs_restore_cached_rustdoc_artifact, docs_route_published_outputs,
        docs_rustdoc_artifact_cache_dir, docs_rustdoc_fingerprint_matches, dynamic,
        framework_builtin_response, http_route_redirect_for_request,
        ignore_non_contract_artifact_entry, is_business_availability_create_path,
        matched_app_route, native_session_token_hash, normalized_booking_time,
        process_one_background_job, remove_artifact_contents_except, route_request_hook_failure,
        route_request_middleware_failure, route_requires_state_mutation_guard,
        runtime_framework_webhook_endpoint_id, runtime_timestamp_seconds, sha256_hex,
        tree_content_digest, verify_generated_ownership_manifest,
    };
    use crate::config::AppRuntime;
    use crate::runtime::RuntimeStack;
    use crate::runtime::http;
    use pharos_runtime_core::application_ir::{
        APPLICATION_IR_VERSION, ApplicationIr, ContractId, RouteIr, RouteSecurityPosture,
        SourceProvenance,
    };
    use pharos_runtime_docs::docs::DocsNavEntry;
    use serde_json::{Value, json};
    use std::collections::{BTreeMap, BTreeSet};
    use std::fs;
    use std::io::Read;
    use std::path::Path;
    use std::path::PathBuf;
    use std::sync::Arc;
    use std::time::{SystemTime, UNIX_EPOCH};

    /// Distinguishes unused browser connections from timed-out partial requests.
    #[test]
    fn unused_preconnection_timeout_is_not_a_bad_request() {
        for kind in [std::io::ErrorKind::TimedOut, std::io::ErrorKind::WouldBlock] {
            let mut reader = std::io::Cursor::new(Vec::<u8>::new()).chain(TimeoutReader(kind));
            assert_eq!(
                super::read_http_request(&mut reader).unwrap_err(),
                "request connection closed"
            );
            let mut reader = std::io::Cursor::new(b"GET /ucal/ HTTP/1.1\r\n".to_vec())
                .chain(TimeoutReader(kind));
            assert_eq!(
                super::read_http_request(&mut reader).unwrap_err(),
                "request parse failed"
            );
        }
    }

    struct TimeoutReader(std::io::ErrorKind);

    impl std::io::Read for TimeoutReader {
        /// Simulates a socket reaching its read deadline without a wall-clock wait.
        fn read(&mut self, _buffer: &mut [u8]) -> std::io::Result<usize> {
            Err(std::io::Error::from(self.0))
        }
    }

    /// Creates one isolated temp root for runtime route tests.
    fn temp_root(label: &str) -> PathBuf {
        let nonce = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        let path = std::env::temp_dir().join(format!(
            "pharos-runtime-{label}-{}-{nonce}",
            std::process::id()
        ));
        fs::create_dir_all(&path).expect("temp root");
        path
    }

    /// Builds one synthetic HTTP request for route tests.
    fn request(
        method: &str,
        target: &str,
        headers: &str,
        content_type: Option<&str>,
        body: &str,
    ) -> http::HttpRequest {
        http::HttpRequest {
            method: method.to_owned(),
            target: target.to_owned(),
            cookie: None,
            content_type: content_type.map(str::to_owned),
            headers: headers.to_owned(),
            body: body.as_bytes().to_vec(),
            body_file_path: None,
            body_len: body.len(),
            is_multipart: false,
        }
    }

    /// Proves framework-owned readiness routes are stable, unauthenticated, and method bounded.
    #[test]
    fn framework_builtin_readiness_and_liveness_contract_is_stable() {
        let artifact_root = temp_root("readiness-contract").join("artifact");
        fs::create_dir_all(&artifact_root).expect("artifact root");
        let app = AppRuntime {
            app_id: Some("ready_app".to_owned()),
            host_profile: Some("static-app".to_owned()),
            artifact_dir: Some(artifact_root.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        let stack = RuntimeStack {
            apps: vec![app],
            failed_apps: Vec::new(),
            host: Some("127.0.0.1".to_owned()),
            port: Some("0".to_owned()),
            socket_path: None,
        };

        let health = framework_builtin_response("GET", "/health", None, Some(&stack))
            .expect("health response");
        assert_eq!(health.status_code, 200);
        assert!(health.body.contains("server_status=green\n"));
        assert!(health.body.contains("probe=liveness\n"));
        assert!(health.body.contains("readiness_status=ready\n"));

        let live =
            framework_builtin_response("HEAD", "/live?probe=1", None, Some(&stack)).expect("live");
        assert_eq!(live.status_code, 200);
        assert_eq!(live.body, "server_status=live\n");

        let ready = framework_builtin_response("GET", "/ready", None, Some(&stack))
            .expect("ready response");
        assert_eq!(ready.status_code, 200);
        assert_eq!(ready.body, "server_status=ready\n");

        let not_ready = framework_builtin_response(
            "GET",
            "/ready",
            None,
            Some(&RuntimeStack {
                apps: Vec::new(),
                failed_apps: Vec::new(),
                host: None,
                port: None,
                socket_path: None,
            }),
        )
        .expect("not ready response");
        assert_eq!(not_ready.status_code, 503);
        assert_eq!(not_ready.body, "server_status=not_ready\n");

        let rejected =
            framework_builtin_response("POST", "/ready", None, Some(&stack)).expect("method");
        assert_eq!(rejected.status_code, 405);
        assert_eq!(rejected.body, "method not allowed\n");
        let quarantined_stack = RuntimeStack {
            apps: stack.apps.clone(),
            failed_apps: vec![super::RuntimeAppLoadFailure {
                app_id: "broken_app".to_owned(),
                app_root: "apps/broken_app".to_owned(),
                mount_path: "/broken".to_owned(),
                artifact_dir: "dist/apps/broken_app".to_owned(),
                error: "generated artifact ownership verification failed".to_owned(),
            }],
            host: stack.host.clone(),
            port: stack.port.clone(),
            socket_path: stack.socket_path.clone(),
        };
        assert!(!super::runtime_stack_probe_ready(&quarantined_stack));
        let quarantined_ready =
            framework_builtin_response("GET", "/ready", None, Some(&quarantined_stack))
                .expect("quarantined ready response");
        assert_eq!(quarantined_ready.status_code, 503);
        assert_eq!(quarantined_ready.body, "server_status=not_ready\n");
    }

    /// Verifies technician availability routes never enter the business-hours create path.
    #[test]
    fn technician_availability_path_is_not_business_availability_path() {
        assert!(is_business_availability_create_path(
            "/businesses/lotus-studio/availability/new/"
        ));
        assert!(!is_business_availability_create_path(
            "/businesses/lotus-studio/technicians/12/availability/new/"
        ));
        assert!(!is_business_availability_create_path(
            "/businesses/technicians/12/availability/new/"
        ));
    }

    #[test]
    /// Performs enhanced provider checkout redirects through HX-Redirect.
    fn enhanced_provider_checkout_redirect_uses_hx_redirect_header() {
        let enhanced = request("POST", "/checkout", "HX-Request: true\r\n", None, "");
        let response = String::from_utf8(http_route_redirect_for_request(
            &enhanced,
            "https://checkout.stripe.com/c/pay/cs_test_123",
        ))
        .expect("response utf8");

        assert!(response.starts_with("HTTP/1.1 200 OK\r\n"));
        assert!(
            response.contains("HX-Redirect: https://checkout.stripe.com/c/pay/cs_test_123\r\n")
        );
        assert!(!response.contains("Location:"));

        let normal = request("POST", "/checkout", "", None, "");
        let response = String::from_utf8(http_route_redirect_for_request(
            &normal,
            "https://checkout.stripe.com/c/pay/cs_test_456",
        ))
        .expect("response utf8");

        assert!(response.starts_with("HTTP/1.1 303 See Other\r\n"));
        assert!(response.contains("Location: https://checkout.stripe.com/c/pay/cs_test_456\r\n"));
    }

    #[test]
    fn app_scope_path_prefixes_mounted_redirect_once() {
        let app = AppRuntime {
            base_path: Some("/ucal".to_owned()),
            ..Default::default()
        };

        assert_eq!(
            app_scope_path(&app, "/appointments/"),
            "/ucal/appointments/"
        );
        assert_eq!(
            app_scope_path(&app, "/ucal/appointments/"),
            "/ucal/appointments/"
        );
    }

    #[test]
    /// Performs framework webhook path accepts only one valid endpoint segment.
    fn framework_webhook_path_accepts_only_one_valid_endpoint_segment() {
        assert_eq!(
            runtime_framework_webhook_endpoint_id("/_pharos/webhooks/local-echo/"),
            Some("local-echo".to_owned())
        );
        assert_eq!(
            runtime_framework_webhook_endpoint_id("/_pharos/webhooks/local-echo"),
            Some("local-echo".to_owned())
        );
        assert_eq!(
            runtime_framework_webhook_endpoint_id("/_pharos/webhooks/local-echo/extra"),
            None
        );
        assert_eq!(
            runtime_framework_webhook_endpoint_id("/_pharos/webhooks/../"),
            None
        );
    }

    /// Normalizes both supported parameter syntaxes into one collision namespace.
    #[test]
    fn route_ownership_normalizes_named_parameters() {
        assert_eq!(
            pharos_runtime_core::route::ownership_route_pattern(
                "/businesses/{business_id}/services/:service_id/"
            ),
            "/businesses/:parameter/services/:parameter/"
        );
        assert_eq!(
            pharos_runtime_core::route::ownership_route_pattern(
                "/businesses/{slug}/services/{id}/"
            ),
            "/businesses/:parameter/services/:parameter/"
        );
    }

    #[test]
    /// Rejects a mismatched generated app artifact before it can enter readiness.
    fn mismatched_generated_artifact_fails_runtime_load() {
        let root = temp_root("mismatched-artifact-load");
        let artifact = root.join("artifact");
        fs::create_dir_all(&artifact).expect("artifact dir");
        fs::write(artifact.join("generated.html"), "tampered").expect("generated");
        fs::write(
            artifact.join("pharos.app.json"),
            serde_json::to_vec(&json!({
                "app_id": "broken_app",
                "artifact": {
                    "input_sha256": "source-digest",
                    "ownership_manifest": "GENERATED-OWNERSHIP.json"
                }
            }))
            .unwrap(),
        )
        .expect("manifest");
        fs::write(
            artifact.join("GENERATED-OWNERSHIP.json"),
            serde_json::to_vec(&json!({
                "schema": "pharos.generated-ownership.v1",
                "input_sha256": "source-digest",
                "outputs": [
                    {
                        "path": "generated.html",
                        "sha256": sha256_hex(b"expected"),
                        "ownership": "pharos_generated"
                    }
                ]
            }))
            .unwrap(),
        )
        .expect("ownership");

        assert_eq!(
            super::load_app_runtime_from_artifact(&artifact),
            Err("generated artifact ownership verification failed")
        );

        fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    fn migration_startup_cache_records_verified_key() {
        let root = temp_root("migration-startup-cache");
        let state_dir = root.join("state");
        fs::create_dir_all(&state_dir).expect("state dir");
        let app = AppRuntime {
            app_id: Some("cache_app".to_owned()),
            state_path: Some(
                state_dir
                    .join("runtime-state.json")
                    .to_string_lossy()
                    .into_owned(),
            ),
            ..AppRuntime::default()
        };

        assert!(!super::cached_verified_migration_state(&app, "cache-key"));
        super::write_verified_migration_state_cache(&app, "cache-key");
        assert!(super::cached_verified_migration_state(&app, "cache-key"));
        assert!(!super::cached_verified_migration_state(&app, "other-key"));

        let cache_path = state_dir.join(".pharos-cache_app-migration-startup-cache.json");
        let cache: Value = serde_json::from_str(&fs::read_to_string(cache_path).expect("cache"))
            .expect("cache json");
        assert_eq!(
            cache.get("schema").and_then(Value::as_str),
            Some("pharos.migration-startup-cache.v1")
        );
        assert_eq!(
            cache.get("status").and_then(Value::as_str),
            Some("verified")
        );
        assert_eq!(
            cache.get("cache_key").and_then(Value::as_str),
            Some("cache-key")
        );

        fs::remove_dir_all(root).expect("cleanup");
    }

    #[cfg(feature = "sqlite")]
    #[test]
    fn selected_logical_contract_controls_startup_readiness() {
        let root = temp_root("logical-migration-startup");
        let missing_manifest_app = AppRuntime {
            host_profile: Some("dynamic-app".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            state_path: Some(root.join("scratch.json").to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        assert!(super::app_uses_relational_runtime_authority(
            &missing_manifest_app
        ));
        assert!(!super::app_uses_file_backed_runtime_state(
            &missing_manifest_app
        ));
        fs::create_dir_all(root.join("data/contracts")).expect("contract directory");
        fs::write(
            root.join("pharos.app.yml"),
            "app_id: todo_list\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        )
        .expect("manifest");
        pharos_runtime_compiler::database::materialize_json(
            Path::new("apps/todo_list/data/contracts/database.yml"),
            root.join("data/contracts/database.json"),
        )
        .expect("logical contract");
        let conf = root.join("runtime.conf");
        fs::write(&conf, "db_backend=sqlite\ndb_path=todo.sqlite3\n").expect("config");
        let config =
            super::database::load_cli_backend_config(&root, Some(&conf), Some("todo_list"))
                .expect("backend config");
        let contract = super::database::selected_logical_contract(&root, "todo_list")
            .expect("contract path")
            .expect("selected logical contract");
        super::database::operations::resolve(&config)
            .expect("backend")
            .apply_contract(&config, &contract)
            .expect("apply logical schema");
        let app = AppRuntime {
            app_id: Some("todo_list".to_owned()),
            app_root: Some(root.to_string_lossy().into_owned()),
            runtime_conf_path: Some(conf.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        assert!(super::app_uses_relational_runtime_authority(&app));
        assert_eq!(super::verify_app_migration_state(&app), Ok(()));
        fs::write(root.join("data/contracts/database.json"), "{}")
            .expect("invalidate logical contract");
        assert_eq!(
            super::verify_app_migration_state(&app),
            Err("logical database contract invalid")
        );
        fs::write(
            root.join("data/contracts/database.json"),
            "{\"backends\":[\"sqlite\"],\"migrations\":[]}",
        )
        .expect("historical vendor manifest");
        assert!(super::app_uses_relational_runtime_authority(&app));
        assert!(super::database::selected_logical_contract(&root, "todo_list").is_err());
        fs::write(
            root.join("pharos.app.yml"),
            "app_id: todo_list\ndatabase:\n  migration_contract: data/contracts/migrations.yml\n",
        )
        .expect("unsupported migration selection");
        assert!(super::app_uses_relational_runtime_authority(&app));
        assert!(super::database::selected_logical_contract(&root, "todo_list").is_err());
        fs::remove_dir_all(root).expect("remove test tree");
    }

    #[test]
    fn incremental_app_copy_skips_unchanged_source_payloads() {
        let suffix = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        let root = std::env::temp_dir().join(format!("pharos-incremental-copy-test-{suffix}"));
        let source = root.join("source");
        let artifact = root.join("artifact");
        fs::create_dir_all(source.join("data/models")).expect("source models");
        fs::create_dir_all(artifact.join("data/models")).expect("artifact models");
        let model_bytes = vec![b'x'; 1024 * 1024];
        fs::write(source.join("data/models/model.bin"), &model_bytes).expect("source model");
        fs::write(artifact.join("data/models/model.bin"), &model_bytes).expect("artifact model");
        fs::write(
            artifact.join("pharos.app.json"),
            serde_json::to_vec(&json!({"artifact": {"input_sha256": "input-digest"}})).unwrap(),
        )
        .expect("manifest");
        super::write_generated_ownership_manifest(&artifact, &source, "input-digest")
            .expect("ownership manifest");
        let manifest_text = fs::read_to_string(artifact.join("GENERATED-OWNERSHIP.json"))
            .expect("ownership manifest text");
        let manifest_json: Value = serde_json::from_str(&manifest_text).expect("ownership json");
        let model_output = manifest_json
            .get("outputs")
            .and_then(Value::as_array)
            .and_then(|outputs| outputs.first())
            .expect("model output");
        assert_eq!(
            model_output.get("path").and_then(Value::as_str),
            Some("data/models/model.bin")
        );
        assert_eq!(
            model_output.get("integrity").and_then(Value::as_str),
            Some("metadata")
        );
        assert!(
            model_output
                .get("fingerprint")
                .and_then(Value::as_str)
                .is_some_and(|value| value.starts_with("metadata:"))
        );
        assert!(model_output.get("sha256").is_none());
        assert!(super::verify_generated_ownership_manifest(&artifact));
        let previous_outputs = super::read_generated_ownership_outputs(&artifact);
        let source_model = source.join("data/models/model.bin");
        let source_modified = UNIX_EPOCH + std::time::Duration::from_secs(1_700_000_000);
        fs::OpenOptions::new()
            .write(true)
            .open(&source_model)
            .expect("open source model")
            .set_times(fs::FileTimes::new().set_modified(source_modified))
            .expect("change source mtime");
        let before_modified = fs::metadata(artifact.join("data/models/model.bin"))
            .expect("artifact metadata")
            .modified()
            .expect("artifact mtime");
        let mut copied_files = 0;
        let mut copied_bytes = 0;
        super::copy_source_tree_to_artifact(
            &source,
            &artifact,
            &source,
            0,
            &previous_outputs,
            &mut copied_files,
            &mut copied_bytes,
        )
        .expect("incremental copy");
        let after_modified = fs::metadata(artifact.join("data/models/model.bin"))
            .expect("artifact metadata")
            .modified()
            .expect("artifact mtime");
        assert_ne!(before_modified, after_modified);
        assert_eq!(source_modified, after_modified);
        assert_eq!(copied_files, 1);
        assert_eq!(copied_bytes, model_bytes.len() as u64);
        fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Keeps small model manifests valid when a cached models archive preserves older timestamps.
    fn model_manifest_ownership_uses_content_digest() {
        let root = temp_root("model-manifest-ownership");
        let source = root.join("source");
        let artifact = root.join("artifact");
        fs::create_dir_all(&source).expect("source dir");
        fs::create_dir_all(artifact.join("data/models")).expect("model dir");
        let model_manifest = artifact.join("data/models/pdf-rasterizer-manifest.json");
        fs::write(&model_manifest, br#"{"schema":"pharos.pdf-rasterizer.v1"}"#)
            .expect("model manifest");
        fs::write(
            artifact.join("pharos.app.json"),
            serde_json::to_vec(&json!({"artifact": {"input_sha256": "input-digest"}})).unwrap(),
        )
        .expect("app manifest");
        super::write_generated_ownership_manifest(&artifact, &source, "input-digest")
            .expect("ownership manifest");
        let ownership: Value = serde_json::from_slice(
            &fs::read(artifact.join("GENERATED-OWNERSHIP.json")).expect("ownership file"),
        )
        .expect("ownership json");
        let output = ownership["outputs"]
            .as_array()
            .expect("outputs")
            .iter()
            .find(|value| value["path"] == "data/models/pdf-rasterizer-manifest.json")
            .expect("model manifest output");
        assert_eq!(output["integrity"], "sha256");
        fs::OpenOptions::new()
            .write(true)
            .open(&model_manifest)
            .expect("open model manifest")
            .set_times(
                fs::FileTimes::new().set_modified(UNIX_EPOCH + std::time::Duration::from_secs(1)),
            )
            .expect("change mtime");
        assert!(super::verify_generated_ownership_manifest(&artifact));
        fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Allows copied app source assets to be refreshed without weakening generated outputs.
    fn generated_ownership_accepts_refreshed_app_source_copy() {
        let suffix = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        let root = std::env::temp_dir().join(format!("pharos-ownership-test-{suffix}"));
        let source = root.join("source");
        let artifact = root.join("artifact");
        fs::create_dir_all(source.join("static/img")).expect("source dirs");
        fs::create_dir_all(&artifact).expect("artifact dir");
        fs::write(source.join("static/img/before-after.svg"), "old svg").expect("source svg");
        fs::create_dir_all(artifact.join("static/img")).expect("artifact img dir");
        fs::write(artifact.join("static/img/before-after.svg"), "old svg").expect("artifact svg");
        fs::write(artifact.join("generated.html"), "generated").expect("generated");
        fs::write(
            artifact.join("pharos.app.json"),
            serde_json::to_vec(&json!({"artifact": {"input_sha256": "source-digest"}})).unwrap(),
        )
        .expect("manifest");
        fs::write(
            artifact.join("GENERATED-OWNERSHIP.json"),
            serde_json::to_vec(&json!({
                "schema": "pharos.generated-ownership.v1",
                "source_owner": source.to_string_lossy(),
                "input_sha256": "source-digest",
                "outputs": [
                    {
                        "path": "static/img/before-after.svg",
                        "sha256": sha256_hex(b"old svg"),
                        "ownership": "app_source_copy"
                    },
                    {
                        "path": "generated.html",
                        "sha256": sha256_hex(b"generated"),
                        "ownership": "pharos_generated"
                    }
                ]
            }))
            .unwrap(),
        )
        .expect("ownership");

        fs::write(source.join("static/img/before-after.svg"), "new svg").expect("source changed");
        fs::write(artifact.join("static/img/before-after.svg"), "new svg")
            .expect("artifact changed");
        assert!(verify_generated_ownership_manifest(&artifact));

        fs::write(artifact.join("generated.html"), "changed generated").expect("generated changed");
        assert!(!verify_generated_ownership_manifest(&artifact));

        fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Preserves mutable runtime media separately from immutable media artifact paths.
    fn artifact_manifest_projects_runtime_media_boundary() {
        let root = temp_root("runtime-media-artifact");
        let manifest_path = root.join("pharos.app.json");
        let source_manifest = json!({
            "app_id": "media_app",
            "assets": {
                "static_dir": "static",
                "media_dir": "media",
                "runtime_media_dir": "/var/lib/pharos/media/media_app"
            }
        });

        super::finalize_artifact_manifest(
            &manifest_path,
            &source_manifest,
            "media_app",
            "input-digest",
        )
        .expect("finalized manifest");
        let artifact_manifest: Value =
            serde_json::from_str(&fs::read_to_string(&manifest_path).expect("artifact manifest"))
                .expect("artifact json");

        assert_eq!(
            artifact_manifest
                .get("assets")
                .and_then(Value::as_object)
                .and_then(|assets| assets.get("runtime_media_dir"))
                .and_then(Value::as_str),
            Some("/var/lib/pharos/media/media_app")
        );
        assert_eq!(
            artifact_manifest
                .get("artifact")
                .and_then(Value::as_object)
                .and_then(|artifact| artifact.get("media_dir"))
                .and_then(Value::as_str),
            Some("media")
        );
        assert_eq!(
            artifact_manifest
                .get("artifact")
                .and_then(Value::as_object)
                .and_then(|artifact| artifact.get("runtime_media_dir"))
                .and_then(Value::as_str),
            Some("/var/lib/pharos/media/media_app")
        );

        fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Includes common local Cargo install paths for docs Rustdoc generation.
    fn docs_cargo_candidates_include_common_local_install_paths() {
        let candidates = docs_cargo_executable_candidates()
            .into_iter()
            .map(|value| value.to_string_lossy().into_owned())
            .collect::<Vec<_>>();
        for cargo_path in ["/usr/local/bin/cargo", "/opt/homebrew/bin/cargo"] {
            if Path::new(cargo_path).is_file() {
                assert!(candidates.iter().any(|candidate| candidate == cargo_path));
            }
        }
    }

    #[test]
    /// Resolves a relative docs app root to the absolute repository root before spawning Cargo.
    fn docs_repo_root_from_relative_app_root_is_absolute() {
        let root = docs_repo_root(Path::new("apps/dev_docs")).expect("repo root");
        assert!(root.is_absolute());
        assert!(root.join("Cargo.toml").is_file());
        assert!(root.join("apps/dev_docs/pharos.app.yml").is_file());
    }

    #[test]
    /// Accepts Rustdoc fingerprint files written with a trailing newline.
    fn docs_rustdoc_fingerprint_match_trims_stored_value() {
        let root =
            std::env::temp_dir().join(format!("pharos-rustdoc-fingerprint-{}", std::process::id()));
        fs::create_dir_all(&root).expect("temp dir");
        let marker = root.join(".pharos-rustdoc-input.sha256");
        fs::write(&marker, "abc123\n").expect("marker");

        assert!(docs_rustdoc_fingerprint_matches(&marker, "abc123"));

        let _ = fs::remove_dir_all(root);
    }

    #[test]
    /// Restores a cached Rustdoc tree into a rebuilt docs app artifact.
    fn docs_rustdoc_cache_restore_copies_matching_tree() {
        let root =
            std::env::temp_dir().join(format!("pharos-rustdoc-cache-{}", std::process::id()));
        let fingerprint = "cache-digest";
        let cache_dir = docs_rustdoc_artifact_cache_dir(&root, fingerprint);
        fs::create_dir_all(cache_dir.join("pharos_native")).expect("cache dirs");
        fs::write(cache_dir.join("index.html"), "redirect").expect("cache index");
        fs::write(cache_dir.join("pharos_native/index.html"), "api").expect("cache api");
        fs::write(
            cache_dir.join(".pharos-rustdoc-input.sha256"),
            format!("{fingerprint}\n"),
        )
        .expect("cache marker");
        let artifact = root.join("artifact");
        fs::create_dir_all(&artifact).expect("artifact dir");
        let manifest = json!({
            "docs": {
                "rustdoc": {
                    "output_dir": "html"
                }
            }
        });

        assert_eq!(
            docs_restore_cached_rustdoc_artifact(&root, &artifact, &manifest, fingerprint),
            Ok(true)
        );
        assert_eq!(
            fs::read_to_string(artifact.join("html/pharos_native/index.html"))
                .expect("restored api"),
            "api"
        );

        let _ = fs::remove_dir_all(root);
    }

    #[test]
    /// Removes rebuilt app artifact files while preserving the Rustdoc output directory.
    fn remove_artifact_contents_except_keeps_preserved_rustdoc_tree() {
        let root =
            std::env::temp_dir().join(format!("pharos-rustdoc-preserve-{}", std::process::id()));
        let artifact = root.join("artifact");
        fs::create_dir_all(artifact.join("html/pharos_native")).expect("html dir");
        fs::create_dir_all(artifact.join("static")).expect("static dir");
        fs::write(artifact.join("html/index.html"), "rustdoc").expect("rustdoc index");
        fs::write(artifact.join("html/pharos_native/index.html"), "api").expect("api index");
        fs::write(artifact.join("static/docs.css"), "old css").expect("old css");
        fs::write(artifact.join("pharos.app.json"), "{}").expect("old manifest");

        remove_artifact_contents_except(&artifact, &artifact.join("html")).expect("clean");

        assert!(artifact.join("html/index.html").is_file());
        assert!(artifact.join("html/pharos_native/index.html").is_file());
        assert!(!artifact.join("static/docs.css").exists());
        assert!(!artifact.join("pharos.app.json").exists());

        let _ = fs::remove_dir_all(root);
    }

    #[test]
    /// Keeps docs shell asset paths manifest-owned and relative.
    fn docs_asset_paths_come_from_manifest() {
        let manifest = json!({
            "docs": {
                "wordmark_src": "static/img/custom-wordmark.svg",
                "favicon_src": "static/img/custom-favicon.ico",
                "stylesheet_src": "static/css/custom-docs.css",
                "rustdoc": {
                    "enabled": true
                }
            }
        });
        assert_eq!(
            docs_manifest_required_relative_path(&manifest, &["wordmark_src"], "wordmark_src")
                .as_deref(),
            Ok("static/img/custom-wordmark.svg")
        );
        assert_eq!(
            docs_manifest_required_relative_path(&manifest, &["favicon_src"], "favicon_src")
                .as_deref(),
            Ok("static/img/custom-favicon.ico")
        );
        assert_eq!(
            docs_manifest_required_relative_path(&manifest, &["stylesheet_src"], "stylesheet_src")
                .as_deref(),
            Ok("static/css/custom-docs.css")
        );
        assert_eq!(
            docs_manifest_bool_path(&manifest, &["rustdoc", "enabled"]),
            Some(true)
        );
    }

    #[test]
    /// Rejects docs asset paths that escape the app artifact tree.
    fn docs_asset_paths_reject_parent_traversal() {
        let manifest = json!({
            "docs": {
                "wordmark_src": "../outside.svg"
            }
        });
        assert!(
            docs_manifest_required_relative_path(&manifest, &["wordmark_src"], "wordmark_src")
                .is_err()
        );
    }

    #[test]
    /// Accepts only the supported declarative docs publish modes.
    fn docs_publish_mode_accepts_all_nav_only_and_routed_only() {
        assert_eq!(
            docs_manifest_publish_mode(&json!({"docs": {}})).unwrap(),
            "all"
        );
        assert_eq!(
            docs_manifest_publish_mode(&json!({"docs": {"publish_mode": "nav_only"}})).unwrap(),
            "nav_only"
        );
        assert_eq!(
            docs_manifest_publish_mode(&json!({"docs": {"publish_mode": "routed_only"}})).unwrap(),
            "routed_only"
        );
        assert!(docs_manifest_publish_mode(&json!({"docs": {"publish_mode": "invalid"}})).is_err());
    }

    #[test]
    /// Treats navigation paths as the published-output allowlist in nav_only mode.
    fn docs_nav_published_outputs_collects_paths() {
        let outputs = docs_nav_published_outputs(&[
            DocsNavEntry {
                path: "index.html".to_owned(),
                label: "Home".to_owned(),
                depth: 0,
            },
            DocsNavEntry {
                path: "reference/library-reference.html".to_owned(),
                label: "Reference".to_owned(),
                depth: 1,
            },
        ]);
        assert!(outputs.contains("index.html"));
        assert!(outputs.contains("reference/library-reference.html"));
        assert!(!outputs.contains("bill_of_materials.html"));
    }

    #[test]
    /// Treats declared page artifacts as the published-output allowlist in routed_only mode.
    fn docs_route_published_outputs_collects_declared_artifacts() {
        let root = std::env::temp_dir().join(format!("pharos-doc-routes-{}", std::process::id()));
        fs::create_dir_all(root.join("data/contracts")).expect("contracts dir");
        fs::write(
            root.join("data/contracts/routes.json"),
            r#"{"routes":[
                {"kind":"page","path":"/","artifact":"index.html"},
                {"kind":"page","path":"/reference/library-reference.html","artifact":"reference/library-reference.html"},
                {"kind":"page","path":"/html/index.html","artifact":"html/index.html"},
                {"kind":"action","path":"/actions/toggle","action_id":"toggle_task"}
            ]}"#,
        )
        .expect("routes");
        let outputs = docs_route_published_outputs(&root).expect("outputs");
        assert!(outputs.contains("index.html"));
        assert!(outputs.contains("reference/library-reference.html"));
        assert!(outputs.contains("html/index.html"));
        assert!(!outputs.contains("bill_of_materials.html"));
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    /// Resolves route method before declared kind so explicit GET actions remain routable.
    fn matched_app_route_finds_explicit_get_action_routes() {
        let route_id = ContractId::parse("payment_provider_callback_stripe").expect("route id");
        let mut routes = BTreeMap::new();
        routes.insert(
            route_id.clone(),
            RouteIr {
                id: route_id.clone(),
                path: "/businesses/:business_slug/payment-providers/stripe/callback/".to_owned(),
                kind: "action".to_owned(),
                method: "GET".to_owned(),
                action_id: Some(
                    ContractId::parse("payment_provider_callback_stripe").expect("action id"),
                ),
                page_id: None,
                policy_id: Some(
                    ContractId::parse("manage_payment_provider_connection").expect("policy id"),
                ),
                auth_gate: "anonymous_or_session".to_owned(),
                security: RouteSecurityPosture {
                    csrf_mode: "none".to_owned(),
                    trusted_origin_policy: "same-origin".to_owned(),
                    tenant_scope: "policy_bound".to_owned(),
                    rate_limit_policy: "default".to_owned(),
                    capability_policy: "policy_gate".to_owned(),
                },
                source: SourceProvenance {
                    path: PathBuf::from("data/contracts/routes.json"),
                    pointer: "/routes/0".to_owned(),
                    line: 1,
                    column: 1,
                },
                compatibility_view: json!({
                    "route_id": "payment_provider_callback_stripe",
                    "kind": "action",
                    "method": "GET",
                    "path": "/businesses/:business_slug/payment-providers/stripe/callback/",
                    "action_id": "payment_provider_callback_stripe"
                }),
            },
        );
        let mut route_buckets = BTreeMap::new();
        route_buckets.insert(("action".to_owned(), 5usize), vec![route_id]);
        let app = AppRuntime {
            application_ir: Some(Arc::new(ApplicationIr {
                version: APPLICATION_IR_VERSION,
                contract_digest: "test".to_owned(),
                app_id: ContractId::parse("ucal").expect("app id"),
                routes,
                route_buckets,
                actions: BTreeMap::new(),
                entities: BTreeSet::new(),
                forms: BTreeSet::new(),
                policies: BTreeSet::new(),
                role_capability_edges: BTreeSet::new(),
                workflows: BTreeSet::new(),
                integrations: BTreeSet::new(),
            })),
            ..AppRuntime::default()
        };

        let matched = matched_app_route(
            &app,
            "GET",
            "/businesses/lotus-studio/payment-providers/stripe/callback/",
        )
        .expect("matched route");

        assert_eq!(
            matched.get("action_id").and_then(Value::as_str),
            Some("payment_provider_callback_stripe")
        );
    }

    #[test]
    fn app_scope_path_prefixes_mounted_internal_redirects() {
        let app = AppRuntime {
            base_path: Some("/ucal".to_owned()),
            ..AppRuntime::default()
        };

        assert_eq!(
            app_scope_path(&app, "/businesses/lotus-studio/"),
            "/ucal/businesses/lotus-studio/"
        );
        assert_eq!(
            app_scope_path(&app, "/ucal/businesses/lotus-studio/"),
            "/ucal/businesses/lotus-studio/"
        );
        assert_eq!(app_scope_path(&app, "/"), "/ucal");
    }

    #[test]
    fn mounted_dynamic_feature_route_redirects_to_scoped_login() {
        let route_id = ContractId::parse("architect_home").expect("route id");
        let mut routes = BTreeMap::new();
        routes.insert(
            route_id.clone(),
            RouteIr {
                id: route_id.clone(),
                path: "/".to_owned(),
                kind: "page".to_owned(),
                method: "GET".to_owned(),
                action_id: None,
                page_id: Some(ContractId::parse("home").expect("page id")),
                policy_id: Some(ContractId::parse("review_builder_plan").expect("policy id")),
                auth_gate: "session_required".to_owned(),
                security: RouteSecurityPosture {
                    csrf_mode: "mutation_required".to_owned(),
                    trusted_origin_policy: "mutation_required".to_owned(),
                    tenant_scope: "policy_bound".to_owned(),
                    rate_limit_policy: "runtime_default".to_owned(),
                    capability_policy: "policy_gate".to_owned(),
                },
                source: SourceProvenance {
                    path: PathBuf::from("data/contracts/routes.json"),
                    pointer: "/routes/0".to_owned(),
                    line: 1,
                    column: 1,
                },
                compatibility_view: json!({
                    "route_id": "architect_home",
                    "path": "/",
                    "kind": "page",
                    "method": "GET",
                    "page_id": "home",
                    "feature_id": "architect_builder_console",
                    "auth_gate": "session_required",
                    "policy_gate": "review_builder_plan"
                }),
            },
        );
        let mut route_buckets = BTreeMap::new();
        route_buckets.insert(("page".to_owned(), 0usize), vec![route_id]);
        let app = AppRuntime {
            app_id: Some("architect".to_owned()),
            host_profile: Some("dynamic-app".to_owned()),
            base_path: Some("/architect".to_owned()),
            application_ir: Some(Arc::new(ApplicationIr {
                version: APPLICATION_IR_VERSION,
                contract_digest: "test".to_owned(),
                app_id: ContractId::parse("architect").expect("app id"),
                routes,
                route_buckets,
                actions: BTreeMap::new(),
                entities: BTreeSet::new(),
                forms: BTreeSet::new(),
                policies: BTreeSet::new(),
                role_capability_edges: BTreeSet::new(),
                workflows: BTreeSet::new(),
                integrations: BTreeSet::new(),
            })),
            ..AppRuntime::default()
        };

        let response =
            app_declarative_route_response(&app, &request("GET", "/architect/", "", None, ""))
                .expect("response");
        let text = String::from_utf8(response).expect("utf8 response");

        assert!(text.starts_with("HTTP/1.1 303 See Other\r\n"));
        assert!(text.contains("Location: /architect/accounts/login/?next=/\r\n"));
    }

    #[test]
    /// Serves mounted static-pages artifact routes directly from the built artifact tree.
    fn mounted_static_pages_artifact_routes_do_not_404() {
        let root = std::env::temp_dir().join(format!("pharos-static-pages-{}", std::process::id()));
        fs::create_dir_all(root.join("reference")).expect("create artifact reference dir");
        fs::write(
            root.join("reference/library-reference.html"),
            "<html><body>library reference</body></html>",
        )
        .expect("write artifact page");
        fs::write(
            root.join("runtime-route-map.tsv"),
            "GET\t/reference/library-reference.html\treference/library-reference.html\ttext/html; charset=utf-8\n",
        )
        .expect("write route map");
        let route_id = ContractId::parse("library_reference_route").expect("route id");
        let mut routes = BTreeMap::new();
        routes.insert(
            route_id.clone(),
            RouteIr {
                id: route_id.clone(),
                path: "/reference/library-reference.html".to_owned(),
                kind: "page".to_owned(),
                method: "GET".to_owned(),
                action_id: None,
                page_id: None,
                policy_id: None,
                auth_gate: "public".to_owned(),
                security: RouteSecurityPosture {
                    csrf_mode: "none".to_owned(),
                    trusted_origin_policy: "same-origin".to_owned(),
                    tenant_scope: "global".to_owned(),
                    rate_limit_policy: "default".to_owned(),
                    capability_policy: "public".to_owned(),
                },
                source: SourceProvenance {
                    path: PathBuf::from("data/contracts/routes.json"),
                    pointer: "/routes/0".to_owned(),
                    line: 1,
                    column: 1,
                },
                compatibility_view: json!({
                    "route_id": "library_reference_route",
                    "kind": "page",
                    "method": "GET",
                    "path": "/reference/library-reference.html",
                    "artifact": "reference/library-reference.html"
                }),
            },
        );
        let mut route_buckets = BTreeMap::new();
        route_buckets.insert(("page".to_owned(), 2usize), vec![route_id]);
        let app = AppRuntime {
            artifact_dir: Some(root.to_string_lossy().into_owned()),
            host_profile: Some("static-pages".to_owned()),
            base_path: Some("/dev_docs".to_owned()),
            application_ir: Some(Arc::new(ApplicationIr {
                version: APPLICATION_IR_VERSION,
                contract_digest: "test".to_owned(),
                app_id: ContractId::parse("dev_docs").expect("app id"),
                routes,
                route_buckets,
                actions: BTreeMap::new(),
                entities: BTreeSet::new(),
                forms: BTreeSet::new(),
                policies: BTreeSet::new(),
                role_capability_edges: BTreeSet::new(),
                workflows: BTreeSet::new(),
                integrations: BTreeSet::new(),
            })),
            ..AppRuntime::default()
        };
        let response = app_declarative_route_response(
            &app,
            &request(
                "GET",
                "/dev_docs/reference/library-reference.html",
                "",
                None,
                "",
            ),
        )
        .expect("response");
        let text = String::from_utf8(response).expect("utf8 response");
        assert!(text.starts_with("HTTP/1.1 200 OK\r\n"));
        assert!(text.contains("library reference"));
        let _ = fs::remove_dir_all(root);
    }

    /// Confirms session digests are unique per secret and bound to the owning application.
    #[test]
    fn session_tokens_are_isolated_by_secret_and_application() {
        let app_a = AppRuntime {
            app_id: Some("app-a".to_owned()),
            ..AppRuntime::default()
        };
        let app_b = AppRuntime {
            app_id: Some("app-b".to_owned()),
            ..AppRuntime::default()
        };
        let first = native_session_token_hash(&app_a, "first-secret").expect("first digest");
        let second = native_session_token_hash(&app_a, "second-secret").expect("second digest");
        let other_app = native_session_token_hash(&app_b, "first-secret").expect("other digest");
        assert_ne!(first, second);
        assert_ne!(first, other_app);
    }

    /// Confirms the state-backed admission window rejects requests beyond its declared maximum.
    #[test]
    fn route_rate_limit_enforces_the_declared_window() {
        let root = std::env::temp_dir().join(format!("pharos-rate-limit-{}", std::process::id()));
        fs::create_dir_all(&root).expect("create rate-limit test root");
        let state_path = root.join("state.json");
        fs::write(&state_path, "{}\n").expect("write rate-limit state");
        let app = AppRuntime {
            state_path: Some(state_path.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        assert_eq!(
            dynamic::admit_rate_limited_request_runtime_local(
                &app,
                "runtime_default:test",
                "actor:1",
                2,
                60,
            ),
            Ok(true)
        );
        assert_eq!(
            dynamic::admit_rate_limited_request_runtime_local(
                &app,
                "runtime_default:test",
                "actor:1",
                2,
                60,
            ),
            Ok(true)
        );
        assert_eq!(
            dynamic::admit_rate_limited_request_runtime_local(
                &app,
                "runtime_default:test",
                "actor:1",
                2,
                60,
            ),
            Ok(false)
        );
        let bounded_app = AppRuntime {
            resource_budgets: pharos_runtime_core::config::ResourceBudgets {
                max_state_section_items: 2,
                ..Default::default()
            },
            ..app.clone()
        };
        assert_eq!(
            dynamic::admit_rate_limited_request_runtime_local(
                &bounded_app,
                "runtime_default:other",
                "actor:2",
                3,
                60,
            ),
            Err(69)
        );
        fs::remove_dir_all(root).expect("remove rate-limit test root");
    }

    /// Storage failure classes reach HTTP without denial, credential or driver-detail substitution.
    #[test]
    fn database_failures_keep_distinct_http_statuses() {
        use pharos_runtime_database::operations::DatabaseError;
        for (error, status) in [
            (DatabaseError::AccessDenied, 403),
            (DatabaseError::Conflict, 409),
            (DatabaseError::InvalidContract, 422),
            (DatabaseError::MissingRecord, 404),
            (DatabaseError::CapacityExceeded, 503),
            (DatabaseError::StorageFailure, 503),
            (DatabaseError::Unavailable, 503),
        ] {
            let response = String::from_utf8(super::database_error_response(error)).unwrap();
            assert!(response.starts_with(&format!("HTTP/1.1 {status} ")));
            let body = response.split("\r\n\r\n").nth(1).unwrap();
            let body: Value = serde_json::from_str(body).unwrap();
            assert_eq!(body["schema"], "pharos.error.v1");
            assert!(body["error"].get("details").is_none());
        }
    }

    /// Confirms legacy and validation JSON failures are normalized without losing safe details.
    #[test]
    fn json_failures_use_the_stable_error_envelope() {
        let legacy = canonical_http_error_body(
            403,
            "Forbidden",
            r#"{"error_code":"capability_denied","message":"capability denied"}"#,
        );
        let parsed: serde_json::Value = serde_json::from_str(&legacy).expect("legacy envelope");
        assert_eq!(parsed["schema"], "pharos.error.v1");
        assert_eq!(parsed["error"]["code"], "access_denied");
        assert_eq!(parsed["error"]["message"], "capability denied");
        assert!(parsed["error"].get("details").is_none());

        let validation = canonical_http_error_body(
            422,
            "Unprocessable Entity",
            r#"{"schema":"pharos.validation.report.v1","errors":["field_required"]}"#,
        );
        let parsed: serde_json::Value =
            serde_json::from_str(&validation).expect("validation envelope");
        assert_eq!(parsed["schema"], "pharos.error.v1");
        assert_eq!(parsed["error"]["code"], "invalid_input");
        assert_eq!(
            parsed["error"]["details"]["schema"],
            "pharos.validation.report.v1"
        );
        assert_eq!(parsed["error"]["details"]["errors"][0], "field_required");

        let validation = canonical_http_error_body(
            422,
            "Unprocessable Entity",
            r#"{"schema":"pharos.validation.report.v1","errors":["missing_required_field"],"field_errors":[{"field_id":"title","code":"missing_required_field","message":"A required field was not provided.","submitted_value":"private input"}]}"#,
        );
        let parsed: serde_json::Value = serde_json::from_str(&validation).unwrap();
        assert_eq!(
            parsed["error"]["message"],
            "title: A required field was not provided."
        );
        assert_eq!(
            parsed["error"]["details"]["field_errors"][0]["code"],
            "missing_required_field"
        );
        assert!(!validation.contains("private input"));
    }

    /// Ignores foreign cookies only when session storage is absent from the logical contract.
    #[test]
    fn public_generated_app_ignores_foreign_cookie_without_hiding_declared_storage_errors() {
        use pharos_runtime_database::contract::{AppDataContract, migration_checksum};
        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp")
            .join(format!("session-schema-boundary-{}", std::process::id()));
        let app_root = root.join("app");
        fs::create_dir_all(app_root.join("data/contracts")).expect("app contracts");
        fs::write(
            app_root.join("pharos.app.yml"),
            "app_id: cookie_app\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        )
        .unwrap();
        let contract_path = app_root.join("data/contracts/database.json");
        fs::write(
            &contract_path,
            pharos_runtime_architect::generated_database::record_contract(
                "cookie_app",
                "entry",
                &["id", "title", "note", "created_at"].map(str::to_owned),
                "Cookie App",
            )
            .unwrap(),
        )
        .unwrap();
        let config = root.join("runtime.conf");
        let data = root.join("uninitialized.sqlite3");
        fs::write(
            &config,
            format!("db_backend=sqlite\ndb_path={}\n", data.display()),
        )
        .unwrap();
        let app = AppRuntime {
            app_id: Some("cookie_app".to_owned()),
            host_profile: Some("dynamic-app".to_owned()),
            app_root: Some(app_root.to_string_lossy().into_owned()),
            runtime_conf_path: Some(config.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        let cookie = Some("pharos_session=unrelated_architect_session");
        assert_eq!(active_session_user_id(&app, cookie), Ok(0));
        assert!(
            !data.exists(),
            "no session declaration must not open storage"
        );
        let repo = Path::new(env!("CARGO_MANIFEST_DIR"));
        let mut declared: AppDataContract = pharos_runtime_compiler::database::load_source(
            &repo.join("apps/architect/data/contracts/database.yml"),
            "architect",
        )
        .unwrap();
        declared.schema.app_id = "cookie_app".to_owned();
        declared.legacy_adoption = None;
        for migration in &mut declared.migrations {
            migration.app_id = "cookie_app".to_owned();
            migration.checksum =
                migration_checksum(&migration.app_id, &migration.id, &migration.changes).unwrap();
        }
        fs::write(contract_path, serde_json::to_vec(&declared).unwrap()).unwrap();
        assert!(
            active_session_user_id(&app, cookie).is_err(),
            "declared but missing session storage must fail explicitly"
        );
        fs::remove_dir_all(root).unwrap();
    }

    /// Confirms concurrent users remain isolated and sessions cannot cross applications.
    #[test]
    fn session_lookup_rejects_cross_application_substitution() {
        let root = std::env::temp_dir().join(format!("pharos-session-{}", std::process::id()));
        fs::create_dir_all(&root).expect("create session test root");
        let state_path = root.join("state.json");
        let app_a = AppRuntime {
            app_id: Some("app-a".to_owned()),
            state_path: Some(state_path.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        let app_b = AppRuntime {
            app_id: Some("app-b".to_owned()),
            state_path: app_a.state_path.clone(),
            ..AppRuntime::default()
        };
        let first_token = "first-unique-session-secret";
        let second_token = "second-unique-session-secret";
        let first_digest =
            native_session_token_hash(&app_a, first_token).expect("first session digest");
        let second_digest =
            native_session_token_hash(&app_a, second_token).expect("second session digest");
        fs::write(
            &state_path,
            serde_json::json!({"sessions":[
                {
                    "session_token_hash": first_digest,
                    "app_id": "app-a",
                    "user_id": 7,
                    "expires_at": "9999999999",
                    "revoked_at": null
                },
                {
                    "session_token_hash": second_digest,
                    "app_id": "app-a",
                    "user_id": 8,
                    "expires_at": "9999999999",
                    "revoked_at": null
                }
            ]})
            .to_string(),
        )
        .expect("write session state");
        let first_app = app_a.clone();
        let second_app = app_a.clone();
        let first_lookup = std::thread::spawn(move || {
            active_session_user_id(&first_app, Some(&format!("pharos_session={first_token}")))
                .expect("security operation")
        });
        let second_lookup = std::thread::spawn(move || {
            active_session_user_id(&second_app, Some(&format!("pharos_session={second_token}")))
                .expect("security operation")
        });
        assert_eq!(first_lookup.join().expect("first session lookup"), 7);
        assert_eq!(second_lookup.join().expect("second session lookup"), 8);
        assert_eq!(
            active_session_user_id(&app_b, Some(&format!("pharos_session={first_token}")))
                .expect("security operation"),
            0
        );
        fs::remove_dir_all(root).expect("remove session test root");
    }

    #[test]
    /// Performs relational login and logout skip state mutation lock.
    fn relational_login_and_logout_skip_state_mutation_lock() {
        let root =
            std::env::temp_dir().join(format!("pharos-relational-login-{}", std::process::id()));
        fs::create_dir_all(&root).expect("create relational login test root");
        let app_root = root.join("app");
        fs::create_dir_all(app_root.join("data/contracts")).expect("create app contracts");
        let runtime_conf = root.join("runtime.conf");
        let state_path = root.join("state.json");
        fs::write(
            app_root.join("pharos.app.yml"),
            "database:\n  migration_contract: data/contracts/migrations.yml\npayments:\n  provider_management:\n    supported_providers:\n      - provider: stripe\n        callback_action_id: payment_provider_callback_stripe\n",
        )
        .expect("write app manifest");
        fs::write(
            app_root.join("data/contracts/migrations.yml"),
            "state_cutover_mode: relational_runtime_authority\n",
        )
        .expect("write migration contract");
        fs::write(&runtime_conf, "db_backend=sqlite\n").expect("write runtime conf");
        fs::write(&state_path, "{}\n").expect("write state");

        let app = AppRuntime {
            app_root: Some(app_root.to_string_lossy().into_owned()),
            runtime_conf_path: Some(runtime_conf.to_string_lossy().into_owned()),
            state_path: Some(state_path.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };

        let login_route = serde_json::json!({ "action_id": "login" });
        let logout_route = serde_json::json!({ "action_id": "logout" });
        let other_route = serde_json::json!({ "action_id": "update_profile" });

        assert!(!route_requires_state_mutation_guard(
            &app,
            "POST",
            Some(&login_route)
        ));
        assert!(!route_requires_state_mutation_guard(
            &app,
            "POST",
            Some(&logout_route)
        ));
        assert!(!route_requires_state_mutation_guard(
            &app,
            "POST",
            Some(&other_route)
        ));
        let feature_route = serde_json::json!({
            "feature_id": "records",
            "action_id": "create_record"
        });
        assert!(!route_requires_state_mutation_guard(
            &app,
            "POST",
            Some(&feature_route)
        ));
        let callback_route = serde_json::json!({
            "action_id": "payment_provider_callback_stripe"
        });
        assert!(!route_requires_state_mutation_guard(
            &app,
            "GET",
            Some(&callback_route)
        ));
        assert!(actor_owns_mutation_resource(&app, "/businesses/other/edit/", 10).is_err());
        assert!(actor_owns_mutation_resource(&app, "/appointments/27/cancel/", 10).is_err());
        assert!(
            actor_owns_mutation_resource(&app, "/businesses/new/", 10)
                .expect("ownership operation")
        );

        let file_backed_app_root = root.join("file_app");
        fs::create_dir_all(&file_backed_app_root).expect("create file-backed app root");
        fs::write(
            file_backed_app_root.join("pharos.app.yml"),
            "app_id: file_app
",
        )
        .expect("write file-backed manifest");
        let file_backed_app = AppRuntime {
            app_root: Some(file_backed_app_root.to_string_lossy().into_owned()),
            runtime_conf_path: Some(runtime_conf.to_string_lossy().into_owned()),
            state_path: Some(state_path.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        assert!(route_requires_state_mutation_guard(
            &file_backed_app,
            "POST",
            Some(&feature_route)
        ));
        fs::write(&runtime_conf, "db_backend=unknown\n").expect("invalidate backend config");
        assert_eq!(super::runtime_default_backend(&app), "unknown");
        assert_eq!(super::db_check_json(&app, "unknown")["status"], "invalid");
        assert_eq!(
            super::app_runtime_backend_summary_value(&app)["db_ready"],
            false
        );
        assert!(app_uses_relational_runtime_authority(&app));
        assert!(!app_uses_file_backed_runtime_state(&app));
        fs::remove_file(app_root.join("data/contracts/migrations.yml"))
            .expect("remove declared contract to exercise missing-file rejection");
        assert!(app_uses_relational_runtime_authority(&app));
        assert!(!app_uses_file_backed_runtime_state(&app));
        assert!(actor_owns_mutation_resource(&app, "/businesses/other/edit/", 10).is_err());

        fs::remove_dir_all(root).expect("remove relational login test root");
    }

    /// Confirms business identifiers cannot be substituted across owners.
    #[test]
    fn mutation_resource_ownership_rejects_cross_tenant_identifier() {
        let root = std::env::temp_dir().join(format!("pharos-owner-{}", std::process::id()));
        fs::create_dir_all(&root).expect("create owner test root");
        let state_path = root.join("state.json");
        fs::write(
            &state_path,
            serde_json::json!({"businesses":[
                {"id": 1, "slug": "owned", "owner_user_id": 10},
                {"id": 2, "slug": "other", "owner_user_id": 20}
            ]})
            .to_string(),
        )
        .expect("write owner state");
        let app = AppRuntime {
            state_path: Some(state_path.to_string_lossy().into_owned()),
            ..AppRuntime::default()
        };
        assert!(
            actor_owns_mutation_resource(&app, "/businesses/owned/edit/", 10)
                .expect("ownership operation")
        );
        assert!(
            !actor_owns_mutation_resource(&app, "/businesses/other/edit/", 10)
                .expect("ownership operation")
        );
        assert!(
            actor_owns_mutation_resource(&app, "/businesses/new/", 10)
                .expect("ownership operation")
        );
        fs::remove_dir_all(root).expect("remove owner test root");
    }

    /// Confirms booking times use the relational schema's canonical 24-hour representation.
    #[test]
    fn booking_time_normalization_rejects_invalid_and_converts_meridiem() {
        assert_eq!(
            normalized_booking_time("", "12", "00", "AM").as_deref(),
            Some("00:00")
        );
        assert_eq!(
            normalized_booking_time("", "12", "05", "PM").as_deref(),
            Some("12:05")
        );
        assert_eq!(
            normalized_booking_time("", "01", "30", "pm").as_deref(),
            Some("13:30")
        );
        assert_eq!(
            normalized_booking_time("9:07", "", "", "").as_deref(),
            Some("09:07")
        );
        assert!(normalized_booking_time("", "00", "00", "AM").is_none());
        assert!(normalized_booking_time("", "11", "60", "AM").is_none());
        assert!(normalized_booking_time("", "11", "00", "noon").is_none());
    }

    /// Confirms queued-job timing accepts both epoch strings and exported UTC timestamps.
    #[test]
    fn runtime_timestamp_seconds_accepts_epoch_and_utc_text() {
        assert_eq!(runtime_timestamp_seconds("1724976000"), Some(1_724_976_000));
        assert_eq!(
            runtime_timestamp_seconds("2026-08-30T00:00:00Z"),
            Some(1_788_048_000)
        );
        assert_eq!(
            runtime_timestamp_seconds("2026-08-30 00:00:00"),
            Some(1_788_048_000)
        );
        assert_eq!(runtime_timestamp_seconds(""), None);
        assert_eq!(runtime_timestamp_seconds("not-a-time"), None);
    }

    #[test]
    /// Performs artifact tree digest ignores ds store noise.
    fn artifact_tree_digest_ignores_ds_store_noise() {
        let root =
            std::env::temp_dir().join(format!("pharos-artifact-noise-{}", std::process::id()));
        if root.exists() {
            fs::remove_dir_all(&root).expect("clear prior artifact-noise root");
        }
        fs::create_dir_all(root.join("templates")).expect("create artifact-noise root");
        fs::write(root.join("pharos.app.json"), "{}\n").expect("write manifest");
        fs::write(root.join("templates/layout.html"), "<body></body>\n").expect("write layout");
        let digest_without_noise =
            tree_content_digest(&root, None).expect("digest without ds_store");
        fs::write(root.join(".DS_Store"), "finder-noise\n").expect("write root ds_store");
        fs::write(root.join("templates/.DS_Store"), "nested-finder-noise\n")
            .expect("write nested ds_store");
        let digest_with_noise = tree_content_digest(&root, None).expect("digest with ds_store");
        assert_eq!(digest_without_noise, digest_with_noise);
        assert!(ignore_non_contract_artifact_entry(".DS_Store"));
        assert!(!ignore_non_contract_artifact_entry(".gitkeep"));
        fs::remove_dir_all(root).expect("remove artifact-noise root");
    }

    #[test]
    /// Performs route request middleware returns structured validation report.
    fn route_request_middleware_returns_structured_validation_report() {
        let route = serde_json::json!({
            "path": "/middleware/proof/",
            "middleware": [{
                "phase": "request",
                "kind": "require_header",
                "header": "X-Pharos-Proof",
                "equals": "state-open",
                "status_code": 428,
                "error_code": "middleware_header_required",
                "message": "This route requires X-Pharos-Proof: state-open."
            }]
        });
        let request = request("GET", "/middleware/proof/", "", None, "");
        let failure =
            route_request_middleware_failure(&route, &request).expect("middleware failure");
        assert_eq!(failure.0, 428);
        let report: serde_json::Value =
            serde_json::from_str(&failure.2).expect("middleware validation report");
        assert_eq!(report["schema"], "pharos.validation.report.v1");
        assert_eq!(
            report["form_errors"][0]["code"],
            "middleware_header_required"
        );
        assert_eq!(
            report["form_errors"][0]["message"],
            "This route requires X-Pharos-Proof: state-open."
        );
    }

    #[test]
    /// Performs route request hook rejects non form body when form is required.
    fn route_request_hook_rejects_non_form_body_when_form_is_required() {
        let route = serde_json::json!({
            "path": "/snapshots/purge",
            "request_hooks": ["form_body_required"]
        });
        let request = request(
            "POST",
            "/snapshots/purge",
            "",
            Some("application/json"),
            r#"{"board_id":4}"#,
        );
        let failure = route_request_hook_failure(&route, &request).expect("form hook failure");
        assert_eq!(failure.0, 415);
        let report: serde_json::Value =
            serde_json::from_str(&failure.2).expect("hook validation report");
        assert_eq!(
            report["form_errors"][0]["code"],
            "form_content_type_required"
        );
    }

    #[test]
    /// Performs route response middleware sets and mirrors headers.
    fn route_response_middleware_sets_and_mirrors_headers() {
        let route = serde_json::json!({
            "middleware": [
                {
                    "phase": "response",
                    "kind": "set_header",
                    "name": "X-Pharos-Route-Middleware",
                    "value": "state_api_active"
                },
                {
                    "phase": "response",
                    "kind": "mirror_request_header",
                    "name": "X-Pharos-Proof-Echo",
                    "from_request_header": "X-Pharos-Proof",
                    "default_value": "missing"
                },
                {
                    "phase": "response",
                    "kind": "mirror_query_param",
                    "name": "X-Pharos-Proof-Query",
                    "from_query_param": "proof",
                    "default_value": "missing"
                }
            ]
        });
        let request = request(
            "GET",
            "/middleware/query-proof?proof=open",
            "X-Pharos-Proof: state-open\r\n",
            None,
            "",
        );
        let response = apply_route_response_middleware(
            &route,
            &request,
            b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n".to_vec(),
        );
        let response_text = String::from_utf8(response).expect("response text");
        assert!(response_text.contains("X-Pharos-Route-Middleware: state_api_active\r\n"));
        assert!(response_text.contains("X-Pharos-Proof-Echo: state-open\r\n"));
        assert!(response_text.contains("X-Pharos-Proof-Query: open\r\n"));
    }

    #[test]
    /// Performs background job emits started and retried lifecycle payloads.
    fn background_job_emits_started_and_retried_lifecycle_payloads() {
        let root = std::env::temp_dir().join(format!("pharos-job-events-{}", std::process::id()));
        if root.exists() {
            fs::remove_dir_all(&root).expect("clear prior job-events root");
        }
        fs::create_dir_all(&root).expect("create job-events root");
        let state_path = root.join("runtime-state.json");
        fs::write(
            &state_path,
            serde_json::json!({
                "job_executions": [{
                    "id": 1,
                    "workflow_execution_id": 7,
                    "queue_name": "proving",
                    "job_id": "simulate-failure",
                    "handler_id": "simulate_failure",
                    "execution_status": "queued",
                    "attempt_count": 0,
                    "max_attempts": 3,
                    "backoff_seconds": 5,
                    "lease_seconds": 30,
                    "available_at": "0"
                }],
                "job_execution_attempts": [],
                "workflow_execution_events": []
            })
            .to_string(),
        )
        .expect("write job state");
        let app = AppRuntime {
            app_id: Some("ucal".to_owned()),
            state_path: Some(state_path.to_string_lossy().into_owned()),
            queue_enabled: true,
            queue_max_attempts: 3,
            queue_retry_seconds: 5,
            ..AppRuntime::default()
        };
        process_one_background_job(&app);
        let state: serde_json::Value =
            serde_json::from_str(&fs::read_to_string(&state_path).expect("read state"))
                .expect("parse state");
        assert_eq!(
            state["job_execution_attempts"]
                .as_array()
                .expect("attempt rows")
                .len(),
            1
        );
        let events = state["workflow_execution_events"]
            .as_array()
            .expect("workflow events");
        assert_eq!(events.len(), 2);
        assert_eq!(events[0]["event_kind"], "job_started");
        assert_eq!(events[1]["event_kind"], "job_retried");
        let started_payload: serde_json::Value =
            serde_json::from_str(events[0]["payload_json"].as_str().expect("started payload"))
                .expect("parse started payload");
        let retried_payload: serde_json::Value =
            serde_json::from_str(events[1]["payload_json"].as_str().expect("retried payload"))
                .expect("parse retried payload");
        assert_eq!(started_payload["queue_name"], "proving");
        assert_eq!(started_payload["attempt_number"], 1);
        assert_eq!(started_payload["lease_seconds"], 30);
        assert_eq!(started_payload["backoff_seconds"], 5);
        assert_eq!(retried_payload["execution_status"], "queued");
        assert_eq!(retried_payload["queue_name"], "proving");
        assert_eq!(retried_payload["attempt_number"], 1);
        fs::remove_dir_all(root).expect("remove job-events root");
    }

    #[test]
    fn ucal_payment_provider_connect_route_matches_post() {
        let route_id = ContractId::parse("payment_provider_connect_stripe").expect("route id");
        let mut routes = BTreeMap::new();
        routes.insert(
            route_id.clone(),
            RouteIr {
                id: route_id.clone(),
                path: "/businesses/:business_slug/payment-providers/stripe/connect/".to_owned(),
                kind: "action".to_owned(),
                method: "POST".to_owned(),
                action_id: Some(
                    ContractId::parse("payment_provider_connect_stripe").expect("action id"),
                ),
                page_id: None,
                policy_id: Some(
                    ContractId::parse("manage_payment_provider_connection").expect("policy id"),
                ),
                auth_gate: "session".to_owned(),
                security: RouteSecurityPosture {
                    csrf_mode: "required".to_owned(),
                    trusted_origin_policy: "same-origin".to_owned(),
                    tenant_scope: "policy_bound".to_owned(),
                    rate_limit_policy: "default".to_owned(),
                    capability_policy: "policy_gate".to_owned(),
                },
                source: SourceProvenance {
                    path: PathBuf::from("data/contracts/routes.json"),
                    pointer: "/routes/0".to_owned(),
                    line: 1,
                    column: 1,
                },
                compatibility_view: json!({
                    "route_id": "payment_provider_connect_stripe",
                    "kind": "action",
                    "method": "POST",
                    "path": "/businesses/:business_slug/payment-providers/stripe/connect/",
                    "action_id": "payment_provider_connect_stripe"
                }),
            },
        );
        let mut route_buckets = BTreeMap::new();
        route_buckets.insert(("action".to_owned(), 5usize), vec![route_id]);
        let app = AppRuntime {
            application_ir: Some(Arc::new(ApplicationIr {
                version: APPLICATION_IR_VERSION,
                contract_digest: "test".to_owned(),
                app_id: ContractId::parse("ucal").expect("app id"),
                routes,
                route_buckets,
                actions: BTreeMap::new(),
                entities: BTreeSet::new(),
                forms: BTreeSet::new(),
                policies: BTreeSet::new(),
                role_capability_edges: BTreeSet::new(),
                workflows: BTreeSet::new(),
                integrations: BTreeSet::new(),
            })),
            ..AppRuntime::default()
        };
        assert_eq!(
            matched_app_route(
                &app,
                "POST",
                "/businesses/lotus-studio/payment-providers/stripe/connect/",
            )
            .and_then(|route| route
                .get("action_id")
                .and_then(Value::as_str)
                .map(str::to_owned))
            .as_deref(),
            Some("payment_provider_connect_stripe")
        );
    }
    /// Expands only successful Architect archive downloads, preserving ordinary and error response limits.
    #[test]
    fn source_export_responses_have_a_scoped_archive_budget() {
        let app = AppRuntime {
            app_id: Some("architect".into()),
            ..AppRuntime::default()
        };
        let ordinary = app.resource_budgets.max_response_bytes;
        let archive =
            super::http_download_response(b"source", "application/x-tar", "source.tar", "GET");
        assert!(
            super::app_response_body_budget(&app, "/exports/download", "GET", &archive) > ordinary
        );
        assert_eq!(
            super::app_response_body_budget(&app, "/other", "GET", &archive),
            ordinary
        );
        assert_eq!(
            super::app_response_body_budget(&app, "/exports/download", "POST", &archive),
            ordinary
        );
        assert_eq!(
            super::app_response_body_budget(
                &app,
                "/exports/download",
                "GET",
                &super::http_text_response(500, "Internal Server Error", "failed")
            ),
            ordinary
        );
        let other = AppRuntime {
            app_id: Some("ucal".into()),
            ..AppRuntime::default()
        };
        assert_eq!(
            super::app_response_body_budget(&other, "/exports/download", "GET", &archive),
            ordinary
        );
    }
}