pharos_native/runtime/

architect_http.rs

//! Architect HTTP request, preview, editor, and export handlers.

use super::*;
use pharos_runtime_architect::AgentErrorKind;

pub(super) fn architect_state_parent(app: &AppRuntime) -> Option<PathBuf> {
    app.state_path
        .as_deref()
        .map(Path::new)
        .and_then(Path::parent)
        .map(Path::to_path_buf)
}

/// Resolves Architect attachments and preview images through its independent media configuration.
fn architect_media_root(app: &AppRuntime) -> Option<PathBuf> {
    let app_root = app.app_root.as_deref().map(Path::new)?;
    if config::dynamic_config_effective_value(app_root, None, "MEDIA_ROOT").is_some() {
        config::app_media_root(app_root)
    } else {
        architect_state_parent(app).map(|parent| parent.join("media/architect"))
    }
}

pub(super) fn architect_vault_paths(app: &AppRuntime) -> Option<(PathBuf, PathBuf)> {
    let state_parent = architect_state_parent(app)?;
    let vault_dir = state_parent.join("vault");
    Some((
        vault_dir.join("architect-llm-vendor-secrets.enc"),
        vault_dir.join("architect-root.key"),
    ))
}

pub(super) fn architect_generated_source_root(app: &AppRuntime) -> Option<PathBuf> {
    let app_root = app.app_root.as_deref().map(Path::new)?;
    let runtime_conf = app.runtime_conf_path.as_deref().map(Path::new);
    config::dynamic_config_effective_value(
        app_root,
        runtime_conf,
        "architect_generated_source_root",
    )
    .map(PathBuf::from)
    .or_else(|| architect_state_parent(app).map(|state_parent| state_parent.join("generated")))
}

pub(super) fn architect_import_source_app_roots(app: &AppRuntime) -> Vec<PathBuf> {
    let mut roots = Vec::new();
    let mut push_root = |path: PathBuf| {
        if !path.as_os_str().is_empty() && !roots.iter().any(|existing| existing == &path) {
            roots.push(path);
        }
    };
    if let Some(app_root) = app.app_root.as_deref().map(Path::new)
        && let Some(parent) = app_root.parent()
    {
        push_root(parent.to_path_buf());
    }
    if let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new)
        && let Some(parent) = artifact_root.parent()
    {
        push_root(parent.to_path_buf());
    }
    if let Ok(cwd) = std::env::current_dir() {
        push_root(cwd.join("apps"));
        push_root(cwd.join("..").join("apps"));
    }
    roots
}

pub(super) fn ensure_architect_root_key(root_key_file: &Path) -> Result<(), i32> {
    let Some(parent) = root_key_file.parent() else {
        return Err(69);
    };
    stdfs::create_dir_all(parent).map_err(|_| 69)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        stdfs::set_permissions(parent, stdfs::Permissions::from_mode(0o700)).map_err(|_| 69)?;
    }
    if let Ok(metadata) = stdfs::symlink_metadata(root_key_file) {
        return if metadata.is_file()
            && !metadata.file_type().is_symlink()
            && (32..=4096).contains(&metadata.len())
        {
            Ok(())
        } else {
            Err(69)
        };
    }
    let root_key = dynamic::random_secret_hex(32).map_err(|_| 69)?;
    let mut options = stdfs::OpenOptions::new();
    options.write(true).create_new(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.mode(0o600);
    }
    let mut file = options.open(root_key_file).map_err(|_| 69)?;
    std::io::Write::write_all(&mut file, root_key.as_bytes()).map_err(|_| 69)?;
    file.sync_all().map_err(|_| 69)
}

fn request_query_value(target: &str, field: &str) -> Option<String> {
    let query = target.split_once('?')?.1;
    json_commands::request_form_value(query, field)
}

fn architect_fragment_html(
    app: &AppRuntime,
    relative_path: &str,
    params: &Value,
) -> Option<String> {
    let artifact_root = app.artifact_dir.as_deref().map(Path::new)?;
    json_commands::template_render_file(&artifact_root.join(relative_path), params)
}

pub(super) fn architect_attachment_media_type(filename: &str, supplied: Option<String>) -> String {
    let inferred = match filename
        .to_ascii_lowercase()
        .rsplit('.')
        .next()
        .unwrap_or_default()
    {
        "css" => Some("text/css"),
        "html" | "htm" => Some("text/html"),
        "svg" => Some("image/svg+xml"),
        "woff" => Some("font/woff"),
        "woff2" => Some("font/woff2"),
        "ttf" => Some("font/ttf"),
        "otf" => Some("font/otf"),
        "txt" | "md" => Some("text/plain"),
        "json" => Some("application/json"),
        "yml" | "yaml" => Some("application/yaml"),
        "toml" => Some("application/toml"),
        "sql" => Some("application/sql"),
        "js" => Some("application/javascript"),
        "zip" => Some("application/zip"),
        "docx" => Some("application/vnd.openxmlformats-officedocument.wordprocessingml.document"),
        _ => None,
    };
    inferred
        .map(str::to_owned)
        .or(supplied.filter(|value| value.len() <= 120 && !value.contains(['\r', '\n'])))
        .unwrap_or_else(|| "application/octet-stream".to_owned())
}

/// Forwards bounded app filters while retaining Architect preview selection as outer routing authority.
fn architect_preview_query_target(route: &str, outer: &str) -> Option<String> {
    if route.len() > 16 * 1024
        || outer.len() > 16 * 1024
        || route.contains(['\0', '\r', '\n'])
        || outer.contains(['\0', '\r', '\n'])
    {
        return None;
    }
    let mut target = route.to_owned();
    let mut count = 0;
    for pair in outer
        .split_once('?')
        .map(|(_, query)| query)
        .unwrap_or("")
        .split('&')
        .filter(|pair| !pair.is_empty())
    {
        let key = json_commands::url_decode(pair.split('=').next()?)?;
        if matches!(key.as_str(), "task_id" | "app_id" | "path") {
            continue;
        }
        count += 1;
        if count > 64 {
            return None;
        }
        target.push(if target.contains('?') { '&' } else { '?' });
        target.push_str(pair);
        if target.len() > 16 * 1024 {
            return None;
        }
    }
    Some(target)
}

pub(super) fn architect_task_console_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    let task_route = matched_app_route(app, "GET", "/tasks/status").unwrap_or_else(|| {
        serde_json::json!({
            "page_id": "task_status",
            "feature_id": "architect_builder_console",
            "template": "templates/fragments/task_console.html",
            "queries": ["recent_tasks", "recent_events"]
        })
    });
    let body = match feature_runtime::render_feature_page_body(
        app,
        &task_route,
        "/tasks/status",
        match active_session_user_id(app, request.cookie.as_deref()) {
            Ok(value) => value,
            Err(error) => return std::convert::identity(database_error_response(error)),
        },
        &csrf_token,
    ) {
        Ok(body) => body,
        Err(error) => {
            eprintln!("architect task console render failed: {error:?}");
            return http_text_response(500, "Internal Server Error", "response unavailable\n");
        }
    };
    let body = architect_guard_preview_actions(app, &body, true);
    let body = dynamic::csrf_inject_hidden_inputs(artifact_root, &body, &csrf_token);
    http_html_response(200, "OK", &body, method)
}

pub(super) fn architect_editor_panel_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    let editor_route = matched_app_route(app, "GET", "/editor").unwrap_or_else(|| {
        serde_json::json!({
            "page_id": "editor",
            "feature_id": "architect_builder_console",
            "template": "templates/editor.body.html",
            "queries": ["editor_projects", "editor_versions", "source_exports"]
        })
    });
    let body = match feature_runtime::render_feature_page_body(
        app,
        &editor_route,
        "/editor",
        match active_session_user_id(app, request.cookie.as_deref()) {
            Ok(value) => value,
            Err(error) => return std::convert::identity(database_error_response(error)),
        },
        &csrf_token,
    ) {
        Ok(body) => body,
        Err(error) => {
            eprintln!("architect editor render failed: {error:?}");
            return http_text_response(500, "Internal Server Error", "response unavailable\n");
        }
    };
    let body = architect_guard_preview_actions(app, &body, false);
    let body = dynamic::csrf_inject_hidden_inputs(artifact_root, &body, &csrf_token);
    http_html_response(200, "OK", &body, method)
}

pub(super) fn architect_settings_access_denied_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
    target: &str,
) -> Vec<u8> {
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let return_url = app_scope_path(app, "/");
    let params = serde_json::json!({
        "error_code": "access_denied",
        "return_delay_seconds": "3",
        "return_url": return_url,
    });
    let Some(body) = json_commands::template_render_file(
        &artifact_root.join("templates/errors/access_denied.body.html"),
        &params,
    ) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let actor_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 rendered = json_commands::template_layout_page_html(
        artifact_root,
        app.base_path.as_deref(),
        Some("architect_shell"),
        Some("en"),
        "Access denied",
        &body,
        Some(target),
        actor_id > 0,
        0,
    )
    .unwrap_or(body);
    let refresh_header = format!("Refresh: 3; url={}", app_scope_path(app, "/"));
    http_html_response_with_headers(403, "Forbidden", &rendered, method, &refresh_header)
}

pub(super) fn architect_settings_review_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    let mut settings_route = matched_app_route(app, "GET", "/settings").unwrap_or_else(|| {
        serde_json::json!({
            "page_id": "settings",
            "feature_id": "architect_builder_console",
            "template": "templates/settings.body.html",
            "queries": ["llm_vendors", "settings_llm_vendor_options", "target_profiles", "workspace_settings", "privacy_settings", "architect_users", "recent_vault_audits", "source_exports", "recent_attachments", "recent_attachment_extracts", "recent_transcripts"]
        })
    });
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    match actor_has_route_policy(app, actor_id, "manage_llm_vendors") {
        Ok(true) => {}
        Ok(false) => {
            return architect_settings_access_denied_response(app, request, method, "/settings");
        }
        Err(error) => return database_error_response(error),
    }
    match actor_has_route_policy(app, actor_id, "manage_builder_settings") {
        Ok(true) => {}
        Ok(false) => {
            settings_route["page_id"] = serde_json::json!("settings_llm");
            settings_route["queries"] = serde_json::json!(["llm_vendors"]);
        }
        Err(error) => return database_error_response(error),
    }
    let mut rendered_body = None;
    let mut last_error = None;
    let max_attempts = 40;
    for attempt in 0..max_attempts {
        match feature_runtime::render_feature_page_body(
            app,
            &settings_route,
            "/settings",
            actor_id,
            &csrf_token,
        ) {
            Ok(body) => {
                rendered_body = Some(body);
                break;
            }
            Err(error) => {
                last_error = Some(error);
                if attempt + 1 < max_attempts {
                    std::thread::sleep(Duration::from_millis(100));
                }
            }
        }
    }
    let body = match rendered_body {
        Some(body) => body,
        None => {
            if let Some(error) = last_error {
                eprintln!("architect settings review render failed: {error:?}");
            }
            return http_text_response(500, "Internal Server Error", "response unavailable\n");
        }
    };
    let body = dynamic::csrf_inject_hidden_inputs(artifact_root, &body, &csrf_token);
    if dynamic::request_is_hx(Some(request)) {
        return http_html_response(200, "OK", &body, method);
    }
    let target = app_relative_target(app, request.target.as_str());
    let rendered = json_commands::template_layout_page_html(
        artifact_root,
        app.base_path.as_deref(),
        Some("architect_shell"),
        Some("en"),
        "Settings",
        &body,
        Some(&target),
        actor_id > 0,
        1,
    )
    .unwrap_or(body);
    let rendered = dynamic::csrf_inject_hidden_inputs(artifact_root, &rendered, &csrf_token);
    http_html_response_with_csrf(200, "OK", &rendered, method, Some(&csrf_token))
}

pub(super) fn architect_account_level(value: &str) -> Option<&'static str> {
    match value {
        "architect_admin" => Some("architect_admin"),
        "build_user" => Some("build_user"),
        _ => None,
    }
}

pub(super) fn architect_form_text(request: &http::HttpRequest, field: &str) -> String {
    dynamic::request_form_value(request, field)
        .unwrap_or_default()
        .trim()
        .to_owned()
}

pub(super) fn architect_valid_username(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 120
        && value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
}

pub(super) fn architect_valid_email(value: &str) -> bool {
    let Some((local, domain)) = value.split_once('@') else {
        return false;
    };
    !local.is_empty()
        && !domain.is_empty()
        && value.len() <= 240
        && !value.contains(['\r', '\n', '<', '>', ' '])
        && domain.contains('.')
}

pub(super) fn architect_manage_users_allowed_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
) -> Result<i64, Vec<u8>> {
    if app.app_id.as_deref() != Some("architect") {
        return Err(http_text_response(404, "Not Found", "not found\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 actor_id <= 0 {
        return Err(app_login_redirect(app, "/settings"));
    }
    if !match actor_has_route_policy(app, actor_id, "manage_architect_users") {
        Ok(value) => value,
        Err(error) => return Err(database_error_response(error)),
    } {
        return Err(http_text_response(403, "Forbidden", "capability denied\n"));
    }
    Ok(actor_id)
}

pub(super) fn architect_create_user_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if let Err(response) = architect_manage_users_allowed_response(app, request) {
        return response;
    }
    let username = architect_form_text(request, "username");
    let email = architect_form_text(request, "email");
    let account_level = architect_form_text(request, "account_level");
    let password = dynamic::request_form_value(request, "password").unwrap_or_default();
    let password_confirm =
        dynamic::request_form_value(request, "password_confirm").unwrap_or_default();
    let Some(role) = architect_account_level(&account_level) else {
        return http_text_response(422, "Unprocessable Entity", "invalid account level\n");
    };
    if !architect_valid_username(&username) || !architect_valid_email(&email) {
        return http_text_response(422, "Unprocessable Entity", "invalid user details\n");
    }
    if password.len() < 8 || password.len() > 256 || password != password_confirm {
        return http_text_response(422, "Unprocessable Entity", "invalid password\n");
    }
    let Ok(password_hash) = dynamic::hash_password(&password) else {
        return http_text_response(500, "Internal Server Error", "password hash unavailable\n");
    };
    match architect_create_user(app, &username, &email, &username, role, &password_hash) {
        Ok(user_id) => {
            if let Ok(cache_scope) = super::app_security_cache_scope(app) {
                pharos_runtime_security::local_role_cache_revoke_actor(&cache_scope, user_id);
                pharos_runtime_security::local_session_cache_revoke_user(&cache_scope, user_id);
                super::cache::session_cache_revoke_user(&cache_scope, user_id);
            }
            architect_settings_review_response(app, request, method)
        }
        Err(_) => http_text_response(422, "Unprocessable Entity", "user could not be created\n"),
    }
}

pub(super) fn architect_set_user_password_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if let Err(response) = architect_manage_users_allowed_response(app, request) {
        return response;
    }
    let user_id = architect_form_text(request, "user_id")
        .parse::<i64>()
        .unwrap_or(0);
    let password = dynamic::request_form_value(request, "password").unwrap_or_default();
    let password_confirm =
        dynamic::request_form_value(request, "password_confirm").unwrap_or_default();
    if user_id <= 0 {
        return http_text_response(
            422,
            "Unprocessable Entity",
            "invalid user update
",
        );
    }
    if password.len() < 8 || password.len() > 256 || password != password_confirm {
        return http_text_response(
            422,
            "Unprocessable Entity",
            "invalid password
",
        );
    }
    let Ok(password_hash) = dynamic::hash_password(&password) else {
        return http_text_response(
            500,
            "Internal Server Error",
            "password hash unavailable
",
        );
    };
    match architect_set_user_password(app, user_id, &password_hash) {
        Ok(()) => architect_settings_review_response(app, request, method),
        Err(_) => http_text_response(
            422,
            "Unprocessable Entity",
            "password could not be updated
",
        ),
    }
}

pub(super) fn architect_update_user_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    let actor_id = match architect_manage_users_allowed_response(app, request) {
        Ok(actor_id) => actor_id,
        Err(response) => return response,
    };
    let user_id = architect_form_text(request, "user_id")
        .parse::<i64>()
        .unwrap_or(0);
    let is_active = architect_form_text(request, "is_active")
        .parse::<i64>()
        .unwrap_or(-1);
    let account_level = architect_form_text(request, "account_level");
    let password = dynamic::request_form_value(request, "password").unwrap_or_default();
    let password_confirm =
        dynamic::request_form_value(request, "password_confirm").unwrap_or_default();
    let password_change_requested = !password.is_empty() || !password_confirm.is_empty();
    let Some(role) = architect_account_level(&account_level) else {
        return http_text_response(422, "Unprocessable Entity", "invalid account level\n");
    };
    if user_id <= 0 || !matches!(is_active, 0 | 1) {
        return http_text_response(422, "Unprocessable Entity", "invalid user update\n");
    }
    if user_id == actor_id && (is_active == 0 || role != "architect_admin") {
        return http_text_response(
            422,
            "Unprocessable Entity",
            "cannot remove your own admin access\n",
        );
    }
    let password_hash = if password_change_requested {
        if password.len() < 8 || password.len() > 256 || password != password_confirm {
            return http_text_response(422, "Unprocessable Entity", "invalid password\n");
        }
        match dynamic::hash_password(&password) {
            Ok(password_hash) => Some(password_hash),
            Err(_) => {
                return http_text_response(
                    500,
                    "Internal Server Error",
                    "password hash unavailable\n",
                );
            }
        }
    } else {
        None
    };
    match architect_update_user(app, user_id, role, is_active == 1) {
        Ok(()) => {
            if let Some(password_hash) = password_hash.as_deref()
                && architect_set_user_password(app, user_id, password_hash).is_err()
            {
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    "password could not be updated\n",
                );
            }
            if let Ok(cache_scope) = super::app_security_cache_scope(app) {
                pharos_runtime_security::local_role_cache_revoke_actor(&cache_scope, user_id);
                pharos_runtime_security::local_session_cache_revoke_user(&cache_scope, user_id);
                super::cache::session_cache_revoke_user(&cache_scope, user_id);
            }
            architect_settings_review_response(app, request, method)
        }
        Err(_) => http_text_response(422, "Unprocessable Entity", "user could not be updated\n"),
    }
}

/// Deletes another account through the logical contract and revokes cached access.
pub(super) fn architect_delete_user_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    let actor_id = match architect_manage_users_allowed_response(app, request) {
        Ok(actor_id) => actor_id,
        Err(response) => return response,
    };
    let user_id = architect_form_text(request, "user_id")
        .parse::<i64>()
        .unwrap_or(0);
    if user_id <= 0 || user_id == actor_id {
        return http_text_response(
            422,
            "Unprocessable Entity",
            "cannot delete your own account or an invalid user\n",
        );
    }
    let (config, adapter, schema) = match architect_user_storage(app) {
        Ok(storage) => storage,
        Err(_) => {
            return http_text_response(503, "Service Unavailable", "user storage unavailable\n");
        }
    };
    match pharos_runtime_architect::user_state::delete_user(
        &config,
        adapter.as_ref(),
        &schema,
        user_id,
    ) {
        Ok(()) => {
            if let Ok(cache_scope) = super::app_security_cache_scope(app) {
                pharos_runtime_security::local_role_cache_revoke_actor(&cache_scope, user_id);
                pharos_runtime_security::local_session_cache_revoke_user(&cache_scope, user_id);
                super::cache::session_cache_revoke_user(&cache_scope, user_id);
            }
            #[cfg(not(target_os = "wasi"))]
            if let Ok(authority) =
                pharos_runtime_architect::chatgpt::InstalledArchitect::from_runtime(app)
                && pharos_runtime_architect::chatgpt::service::erase_deleted_user(
                    &authority, user_id,
                )
                .is_err()
            {
                return http_text_response(
                    503,
                    "Service Unavailable",
                    "User deleted; ChatGPT credential cleanup requires retry",
                );
            }
            architect_settings_review_response(app, request, method)
        }
        Err(pharos_runtime_database::operations::DatabaseError::Conflict) => http_text_response(
            409,
            "Conflict",
            "user has retained project or activity history; disable the account instead\n",
        ),
        Err(error) => database_error_response(error),
    }
}

/// Resolves the configured database and typed Architect account declarations.
fn architect_user_storage(
    app: &AppRuntime,
) -> Result<
    (
        pharos_runtime_database::DbBackendConfig,
        std::sync::Arc<dyn pharos_runtime_database::operations::DatabaseOperations>,
        pharos_runtime_database::operations::AppSchema,
    ),
    i32,
> {
    architect_database_storage_for_app(app, &["user_account", "store_membership"])
}

/// Resolves the configured adapter and the Architect entities needed by one route.
fn architect_database_storage_for_app(
    app: &AppRuntime,
    entities: &[&str],
) -> Result<
    (
        pharos_runtime_database::DbBackendConfig,
        std::sync::Arc<dyn pharos_runtime_database::operations::DatabaseOperations>,
        pharos_runtime_database::operations::AppSchema,
    ),
    i32,
> {
    let app_root = app.app_root.as_deref().map(Path::new).ok_or(69)?;
    let artifact_root = app
        .artifact_dir
        .as_deref()
        .map(Path::new)
        .unwrap_or(app_root);
    agent_architect::architect_database_storage(
        app_root,
        artifact_root,
        app.runtime_conf_path.as_deref().map(Path::new),
        entities,
    )
    .map_err(|_| 69)
}

/// Opens the Architect task store through the configured logical database contract.
pub(super) fn architect_task_store_for_app(
    app: &AppRuntime,
) -> Result<pharos_runtime_architect::database::ArchitectStore, i32> {
    let app_root = app.app_root.as_deref().map(Path::new).ok_or(69)?;
    let artifact_root = app
        .artifact_dir
        .as_deref()
        .map(Path::new)
        .unwrap_or(app_root);
    agent_architect::architect_worker_store(
        app_root,
        artifact_root,
        app.runtime_conf_path.as_deref().map(Path::new),
    )
    .map_err(|_| 69)
}

/// Creates an Architect account through one logical database transaction.
fn architect_create_user(
    app: &AppRuntime,
    username: &str,
    email: &str,
    display_name: &str,
    role: &str,
    password_hash: &str,
) -> Result<i64, i32> {
    let (config, adapter, schema) = architect_user_storage(app)?;
    pharos_runtime_architect::user_state::create_user(
        &config,
        adapter.as_ref(),
        &schema,
        pharos_runtime_architect::user_state::NewUser {
            username,
            email,
            display_name,
            role,
            password_hash,
        },
    )
    .map_err(|_| 69)
}

pub(super) fn architect_set_user_password(
    app: &AppRuntime,
    user_id: i64,
    password_hash: &str,
) -> Result<(), i32> {
    let app_root = app.app_root.as_deref().map(Path::new).ok_or(69)?;
    let runtime_conf = app.runtime_conf_path.as_deref().map(Path::new);
    #[cfg(not(target_os = "wasi"))]
    if let Ok(authority) = pharos_runtime_architect::chatgpt::InstalledArchitect::from_runtime(app)
    {
        let store = architect_task_store_for_app(app)?;
        pharos_runtime_architect::chatgpt::service::disconnect(&authority, &store, user_id, false)
            .map_err(|_| 69)?;
    }
    database::dynamic_relational_update_user_password(
        app_root,
        runtime_conf,
        app.app_id.as_deref(),
        user_id,
        password_hash,
    )
    .map_err(|_| 69)
}

/// Updates Architect activation and role through one logical transaction.
fn architect_update_user(
    app: &AppRuntime,
    user_id: i64,
    role: &str,
    is_active: bool,
) -> Result<(), i32> {
    let (config, adapter, schema) = architect_user_storage(app)?;
    pharos_runtime_architect::user_state::update_user(
        &config,
        adapter.as_ref(),
        &schema,
        user_id,
        role,
        is_active,
    )
    .map_err(|_| 69)
}

pub(super) fn architect_configure_llm_vendor_connection_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/settings");
    }
    if !match actor_has_route_policy(app, actor_id, "manage_llm_vendors") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id").unwrap_or_default();
    let llm_vendor_kind =
        dynamic::request_form_value(request, "llm_vendor_kind").unwrap_or_default();
    let display_name = dynamic::request_form_value(request, "display_name").unwrap_or_default();
    let model_id = dynamic::request_form_value(request, "model_id").unwrap_or_default();
    let base_url = dynamic::request_form_value(request, "base_url").unwrap_or_default();
    let enabled = dynamic::request_form_value(request, "enabled").unwrap_or_else(|| "0".to_owned());
    match architect_configure_llm_vendor_connection(
        &store,
        &llm_vendor_id,
        &llm_vendor_kind,
        &display_name,
        &model_id,
        &base_url,
        &enabled,
    ) {
        Ok(()) => architect_settings_review_response(app, request, method),
        Err(_) => http_text_response(
            422,
            "Unprocessable Entity",
            "LLM vendor settings rejected\n",
        ),
    }
}

/// Saves validated non-secret LLM vendor settings through the selected database adapter.
pub(super) fn architect_configure_llm_vendor_connection(
    store: &pharos_runtime_architect::database::ArchitectStore,
    llm_vendor_id: &str,
    llm_vendor_kind: &str,
    display_name: &str,
    model_id: &str,
    base_url: &str,
    enabled: &str,
) -> Result<(), i32> {
    if !matches!(
        llm_vendor_id,
        "openai_compatible"
            | "anthropic_claude"
            | "google_gemini"
            | "nvidia_nim"
            | "ollama_compatible"
            | "local_whisper"
    ) {
        return Err(64);
    }
    if !matches!(llm_vendor_kind, "cloud" | "local") {
        return Err(64);
    }
    let display_name = display_name.trim();
    let model_id = model_id.trim();
    let base_url = base_url.trim();
    if display_name.is_empty()
        || display_name.len() > 120
        || model_id.is_empty()
        || model_id.len() > 128
        || base_url.is_empty()
        || base_url.len() > 512
    {
        return Err(64);
    }
    let enabled_value = match enabled {
        "1" => true,
        "0" => false,
        _ => return Err(64),
    };
    let cloud_egress_allowed = llm_vendor_kind == "cloud";
    use pharos_runtime_database::operations::{Mutation, Predicate, WriteValue};
    store.transact(vec![Mutation::Update {
        entity: "architect_llm_vendor".to_owned(),
        filter: Predicate::Equal("llm_vendor_id".to_owned(), serde_json::json!(llm_vendor_id)),
        values: std::collections::BTreeMap::from([
            ("llm_vendor_kind".to_owned(), WriteValue::Literal(serde_json::json!(llm_vendor_kind))),
            ("display_name".to_owned(), WriteValue::Literal(serde_json::json!(display_name))),
            ("model_id".to_owned(), WriteValue::Literal(serde_json::json!(model_id))),
            ("base_url".to_owned(), WriteValue::Literal(serde_json::json!(base_url))),
            ("enabled".to_owned(), WriteValue::Literal(serde_json::json!(enabled_value))),
            ("cloud_egress_allowed".to_owned(), WriteValue::Literal(serde_json::json!(cloud_egress_allowed))),
            ("activation_status".to_owned(), WriteValue::Literal(serde_json::json!("draft_saved"))),
            ("status_message".to_owned(), WriteValue::Literal(serde_json::json!("LLM vendor settings saved. Add or rotate the API Key, then run a connection test before routing is enabled."))),
            ("last_tested_at".to_owned(), WriteValue::Literal(Value::Null)),
            ("updated_at".to_owned(), WriteValue::Literal(serde_json::json!(current_timestamp_utc()))),
        ]), expected_rows: Some(1),
    }]).map_err(|_| 69)?;
    Ok(())
}

pub(super) fn architect_rotate_llm_vendor_secret_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/settings");
    }
    if !match actor_has_route_policy(app, actor_id, "manage_llm_vendors") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some((vault_path, root_key_file)) = architect_vault_paths(app) else {
        return http_text_response(503, "Service Unavailable", "vault unavailable\n");
    };
    if ensure_architect_root_key(&root_key_file).is_err() {
        return http_text_response(503, "Service Unavailable", "vault key unavailable\n");
    }
    let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id").unwrap_or_default();
    let mut llm_vendor_secret =
        dynamic::request_form_value(request, "llm_vendor_secret").unwrap_or_default();
    let trimmed_secret = llm_vendor_secret.trim().as_bytes().to_vec();
    llm_vendor_secret.clear();
    let Ok((config, adapter, schema)) =
        architect_database_storage_for_app(app, &["architect_llm_vendor", "architect_vault_audit"])
    else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let result = agent_vault::put_architect_runtime_llm_vendor_secret(
        &config,
        adapter.as_ref(),
        &schema,
        &vault_path,
        &root_key_file,
        &llm_vendor_id,
        &trimmed_secret,
    );
    drop(trimmed_secret);
    match result {
        Ok(_) => {
            if architect_mark_llm_vendor_secret_saved(&store, &llm_vendor_id).is_err() {
                return http_text_response(
                    503,
                    "Service Unavailable",
                    "LLM vendor status unavailable\n",
                );
            }
            architect_settings_review_response(app, request, method)
        }
        Err(error) => {
            eprintln!("architect LLM vendor secret rotation failed: {error:?}");
            http_text_response(422, "Unprocessable Entity", "LLM vendor secret rejected\n")
        }
    }
}

/// Marks encrypted LLM vendor credentials ready for a connection test.
pub(super) fn architect_mark_llm_vendor_secret_saved(
    store: &pharos_runtime_architect::database::ArchitectStore,
    llm_vendor_id: &str,
) -> Result<(), i32> {
    use pharos_runtime_database::operations::{Mutation, Predicate, WriteValue};
    store.transact(vec![Mutation::Update {
        entity: "architect_llm_vendor".to_owned(),
        filter: Predicate::Equal("llm_vendor_id".to_owned(), serde_json::json!(llm_vendor_id)),
        values: std::collections::BTreeMap::from([
            ("activation_status".to_owned(), WriteValue::Literal(serde_json::json!("draft_saved"))),
            ("status_message".to_owned(), WriteValue::Literal(serde_json::json!("LLM vendor API Key saved in the encrypted runtime vault. Run a connection test before routing tasks to this LLM vendor."))),
            ("updated_at".to_owned(), WriteValue::Literal(serde_json::json!(current_timestamp_utc()))),
        ]), expected_rows: Some(1),
    }]).map_err(|_| 69)?;
    Ok(())
}

#[derive(Debug, Clone)]
pub(super) struct ArchitectLlmVendorState {
    llm_vendor_kind: String,
    model_id: String,
    base_url: String,
    enabled: bool,
    cloud_egress_allowed: bool,
    activation_status: String,
    secret_ref: String,
}

pub(super) fn architect_test_llm_vendor_connection_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/settings");
    }
    if !match actor_has_route_policy(app, actor_id, "manage_llm_vendors") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some((vault_path, root_key_file)) = architect_vault_paths(app) else {
        return http_text_response(503, "Service Unavailable", "vault unavailable\n");
    };
    let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id").unwrap_or_default();
    let (status, message) =
        architect_test_llm_vendor_connection(&store, &vault_path, &root_key_file, &llm_vendor_id);
    if architect_update_llm_vendor_activation_status(&store, &llm_vendor_id, &status, &message)
        .is_err()
    {
        return http_text_response(
            503,
            "Service Unavailable",
            "LLM vendor status unavailable\n",
        );
    }
    architect_settings_review_response(app, request, method)
}

pub(super) fn architect_revoke_llm_vendor_connection_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/settings");
    }
    if !match actor_has_route_policy(app, actor_id, "manage_llm_vendors") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id").unwrap_or_default();
    if architect_revoke_llm_vendor_connection(&store, &llm_vendor_id).is_err() {
        return http_text_response(
            503,
            "Service Unavailable",
            "LLM vendor revoke unavailable\n",
        );
    }
    architect_settings_review_response(app, request, method)
}

/// Revokes LLM vendor routing and records its vault audit in one logical transaction.
pub(super) fn architect_revoke_llm_vendor_connection(
    store: &pharos_runtime_architect::database::ArchitectStore,
    llm_vendor_id: &str,
) -> Result<(), i32> {
    use pharos_runtime_database::operations::{Mutation, Predicate, WriteValue};
    if llm_vendor_id == "builtin" || llm_vendor_id.is_empty() || llm_vendor_id.len() > 64 {
        return Err(64);
    }
    let now = current_timestamp_utc();
    store.transact(vec![
        Mutation::Update {
            entity: "architect_llm_vendor".to_owned(),
            filter: Predicate::Equal("llm_vendor_id".to_owned(), serde_json::json!(llm_vendor_id)),
            values: std::collections::BTreeMap::from([
                ("enabled".to_owned(), WriteValue::Literal(serde_json::json!(false))),
                ("activation_status".to_owned(), WriteValue::Literal(serde_json::json!("revoked"))),
                ("status_message".to_owned(), WriteValue::Literal(serde_json::json!("LLM vendor routing was revoked. Save settings, rotate the API Key if needed, and test again before reuse."))),
                ("secret_ref".to_owned(), WriteValue::Literal(Value::Null)),
                ("updated_at".to_owned(), WriteValue::Literal(serde_json::json!(now))),
            ]), expected_rows: Some(1),
        },
        Mutation::Insert {
            entity: "architect_vault_audit".to_owned(),
            values: std::collections::BTreeMap::from([
                ("llm_vendor_id".to_owned(), WriteValue::Literal(serde_json::json!(llm_vendor_id))),
                ("secret_ref".to_owned(), WriteValue::Literal(serde_json::json!(format!("architect.{llm_vendor_id}.api_key")))),
                ("event_kind".to_owned(), WriteValue::Literal(serde_json::json!("secret_unset"))),
                ("fingerprint".to_owned(), WriteValue::Literal(serde_json::json!("removed"))),
                ("created_at".to_owned(), WriteValue::Literal(serde_json::json!(now))),
            ]),
        },
    ]).map_err(|_| 69)?;
    Ok(())
}

pub(super) fn architect_test_llm_vendor_connection(
    store: &pharos_runtime_architect::database::ArchitectStore,
    vault_path: &Path,
    root_key_file: &Path,
    llm_vendor_id: &str,
) -> (String, String) {
    let Some(state) = architect_llm_vendor_state_in_store(store, llm_vendor_id) else {
        return (
            "test_failed".to_owned(),
            "LLM vendor configuration could not be loaded.".to_owned(),
        );
    };
    if !state.enabled {
        return (
            "test_failed".to_owned(),
            "Enable this LLM vendor before running the connection test.".to_owned(),
        );
    }
    if state.model_id.trim().is_empty() || state.base_url.trim().is_empty() {
        return (
            "test_failed".to_owned(),
            "Model id and base URL are required before testing this provider.".to_owned(),
        );
    }
    if state.secret_ref.trim().is_empty() {
        return (
            "missing_secret".to_owned(),
            "Save an LLM vendor API key in the encrypted vault before testing this LLM vendor."
                .to_owned(),
        );
    }
    if state.llm_vendor_kind == "cloud" && !state.cloud_egress_allowed {
        return (
            "test_failed".to_owned(),
            "Allow cloud egress for this LLM vendor before testing a cloud endpoint.".to_owned(),
        );
    }
    let allow_plaintext_local = state.llm_vendor_kind == "local";
    if state.base_url.starts_with("http://") && !allow_plaintext_local {
        return (
            "test_failed".to_owned(),
            "HTTP LLM vendor tests are limited to local LLM vendor endpoints.".to_owned(),
        );
    }
    if state.base_url.starts_with("http://")
        && !pharos_runtime_architect::llm_vendor::url_uses_loopback_http(&state.base_url)
    {
        return (
            "test_failed".to_owned(),
            "Local HTTP LLM vendor tests must use a loopback localhost endpoint.".to_owned(),
        );
    }
    let Ok(secret_bytes) = agent_vault::get_architect_runtime_llm_vendor_secret(
        vault_path,
        root_key_file,
        llm_vendor_id,
    ) else {
        return (
            "missing_secret".to_owned(),
            "Saved LLM vendor secret could not be read from the encrypted vault.".to_owned(),
        );
    };
    let mut secret = match String::from_utf8(secret_bytes) {
        Ok(value) => value,
        Err(_) => {
            return (
                "test_failed".to_owned(),
                "Saved LLM vendor secret is not valid text for this adapter.".to_owned(),
            );
        }
    };
    let Some((method, url, content_type, payload, headers, failure_label)) =
        architect_llm_vendor_connection_request(llm_vendor_id, &state, secret.trim())
    else {
        secret.clear();
        return (
            "test_failed".to_owned(),
            "LLM vendor base URL or model id is invalid.".to_owned(),
        );
    };
    let response = pharos_runtime_integrations::webhook::send_request(
        method,
        &url,
        content_type,
        &payload,
        &headers,
        pharos_runtime_integrations::webhook::WebhookLimits {
            connect_timeout: std::time::Duration::from_secs(5),
            operation_timeout: std::time::Duration::from_secs(15),
            max_response_bytes: 128 * 1024,
            allow_plaintext_local,
        },
    );
    secret.clear();
    match response {
        Some(value) if (200..300).contains(&value.status_code) => {
            if llm_vendor_id == "local_whisper" {
                (
                    "transcription_active".to_owned(),
                    "Whisper-compatible audio transcription test passed. This LLM vendor is now available for voice transcription.".to_owned(),
                )
            } else {
                (
                    "tested_active".to_owned(),
                    "LLM vendor connection test passed. This LLM vendor is now available for task routing.".to_owned(),
                )
            }
        }
        Some(value) if matches!(value.status_code, 401 | 403) => (
            "test_failed".to_owned(),
            format!(
                "LLM vendor rejected the saved API key with HTTP status {}. Rotate the secret and test again{}",
                value.status_code,
                pharos_runtime_architect::llm_vendor::llm_vendor_failure_excerpt(&value.body)
            ),
        ),
        Some(value) => (
            "test_failed".to_owned(),
            format!(
                "LLM vendor connection test reached the endpoint but failed with HTTP status {}. Check the base URL, model id, and provider type{}",
                value.status_code,
                pharos_runtime_architect::llm_vendor::llm_vendor_failure_excerpt(&value.body)
            ),
        ),
        None => (
            "test_failed".to_owned(),
            format!("LLM vendor connection test could not reach a valid {failure_label} endpoint."),
        ),
    }
}

type ArchitectLlmVendorConnectionRequest = (
    &'static str,
    String,
    Option<&'static str>,
    String,
    Vec<(&'static str, String)>,
    &'static str,
);

pub(super) fn architect_llm_vendor_connection_request(
    llm_vendor_id: &str,
    state: &ArchitectLlmVendorState,
    secret: &str,
) -> Option<ArchitectLlmVendorConnectionRequest> {
    if secret.is_empty() || secret.len() > 4096 {
        return None;
    }
    match llm_vendor_id {
        "anthropic_claude" => Some((
            "POST",
            pharos_runtime_architect::llm_vendor::join_vendor_url(&state.base_url, "messages")?,
            Some("application/json"),
            serde_json::to_string(&serde_json::json!({
                "model": state.model_id,
                "max_tokens": 8,
                "messages": [{"role": "user", "content": "Return ok."}]
            }))
            .ok()?,
            vec![
                ("x-api-key", secret.to_owned()),
                ("anthropic-version", "2023-06-01".to_owned()),
            ],
            "Anthropic Messages",
        )),
        "google_gemini" => Some((
            "POST",
            pharos_runtime_architect::llm_vendor::gemini_generate_content_url_option(
                &state.base_url,
                &state.model_id,
            )?,
            Some("application/json"),
            serde_json::to_string(&serde_json::json!({
                "contents": [{"parts": [{"text": "Return ok."}]}],
                "generationConfig": {"temperature": 0}
            }))
            .ok()?,
            vec![("x-goog-api-key", secret.to_owned())],
            "Gemini generateContent",
        )),
        "local_whisper" => Some((
            "GET",
            pharos_runtime_architect::llm_vendor::join_vendor_url(&state.base_url, "models")?,
            None,
            String::new(),
            vec![("Authorization", format!("Bearer {secret}"))],
            "Whisper-compatible audio",
        )),
        "openai_compatible" | "ollama_compatible" | "nvidia_nim" => Some((
            "POST",
            pharos_runtime_architect::llm_vendor::join_vendor_url(&state.base_url, "chat/completions")?,
            Some("application/json"),
            serde_json::to_string(&serde_json::json!({
                "model": state.model_id,
                "messages": [{"role": "user", "content": "Return only ok."}],
                if llm_vendor_id == "openai_compatible" { "max_completion_tokens" } else { "max_tokens" }: 64
            })).ok()?,
            vec![("Authorization", format!("Bearer {secret}"))],
            "OpenAI-compatible",
        )),
        _ => None,
    }
}

/// Reads one LLM vendor record from the configured Architect database.
fn architect_llm_vendor_state_in_store(
    store: &pharos_runtime_architect::database::ArchitectStore,
    llm_vendor_id: &str,
) -> Option<ArchitectLlmVendorState> {
    use pharos_runtime_database::operations::Predicate;
    let row = store
        .query_one(
            "architect_llm_vendor",
            &[
                "llm_vendor_kind",
                "model_id",
                "base_url",
                "enabled",
                "cloud_egress_allowed",
                "activation_status",
                "secret_ref",
            ],
            Predicate::Equal("llm_vendor_id".to_owned(), serde_json::json!(llm_vendor_id)),
        )
        .ok()??;
    let text = |field: &str| row.get(field).and_then(Value::as_str).map(str::to_owned);
    let enabled = |field: &str| {
        row.get(field)
            .and_then(Value::as_bool)
            .or_else(|| {
                row.get(field)
                    .and_then(Value::as_i64)
                    .map(|value| value == 1)
            })
            .unwrap_or(false)
    };
    Some(ArchitectLlmVendorState {
        llm_vendor_kind: text("llm_vendor_kind")?,
        model_id: text("model_id")?,
        base_url: text("base_url")?,
        enabled: enabled("enabled"),
        cloud_egress_allowed: enabled("cloud_egress_allowed"),
        activation_status: text("activation_status")?,
        secret_ref: text("secret_ref").unwrap_or_default(),
    })
}

/// Reads the vendor selected for a task without physical backend queries.
fn architect_task_llm_vendor_in_store(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
) -> Option<String> {
    use pharos_runtime_database::operations::Predicate;
    store
        .query_one(
            "architect_task",
            &["llm_vendor_id"],
            Predicate::Equal("id".to_owned(), serde_json::json!(task_id)),
        )
        .ok()??
        .get("llm_vendor_id")
        .and_then(Value::as_str)
        .map(str::to_owned)
}

/// Queues an accepted voice transcript as one guarded task transaction.
fn architect_queue_transcribed_task_in_store(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
    brief: &str,
) -> Result<(), i32> {
    use pharos_runtime_database::operations::{Mutation, Predicate, WriteValue};
    let brief = brief.chars().take(8192).collect::<String>();
    let now = current_timestamp_utc();
    store
        .transact(vec![
            Mutation::Update {
                entity: "architect_task".to_owned(),
                filter: Predicate::All(vec![
                    Predicate::Equal("id".to_owned(), serde_json::json!(task_id)),
                    Predicate::Any(vec![
                        Predicate::Equal("task_status".to_owned(), serde_json::json!("draft")),
                        Predicate::Equal("task_status".to_owned(), serde_json::json!("queued")),
                    ]),
                ]),
                values: std::collections::BTreeMap::from([
                    (
                        "brief".to_owned(),
                        WriteValue::Literal(serde_json::json!(brief)),
                    ),
                    (
                        "task_status".to_owned(),
                        WriteValue::Literal(serde_json::json!("queued")),
                    ),
                    (
                        "updated_at".to_owned(),
                        WriteValue::Literal(serde_json::json!(now)),
                    ),
                ]),
                expected_rows: Some(1),
            },
            Mutation::Insert {
                entity: "architect_task_event".to_owned(),
                values: std::collections::BTreeMap::from([
                    (
                        "task_id".to_owned(),
                        WriteValue::Literal(serde_json::json!(task_id)),
                    ),
                    (
                        "event_kind".to_owned(),
                        WriteValue::Literal(serde_json::json!("plan_requested")),
                    ),
                    (
                        "event_summary".to_owned(),
                        WriteValue::Literal(serde_json::json!(
                            "Voice transcript was accepted automatically and queued for planning."
                        )),
                    ),
                    (
                        "created_at".to_owned(),
                        WriteValue::Literal(serde_json::json!(now)),
                    ),
                ]),
            },
        ])
        .map_err(|_| 69)?;
    Ok(())
}

/// Saves bounded connection-test status through the configured database adapter.
pub(super) fn architect_update_llm_vendor_activation_status(
    store: &pharos_runtime_architect::database::ArchitectStore,
    llm_vendor_id: &str,
    status: &str,
    message: &str,
) -> Result<(), i32> {
    use pharos_runtime_database::operations::{Mutation, Predicate, WriteValue};
    let message: String = message.chars().take(512).collect();
    let now = current_timestamp_utc();
    store
        .transact(vec![Mutation::Update {
            entity: "architect_llm_vendor".to_owned(),
            filter: Predicate::Equal("llm_vendor_id".to_owned(), serde_json::json!(llm_vendor_id)),
            values: std::collections::BTreeMap::from([
                (
                    "activation_status".to_owned(),
                    WriteValue::Literal(serde_json::json!(status)),
                ),
                (
                    "status_message".to_owned(),
                    WriteValue::Literal(serde_json::json!(message)),
                ),
                (
                    "last_tested_at".to_owned(),
                    WriteValue::Literal(serde_json::json!(now)),
                ),
                (
                    "updated_at".to_owned(),
                    WriteValue::Literal(serde_json::json!(now)),
                ),
            ]),
            expected_rows: Some(1),
        }])
        .map_err(|_| 69)?;
    Ok(())
}

pub(super) fn architect_preview_image_content_type(
    filename: &str,
    supplied: Option<&str>,
) -> Option<&'static str> {
    let lower = filename.to_ascii_lowercase();
    let by_extension = if lower.ends_with(".png") {
        Some("image/png")
    } else if lower.ends_with(".jpg") || lower.ends_with(".jpeg") {
        Some("image/jpeg")
    } else if lower.ends_with(".webp") {
        Some("image/webp")
    } else if lower.ends_with(".gif") {
        Some("image/gif")
    } else {
        None
    }?;
    if let Some(supplied) = supplied {
        let supplied = supplied.to_ascii_lowercase();
        if !supplied.is_empty()
            && !supplied.starts_with(by_extension)
            && !(by_extension == "image/jpeg" && supplied.starts_with("image/jpg"))
        {
            return None;
        }
    }
    Some(by_extension)
}

pub(super) fn architect_preview_image_media_path(value: &str) -> Option<PathBuf> {
    let name = value.strip_prefix("/media/architect-preview/")?;
    if name.is_empty()
        || name.len() > 180
        || name.contains('/')
        || name.contains('\\')
        || name.contains("..")
        || !name.chars().all(|character| {
            character.is_ascii_alphanumeric() || matches!(character, '.' | '-' | '_')
        })
    {
        return None;
    }
    Some(PathBuf::from(name))
}

pub(super) fn architect_preview_image_response(
    app: &AppRuntime,
    media_path: &str,
    method: &str,
) -> Vec<u8> {
    let Some(filename) = architect_preview_image_media_path(media_path) else {
        return http_text_response(404, "Not Found", "not found\n");
    };
    let Some(media_root) = architect_media_root(app) else {
        return http_text_response(503, "Service Unavailable", "media storage unavailable\n");
    };
    let disk_path = media_root.join("preview").join(&filename);
    let Some(content_type) =
        architect_preview_image_content_type(filename.to_string_lossy().as_ref(), None)
    else {
        return http_text_response(404, "Not Found", "not found\n");
    };
    let Ok(body) = stdfs::read(&disk_path) else {
        return http_text_response(404, "Not Found", "not found\n");
    };
    http_inline_binary_response(&body, content_type, method)
}

fn http_inline_binary_response(body: &[u8], content_type: &str, method: &str) -> Vec<u8> {
    let headers = format!(
        "HTTP/1.1 200 OK\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\nX-Content-Type-Options: nosniff\r\nCache-Control: private, max-age=300\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
}

pub(super) fn architect_upload_preview_image_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    if let Err(response) = authorize_app_mutation(app, request, "/apps/view/upload-image") {
        return response;
    }
    let Some(content_type) = request.content_type.as_deref() else {
        return http_json_response(
            422,
            "Unprocessable Entity",
            r#"{"error":"missing multipart body"}"#,
            method,
        );
    };
    if !content_type
        .to_ascii_lowercase()
        .starts_with("multipart/form-data")
    {
        return http_json_response(
            415,
            "Unsupported Media Type",
            r#"{"error":"multipart body required"}"#,
            method,
        );
    }
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_json_response(
            422,
            "Unprocessable Entity",
            r#"{"error":"invalid task id"}"#,
            method,
        );
    }
    let Some((filename, bytes)) =
        json_commands::dynamic_multipart_find_part(&request.body, content_type, "image")
    else {
        return http_json_response(
            422,
            "Unprocessable Entity",
            r#"{"error":"image file required"}"#,
            method,
        );
    };
    if bytes.is_empty() || bytes.len() > 5 * 1024 * 1024 {
        return http_json_response(
            422,
            "Unprocessable Entity",
            r#"{"error":"image size must be 1 byte to 5 MB"}"#,
            method,
        );
    }
    let safe_name = filename
        .as_deref()
        .and_then(dynamic::safe_upload_filename)
        .filter(|value| !value.is_empty())
        .unwrap_or_else(|| "image.png".to_owned());
    let Some(content_type) = architect_preview_image_content_type(&safe_name, None) else {
        return http_json_response(
            422,
            "Unprocessable Entity",
            r#"{"error":"supported image types are PNG, JPEG, WebP, and GIF"}"#,
            method,
        );
    };
    let extension = Path::new(&safe_name)
        .extension()
        .and_then(|value| value.to_str())
        .unwrap_or("png")
        .to_ascii_lowercase();
    let nonce = dynamic::random_secret_hex(12).unwrap_or_else(|_| current_timestamp_utc());
    let stored_name = format!("task{task_id}-{nonce}.{extension}");
    let Some(media_root) = architect_media_root(app) else {
        return http_text_response(503, "Service Unavailable", "media storage unavailable\n");
    };
    let storage_root = media_root.join("preview");
    if stdfs::create_dir_all(&storage_root).is_err() {
        return http_json_response(
            503,
            "Service Unavailable",
            r#"{"error":"upload storage unavailable"}"#,
            method,
        );
    }
    let stored_path = storage_root.join(&stored_name);
    if fs::write_binary_file(&stored_path, &bytes, 0o640).is_err() {
        return http_json_response(
            503,
            "Service Unavailable",
            r#"{"error":"upload storage unavailable"}"#,
            method,
        );
    }
    let media_path = format!("/media/architect-preview/{stored_name}");
    let body = serde_json::json!({
        "schema": "pharos.architect.preview_image_upload.v1",
        "media_path": media_path,
        "filename": safe_name,
        "content_type": content_type,
    })
    .to_string();
    http_json_response(200, "OK", &body, method)
}

/// Serves a task-owned image asset without requiring a generated app or invoking extraction.
pub(super) fn architect_read_image_asset_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor = active_session_user_id(app, request.cookie.as_deref()).unwrap_or(0);
    if actor <= 0 {
        return app_login_redirect(app, "/");
    }
    let task_id = request_query_value(&request.target, "task_id")
        .and_then(|v| v.parse::<i64>().ok())
        .unwrap_or(0);
    let attachment_id = request_query_value(&request.target, "attachment_id")
        .and_then(|v| v.parse::<i64>().ok())
        .unwrap_or(0);
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    if task_id <= 0
        || attachment_id <= 0
        || pharos_runtime_architect::task_ownership::task_owner(&store, task_id)
            .ok()
            .flatten()
            != Some(actor)
    {
        return http_text_response(404, "Not Found", "image unavailable\n");
    }
    let Some(root) = architect_media_root(app) else {
        return http_text_response(503, "Service Unavailable", "media storage unavailable\n");
    };
    match pharos_runtime_architect::image_assets::read_image_in_store(
        &store,
        task_id,
        attachment_id,
        &root,
    ) {
        Ok((bytes, content_type)) => http_inline_binary_response(&bytes, &content_type, method),
        Err(_) => http_text_response(404, "Not Found", "image unavailable\n"),
    }
}

pub(super) fn architect_upload_attachment_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    if let Err(response) = authorize_app_mutation(app, request, "/attachments/upload") {
        return response;
    }
    let Some(content_type) = request.content_type.as_deref() else {
        return http_text_response(422, "Unprocessable Entity", "missing multipart body\n");
    };
    if !content_type
        .to_ascii_lowercase()
        .starts_with("multipart/form-data")
    {
        return http_text_response(415, "Unsupported Media Type", "multipart body required\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(state_parent) = architect_state_parent(app) else {
        return http_text_response(503, "Service Unavailable", "state unavailable\n");
    };
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| agent_ingest::parse_task_id(&value).ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid task id\n");
    }
    let actor = active_session_user_id(app, request.cookie.as_deref()).unwrap_or(0);
    if actor <= 0
        || pharos_runtime_architect::task_ownership::task_owner(&store, task_id)
            .ok()
            .flatten()
            != Some(actor)
    {
        return http_text_response(403, "Forbidden", "This task belongs to another user.\n");
    }
    if dynamic::request_form_value(request, "list_image_assets").as_deref() == Some("true") {
        let after_id =
            dynamic::request_form_value(request, "after_id").unwrap_or_else(|| "0".into());
        let Ok(after_id) = after_id.parse::<i64>() else {
            return http_text_response(422, "Unprocessable Entity", "invalid image cursor\n");
        };
        return match pharos_runtime_architect::image_assets::list_images_in_store(&store, task_id, after_id)
            .and_then(|page| {
                serde_json::to_string(&serde_json::json!({"task_id":task_id,"images":page.images,"next_after":page.next_after}))
                    .map_err(|_| agent_bridge::AgentErrorKind::InvalidEnvelope)
            }) {
            Ok(body) => http_json_response(200, "OK", &body, method),
            Err(_) => http_text_response(
                422,
                "Unprocessable Entity",
                "image asset list unavailable\n",
            ),
        };
    }
    if dynamic::request_form_value(request, "finalize_image_assets").as_deref() == Some("true") {
        let persisted =
            match pharos_runtime_architect::data_binding::has_source(&store, task_id, actor) {
                true => {
                    let Some(root) = architect_generated_source_root(app) else {
                        return http_text_response(
                            503,
                            "Service Unavailable",
                            "Generated source unavailable.\n",
                        );
                    };
                    if let Err(error) =
                        architect_prepare_csv_page_bindings(app, &store, task_id, actor, &root, "")
                    {
                        return http_text_response(
                            422,
                            "Unprocessable Entity",
                            &format!("Image source import failed: {error}\n"),
                        );
                    }
                    true
                }
                false => false,
            };
        return http_json_response(
            200,
            "OK",
            &serde_json::json!({"task_id":task_id,"persisted":persisted}).to_string(),
            method,
        );
    }
    let image_asset =
        dynamic::request_form_value(request, "attachment_role").as_deref() == Some("image_asset");
    let temp_root = state_parent.join("tmp/uploads");
    if stdfs::create_dir_all(&temp_root).is_err() {
        return http_text_response(503, "Service Unavailable", "upload storage unavailable\n");
    }
    let nonce = dynamic::random_secret_hex(12).unwrap_or_else(|_| current_timestamp_utc());
    let body_path = temp_root.join(format!("{nonce}.multipart"));
    let input_path = temp_root.join(format!("{nonce}.upload"));
    if fs::write_binary_file(&body_path, &request.body, 0o600).is_err() {
        return http_text_response(503, "Service Unavailable", "upload storage unavailable\n");
    }
    let filename =
        json_commands::dynamic_multipart_filename(content_type, &body_path, "attachment")
            .and_then(|value| dynamic::safe_upload_filename(&value))
            .unwrap_or_else(|| "attachment.bin".to_owned());
    let media_type = architect_attachment_media_type(
        &filename,
        dynamic::request_form_value(request, "media_type"),
    );
    let extract_status = json_commands::dynamic_multipart_extract_file(
        content_type,
        &body_path,
        "attachment",
        &input_path,
    );
    let _ = stdfs::remove_file(&body_path);
    if extract_status != 0 {
        let _ = stdfs::remove_file(&input_path);
        return http_text_response(422, "Unprocessable Entity", "attachment file required\n");
    }
    let Some(storage_root) = architect_media_root(app) else {
        return http_text_response(503, "Service Unavailable", "media storage unavailable\n");
    };
    if stdfs::create_dir_all(&storage_root).is_err() {
        let _ = stdfs::remove_file(&input_path);
        return http_text_response(503, "Service Unavailable", "upload storage unavailable\n");
    }
    if dynamic::request_form_value(request, "attachment_role").as_deref() == Some("csv_data") {
        let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
            Ok(actor) => actor,
            Err(error) => return database_error_response(error),
        };
        let result = pharos_runtime_architect::csv_import::inspect_or_prepare(
            &store,
            task_id,
            actor_id,
            &input_path,
            &storage_root,
            &filename,
            &dynamic::request_form_value(request, "csv_table").unwrap_or_default(),
            dynamic::request_form_value(request, "csv_existing").as_deref() == Some("true"),
            dynamic::request_form_value(request, "csv_mapping").as_deref(),
        );
        let _ = stdfs::remove_file(&input_path);
        return match result {
            Ok(value) => http_json_response(200, "OK", &value.to_string(), method),
            Err(message) => http_text_response(
                422,
                "Unprocessable Entity",
                &format!("{filename}: {message}"),
            ),
        };
    }
    if image_asset {
        let relative_path = dynamic::request_form_value(request, "relative_path")
            .unwrap_or_else(|| filename.clone());
        let result = pharos_runtime_architect::image_assets::import_image_in_store(
            &store,
            task_id,
            &input_path,
            &storage_root,
            &relative_path,
        );
        let _ = stdfs::remove_file(&input_path);
        return match result {
            Ok(asset) => match serde_json::to_string(&asset) {
                Ok(body) => http_json_response(200, "OK", &body, method),
                Err(_) => http_text_response(
                    503,
                    "Service Unavailable",
                    "image import result unavailable\n",
                ),
            },
            Err(error) => http_text_response(
                422,
                "Unprocessable Entity",
                &format!(
                    "image import rejected: {error:?}; use PNG, JPEG, WebP or GIF up to 2 MiB with a relative image path\n"
                ),
            ),
        };
    }
    let ingest = pharos_runtime_architect::attachment_ingest::ingest_attachment_in_store(
        &store,
        task_id,
        &input_path,
        &storage_root,
        &filename,
        &media_type,
    );
    let _ = stdfs::remove_file(&input_path);
    match ingest {
        Ok(ingest) => {
            if media_type.to_ascii_lowercase().starts_with("audio/") {
                let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id")
                    .filter(|value| !value.trim().is_empty())
                    .or_else(|| architect_task_llm_vendor_in_store(&store, task_id))
                    .unwrap_or_else(|| "builtin".to_owned());
                if matches!(llm_vendor_id.as_str(), "builtin" | "chatgpt") {
                    if agent_ingest::extract_architect_attachment_from_store(
                        &store,
                        task_id,
                        ingest.attachment_id,
                        &storage_root,
                    )
                    .is_err()
                    {
                        return http_text_response(
                            422,
                            "Unprocessable Entity",
                            "local audio transcription unavailable\n",
                        );
                    }
                } else {
                    let Some((vault_path, root_key_file)) = architect_vault_paths(app) else {
                        return http_text_response(
                            503,
                            "Service Unavailable",
                            "vault unavailable\n",
                        );
                    };
                    if architect_transcribe_audio_attachment_and_queue(
                        &store,
                        &vault_path,
                        &root_key_file,
                        &storage_root,
                        &ingest.storage_ref,
                        task_id,
                        &llm_vendor_id,
                        &filename,
                        &media_type,
                    )
                    .is_err()
                    {
                        return http_text_response(
                            422,
                            "Unprocessable Entity",
                            "audio transcription unavailable\n",
                        );
                    }
                }
            } else if let Err(error) = agent_ingest::extract_architect_attachment_from_store(
                &store,
                task_id,
                ingest.attachment_id,
                &storage_root,
            ) {
                let message = if error == agent_bridge::AgentErrorKind::CapacityExceeded {
                    format!("Context is empty or exceeds its extraction limit. Keep structured site-context JSON within {} KiB; use smaller context files or CSV for larger record sets.\n", pharos_runtime_architect::attachment_ingest::MAX_STRUCTURED_SITE_CONTEXT_BYTES / 1024)
                } else {
                    "attachment text extraction unavailable\n".to_owned()
                };
                return http_text_response(422, "Unprocessable Entity", &message);
            }
            architect_settings_review_response(app, request, method)
        }
        Err(error) => {
            let message = match error {
                agent_bridge::AgentErrorKind::CapacityExceeded => {
                    "attachment rejected: context files must be nonempty and at most 10 MiB each\n"
                }
                agent_bridge::AgentErrorKind::InvalidIdentifier => {
                    "attachment rejected: builder task was not found\n"
                }
                agent_bridge::AgentErrorKind::InvalidPath => {
                    "attachment rejected: storage or database write failed\n"
                }
                agent_bridge::AgentErrorKind::InvalidEnvelope => {
                    "attachment rejected: attachment metadata was invalid\n"
                }
                agent_bridge::AgentErrorKind::PolicyViolation => {
                    "attachment rejected: file type or storage policy blocked the upload\n"
                }
                agent_bridge::AgentErrorKind::CredentialUnavailable => {
                    "attachment rejected: required credential was unavailable\n"
                }
                agent_bridge::AgentErrorKind::LockBusy => {
                    "attachment rejected: database was busy\n"
                }
                _ => "attachment rejected: server could not accept the context file\n",
            };
            http_text_response(
                422,
                "Unprocessable Entity",
                &format!("{filename}: {message}"),
            )
        }
    }
}

/// Sends a saved Architect audio attachment to a tested external LLM vendor and queues the transcribed task brief.
pub(super) fn architect_transcribe_audio_attachment_and_queue(
    store: &pharos_runtime_architect::database::ArchitectStore,
    vault_path: &Path,
    root_key_file: &Path,
    storage_root: &Path,
    storage_ref: &str,
    task_id: i64,
    llm_vendor_id: &str,
    filename: &str,
    media_type: &str,
) -> Result<(), i32> {
    let state = architect_llm_vendor_state_in_store(store, llm_vendor_id).ok_or(69)?;
    let transcription_active = state.activation_status == "tested_active"
        || state.activation_status == "transcription_active";
    if !state.enabled || !transcription_active || state.secret_ref.is_empty() {
        return Err(65);
    }
    if state.llm_vendor_kind == "cloud" && !state.cloud_egress_allowed {
        return Err(65);
    }
    let allow_plaintext_local = state.llm_vendor_kind == "local";
    if state.base_url.starts_with("http://") && !allow_plaintext_local {
        return Err(65);
    }
    if state.base_url.starts_with("http://")
        && !pharos_runtime_architect::llm_vendor::url_uses_loopback_http(&state.base_url)
    {
        return Err(65);
    }
    let attachment_relative = architect_storage_ref_path(storage_ref).ok_or(66)?;
    let audio_path = storage_root.join(attachment_relative);
    let audio = stdfs::read(audio_path).map_err(|_| 66)?;
    if audio.is_empty() || audio.len() > 10 * 1024 * 1024 {
        return Err(65);
    }
    let mut secret = String::from_utf8(
        agent_vault::get_architect_runtime_llm_vendor_secret(
            vault_path,
            root_key_file,
            llm_vendor_id,
        )
        .map_err(|_| 66)?,
    )
    .map_err(|_| 66)?;
    let url = pharos_runtime_architect::llm_vendor::audio_transcriptions_url(&state.base_url)
        .ok_or(64)?;
    let boundary = format!(
        "pharos-architect-audio-{}",
        current_timestamp_utc().replace([':', '-'], "")
    );
    let payload = architect_audio_transcription_multipart(
        &boundary,
        &state.model_id,
        filename,
        media_type,
        &audio,
    )
    .ok_or(65)?;
    let content_type = format!("multipart/form-data; boundary={boundary}");
    let response = pharos_runtime_integrations::webhook::send_request_bytes(
        "POST",
        &url,
        Some(&content_type),
        &payload,
        &[("Authorization", format!("Bearer {}", secret.trim()))],
        pharos_runtime_integrations::webhook::WebhookLimits {
            connect_timeout: std::time::Duration::from_secs(5),
            operation_timeout: std::time::Duration::from_secs(60),
            max_response_bytes: 128 * 1024,
            allow_plaintext_local,
        },
    );
    secret.clear();
    let Some(response) = response else {
        return Err(69);
    };
    if !(200..300).contains(&response.status_code) {
        return Err(69);
    }
    let transcript_text = architect_parse_transcription_text(&response.body).ok_or(65)?;
    if transcript_text.len() < 8 {
        return Err(65);
    }
    pharos_runtime_architect::attachment_ingest::ingest_transcript_in_store(
        store,
        task_id,
        llm_vendor_id,
        &transcript_text,
    )
    .map_err(|_| 69)?;
    architect_queue_transcribed_task_in_store(store, task_id, &transcript_text)
}

/// Converts an Architect storage reference into a safe relative path below the configured storage root.
pub(super) fn architect_storage_ref_path(value: &str) -> Option<&Path> {
    let path = Path::new(value);
    if value.is_empty()
        || path.is_absolute()
        || path
            .components()
            .any(|component| !matches!(component, std::path::Component::Normal(_)))
    {
        return None;
    }
    Some(path)
}

/// Builds a bounded multipart/form-data payload for external LLM vendor audio transcription.
pub(super) fn architect_audio_transcription_multipart(
    boundary: &str,
    model_id: &str,
    filename: &str,
    media_type: &str,
    audio: &[u8],
) -> Option<Vec<u8>> {
    if boundary.len() > 80
        || model_id.is_empty()
        || model_id.len() > 128
        || filename.contains(['\r', '\n', '"'])
        || media_type.contains(['\r', '\n'])
        || media_type.len() > 120
    {
        return None;
    }
    let mut payload = Vec::with_capacity(audio.len().saturating_add(512));
    payload.extend_from_slice(
        format!(
            "--{boundary}\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\n{model_id}\r\n"
        )
        .as_bytes(),
    );
    payload.extend_from_slice(format!("--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{filename}\"\r\nContent-Type: {media_type}\r\n\r\n").as_bytes());
    payload.extend_from_slice(audio);
    payload.extend_from_slice(format!("\r\n--{boundary}--\r\n").as_bytes());
    Some(payload)
}

/// Extracts the transcript text field from an OpenAI-compatible audio transcription response.
pub(super) fn architect_parse_transcription_text(body: &str) -> Option<String> {
    let value: Value = serde_json::from_str(body).ok()?;
    let text = value.get("text").and_then(Value::as_str)?.trim();
    if text.is_empty() || text.len() > 8192 || text.contains('\0') {
        return None;
    }
    Some(text.to_owned())
}

pub(super) fn architect_upload_transcript_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    if let Err(response) = authorize_app_mutation(app, request, "/transcripts/upload") {
        return response;
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| agent_ingest::parse_task_id(&value).ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid task id\n");
    }
    let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id")
        .filter(|value| !value.trim().is_empty())
        .unwrap_or_else(|| "builtin".to_owned());
    let mut transcript_text =
        dynamic::request_form_value(request, "transcript_text").unwrap_or_default();
    if transcript_text.trim().is_empty()
        && let Some(content_type) = request.content_type.as_deref()
        && content_type
            .to_ascii_lowercase()
            .starts_with("multipart/form-data")
        && let Some(state_parent) = architect_state_parent(app)
    {
        let temp_root = state_parent.join("tmp/transcripts");
        if stdfs::create_dir_all(&temp_root).is_err() {
            return http_text_response(
                503,
                "Service Unavailable",
                "transcript storage unavailable\n",
            );
        }
        let nonce = dynamic::random_secret_hex(12).unwrap_or_else(|_| current_timestamp_utc());
        let body_path = temp_root.join(format!("{nonce}.multipart"));
        if fs::write_binary_file(&body_path, &request.body, 0o600).is_err() {
            return http_text_response(
                503,
                "Service Unavailable",
                "transcript storage unavailable\n",
            );
        }
        transcript_text =
            json_commands::dynamic_multipart_extract_text(content_type, &body_path, "transcript")
                .unwrap_or_default();
        let _ = stdfs::remove_file(&body_path);
    }
    match pharos_runtime_architect::attachment_ingest::ingest_transcript_in_store(
        &store,
        task_id,
        &llm_vendor_id,
        &transcript_text,
    ) {
        Ok(_) => architect_settings_review_response(app, request, method),
        Err(_) => http_text_response(422, "Unprocessable Entity", "transcript rejected\n"),
    }
}

/// Checks console task actions against the authenticated submitter or legacy project creator.
pub(super) fn architect_task_actor_allowed_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
) -> Result<(), Vec<u8>> {
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return Ok(());
    }
    let actor_id =
        active_session_user_id(app, request.cookie.as_deref()).map_err(database_error_response)?;
    if actor_id <= 0 {
        return Err(app_login_redirect(app, "/"));
    }
    let store = architect_task_store_for_app(app)
        .map_err(|_| http_text_response(503, "Service Unavailable", "database unavailable\n"))?;
    let owner = pharos_runtime_architect::task_ownership::task_owner(&store, task_id)
        .map_err(database_error_response)?;
    if owner != Some(actor_id) {
        return Err(http_text_response(
            403,
            "Forbidden",
            "task belongs to another user\n",
        ));
    }
    Ok(())
}

pub(super) fn architect_submit_builtin_task_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/");
    }
    if !match actor_has_route_policy(app, actor_id, "submit_builder_task") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let output_app_id = dynamic::request_form_value(request, "output_app_id").unwrap_or_default();
    if dynamic::request_form_value(request, "image_import_only").as_deref() == Some("true") {
        return match pharos_runtime_architect::task_repository::image_asset_task_for_actor(
            &store,
            &output_app_id,
            actor_id,
        ) {
            Ok(task_id) => http_json_response(
                200,
                "OK",
                &serde_json::json!({"task_id":task_id}).to_string(),
                method,
            ),
            Err(agent_bridge::AgentErrorKind::PolicyViolation) => {
                http_text_response(403, "Forbidden", "app id belongs to another user\n")
            }
            Err(_) => http_text_response(
                422,
                "Unprocessable Entity",
                "image collection unavailable\n",
            ),
        };
    }
    let llm_vendor_id = dynamic::request_form_value(request, "llm_vendor_id")
        .filter(|value| !value.trim().is_empty())
        .unwrap_or_else(|| "builtin".to_owned());
    let brief = dynamic::request_form_value(request, "brief").unwrap_or_default();
    #[cfg(not(target_os = "wasi"))]
    if llm_vendor_id == "chatgpt" {
        let authority =
            match pharos_runtime_architect::chatgpt::InstalledArchitect::from_runtime(app) {
                Ok(authority) => authority,
                Err(error) => return architect_chatgpt_http::connection_failure(error),
            };
        let model = dynamic::request_form_value(request, "chatgpt_model_id").unwrap_or_default();
        let runtime = match tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
        {
            Ok(runtime) => runtime,
            Err(_) => {
                return architect_chatgpt_http::connection_failure(
                    pharos_runtime_architect::chatgpt::ConnectionError::Storage,
                );
            }
        };
        let binding = match runtime.block_on(
            pharos_runtime_architect::chatgpt::service::prepare_task_binding(
                &authority, &store, actor_id, &model,
            ),
        ) {
            Ok(binding) => binding,
            Err(error) => return architect_chatgpt_http::connection_failure(error),
        };
        return match pharos_runtime_architect::task_repository::queue_or_retry_chatgpt_task(
            &store,
            &output_app_id,
            &brief,
            actor_id,
            &binding,
        ) {
            Ok(_) => architect_task_console_response(app, request, method),
            Err(agent_bridge::AgentErrorKind::LockBusy) => http_text_response(
                409,
                "Conflict",
                "The current task is running; wait before changing its account or model",
            ),
            Err(agent_bridge::AgentErrorKind::PolicyViolation) => {
                http_text_response(403, "Forbidden", "App id belongs to another user")
            }
            Err(_) => http_text_response(
                422,
                "Unprocessable Entity",
                "ChatGPT task could not be queued; refresh the connection and try again",
            ),
        };
    }
    match agent_architect::queue_or_retry_architect_task(
        &store,
        &output_app_id,
        &llm_vendor_id,
        &brief,
        actor_id,
    ) {
        Ok(_) => architect_task_console_response(app, request, method),
        Err(agent_bridge::AgentErrorKind::PolicyViolation) => {
            http_text_response(403, "Forbidden", "app id belongs to another user\n")
        }
        Err(_) => http_text_response(422, "Unprocessable Entity", "task creation unavailable\n"),
    }
}

/// Applies explicit CSV/page/image requests through the ordinary owner-checked source transaction.
fn architect_prepare_csv_page_bindings(
    app: &AppRuntime,
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
    actor_id: i64,
    generated_root: &Path,
    brief: &str,
) -> Result<(), String> {
    let bind_pages =
        pharos_runtime_architect::data_binding::requested_for_task(store, task_id, brief)?;
    let media_root = architect_media_root(app).ok_or("Image storage is unavailable.")?;
    if let Some(change) = pharos_runtime_architect::data_binding::prepare(
        store,
        task_id,
        actor_id,
        &media_root,
        bind_pages,
    )? {
        agent_architect::apply_architect_editor_source_edit(
            store,
            change,
            generated_root,
            actor_id,
        )
        .map_err(|error| format!("Validation failed: {error:?}; accepted source was preserved."))?;
    }
    store.insert("architect_task_event", BTreeMap::from([
        ("task_id".to_owned(), pharos_runtime_database::operations::WriteValue::Literal(serde_json::json!(task_id))),
        ("event_kind".to_owned(), pharos_runtime_database::operations::WriteValue::Literal(serde_json::json!("data_pages_populated"))),
        ("event_summary".to_owned(), pharos_runtime_database::operations::WriteValue::Literal(serde_json::json!(if bind_pages {"CSV tables linked to matching pages; image references resolved into app-owned source assets."} else {"Imported image history retained as portable app-owned static assets."}))),
        ("created_at".to_owned(), pharos_runtime_database::operations::WriteValue::Literal(serde_json::json!(current_timestamp_utc())))
    ])).map_err(|_|"Data binding evidence could not be saved.")?;
    Ok(())
}

pub(super) fn architect_auto_build_task_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid task id\n");
    }
    if pharos_runtime_architect::task_ownership::task_owner(&store, task_id)
        .ok()
        .flatten()
        != Some(actor_id)
    {
        return http_text_response(403, "Forbidden", "This task belongs to another user.\n");
    }
    if dynamic::request_form_value(request, "validate_existing_source").as_deref() == Some("true") {
        return match agent_architect::validate_existing_architect_task_source(
            &store,
            task_id,
            &generated_root,
            actor_id,
        ) {
            Ok(()) => architect_task_console_response(app, request, method),
            Err(error) => {
                eprintln!("Architect existing source validation failed: {error:?}");
                http_text_response(
                    422,
                    "Unprocessable Entity",
                    "Existing app source validation failed; accepted source was preserved.\n",
                )
            }
        };
    }
    let task_brief = match pharos_runtime_architect::task_repository::load_task(&store, task_id) {
        Ok(task) => task
            .context_evidence
            .sources
            .iter()
            .find(|source| source.source_id == "brief")
            .map(|source| source.selected_excerpt.clone())
            .unwrap_or_default(),
        Err(_) => {
            return http_text_response(
                422,
                "Unprocessable Entity",
                "Builder task is unavailable.\n",
            );
        }
    };
    if dynamic::request_form_value(request, "complete_csv_binding").as_deref() == Some("true") {
        if !pharos_runtime_architect::task_repository::load_task(&store, task_id)
            .is_ok_and(|task| task.task_status == "validated")
        {
            return http_text_response(
                409,
                "Conflict",
                "The app must finish its initial build before CSV data can be connected.\n",
            );
        }
        if let Err(message) = architect_prepare_csv_page_bindings(
            app,
            &store,
            task_id,
            actor_id,
            &generated_root,
            &task_brief,
        ) {
            return http_text_response(
                422,
                "Unprocessable Entity",
                &format!("CSV page binding failed: {message}\n"),
            );
        }
        if !architect_prepare_validated_generated_preview(&store, task_id) {
            return http_text_response(
                422,
                "Unprocessable Entity",
                "Imported-data preview is still preparing.\n",
            );
        }
        return architect_task_console_response(app, request, method);
    }
    let llm_vendor_vault =
        architect_vault_paths(app).map(|(vault_path, root_key_file)| {
            agent_architect::ArchitectLlmVendorVaultPaths {
                vault_path,
                root_key_file,
                chatgpt_authority:
                    pharos_runtime_architect::chatgpt::InstalledArchitect::from_runtime(app).ok(),
            }
        });
    let mut last_error = None;
    for attempt in 0..6 {
        match agent_architect::run_architect_task_to_validated(
            &store,
            task_id,
            &generated_root,
            llm_vendor_vault.clone(),
        ) {
            Ok(_) => {
                if let Err(message) = architect_prepare_csv_page_bindings(
                    app,
                    &store,
                    task_id,
                    actor_id,
                    &generated_root,
                    if dynamic::request_form_value(request, "defer_csv_binding").as_deref()
                        == Some("true")
                    {
                        ""
                    } else {
                        &task_brief
                    },
                ) {
                    if pharos_runtime_architect::task_repository::transition_task(
                        &store,
                        task_id,
                        "failed",
                        "data_binding_failed",
                        &message,
                        BTreeMap::new(),
                    )
                    .is_err()
                    {
                        return http_text_response(
                            503,
                            "Service Unavailable",
                            "Data binding failure could not be recorded.\n",
                        );
                    }
                    return http_text_response(
                        422,
                        "Unprocessable Entity",
                        &format!("CSV page binding failed: {message}\n"),
                    );
                }
                if !architect_prepare_validated_generated_preview(&store, task_id) {
                    return http_text_response(
                        422,
                        "Unprocessable Entity",
                        "generated app preview is still preparing\n",
                    );
                }
                return architect_task_console_response(app, request, method);
            }
            Err(
                error @ (agent_bridge::AgentErrorKind::LockBusy
                | agent_bridge::AgentErrorKind::InvalidIdentifier),
            ) if attempt < 5 => {
                last_error = Some(error);
                std::thread::sleep(Duration::from_millis(150 * (attempt + 1) as u64));
            }
            Err(error) => {
                last_error = Some(error);
                break;
            }
        }
    }
    let message = match last_error {
        Some(agent_bridge::AgentErrorKind::DatabaseConflict) => {
            "Automatic app build could not save a database change because a constraint or concurrent update was rejected. Check the app migrations; accepted source was preserved.\n".to_owned()
        }
        Some(agent_bridge::AgentErrorKind::LockBusy) => {
            "automatic app build database was busy\n".to_owned()
        }
        Some(agent_bridge::AgentErrorKind::InvalidIdentifier) => {
            "automatic app build could not read the queued task\n".to_owned()
        }
        Some(error) => {
            let failure = store
                .query_one(
                    "architect_task",
                    &["task_status", "validation_summary"],
                    pharos_runtime_database::operations::Predicate::Equal(
                        "id".to_owned(),
                        serde_json::json!(task_id),
                    ),
                )
                .ok()
                .flatten()
                .filter(|row| {
                    row.get("task_status").and_then(serde_json::Value::as_str) == Some("failed")
                })
                .and_then(|row| {
                    row.get("validation_summary")
                        .and_then(serde_json::Value::as_str)
                        .filter(|message| {
                            message.starts_with("LLM build failed:")
                                || message.starts_with("App requirements need attention:")
                                || message.starts_with("Architect app model synthesis failed:")
                                || message.starts_with("Source planning rejected:")
                                || message.starts_with("Reference source could not be read")
                        })
                        .map(str::to_owned)
                });
            failure
                .map(|message| format!("{message}\n"))
                .unwrap_or_else(|| format!("automatic app build unavailable: {error:?}\n"))
        }
        None => "automatic app build unavailable\n".to_owned(),
    };
    http_text_response(422, "Unprocessable Entity", &message)
}

pub(super) fn architect_approve_apply_plan_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid task id\n");
    }
    match agent_architect::approve_architect_task_plan(&store, task_id, &generated_root) {
        Ok(_) => {
            if !architect_prepare_validated_generated_preview(&store, task_id) {
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    "generated app preview is still preparing\n",
                );
            }
            architect_task_console_response(app, request, method)
        }
        Err(_) => http_text_response(422, "Unprocessable Entity", "plan apply unavailable\n"),
    }
}

pub(super) fn architect_delete_task_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let Some(state_parent) = architect_state_parent(app) else {
        return http_text_response(503, "Service Unavailable", "state unavailable\n");
    };
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid task id\n");
    }
    let export_root = state_parent.join("exports/source");
    let Some(media_root) = architect_media_root(app) else {
        return http_text_response(503, "Service Unavailable", "media storage unavailable\n");
    };
    if stdfs::create_dir_all(&export_root).is_err() || stdfs::create_dir_all(&media_root).is_err() {
        return http_text_response(503, "Service Unavailable", "task storage unavailable\n");
    }
    let delete_task_result =
        pharos_runtime_architect::project_state::delete_architect_task_in_store(
            &store,
            task_id,
            &generated_root,
            &export_root,
            &media_root,
        );
    match delete_task_result {
        Ok(_) => architect_task_console_response(app, request, method),
        Err(error) => {
            eprintln!("architect task {task_id} deletion failed: {error:?}");
            http_text_response(422, "Unprocessable Entity", "task delete unavailable\n")
        }
    }
}

pub(super) fn architect_generated_app_preview_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let task_id = request_query_value(&request.target, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return http_route_redirect("/architect/");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let connection_namespace =
        match pharos_runtime_architect::task_ownership::owned_preview_namespace(
            &store, task_id, actor_id,
        ) {
            Ok(namespace) => namespace,
            Err(error) => return database_error_response(error),
        };
    let generated_root = architect_generated_source_root(app);
    let accepted_editor_root = architect_current_editor_preview_root(&store, task_id);
    let has_accepted_editor_version = accepted_editor_root.is_some();
    let (output_app_id, preview_root, preview_workspace) =
        if let Some((output_app_id, current_editor_root)) = accepted_editor_root {
            let current_editor_workspace = architect_editor_preview_workspace(&current_editor_root);
            if !architect_sync_editor_preview_config(&store, task_id, &current_editor_workspace) {
                return http_text_response(
                    503,
                    "Service Unavailable",
                    "preview configuration unavailable\n",
                );
            }
            (output_app_id, current_editor_root, current_editor_workspace)
        } else {
            let output_app_id = store
                .query_one(
                    "architect_task",
                    &["output_app_id"],
                    pharos_runtime_database::operations::Predicate::Equal(
                        "id".to_owned(),
                        serde_json::json!(task_id),
                    ),
                )
                .ok()
                .flatten()
                .and_then(|task| {
                    task.get("output_app_id")
                        .and_then(Value::as_str)
                        .map(str::to_owned)
                });
            let Some(output_app_id) = output_app_id else {
                return http_text_response(404, "Not Found", "generated app preview unavailable\n");
            };
            let review_workspace_path = architect_validated_task_preview_info(&store, task_id)
                .map(|(_, review_workspace_path)| review_workspace_path);
            let generated_source_root = generated_root
                .as_ref()
                .map(|root| root.join(&output_app_id))
                .filter(|root| root.join("pharos.app.yml").is_file());
            let preview_workspace = review_workspace_path
                .as_deref()
                .map(PathBuf::from)
                .filter(|path| path.is_dir())
                .or_else(|| {
                    generated_source_root
                        .as_ref()
                        .and_then(|root| root.parent().map(Path::to_path_buf))
                })
                .unwrap_or_else(|| PathBuf::from("."));
            let built_preview_root = preview_workspace
                .join("dist")
                .join("apps")
                .join(&output_app_id);
            let source_preview_root = preview_workspace.join("apps").join(&output_app_id);
            let preview_root = if built_preview_root.join("pharos.app.json").is_file() {
                built_preview_root
            } else if source_preview_root.join("pharos.app.yml").is_file() {
                source_preview_root
            } else if let Some(root) = generated_source_root {
                root
            } else {
                return http_text_response(404, "Not Found", "generated app preview unavailable\n");
            };
            (output_app_id, preview_root, preview_workspace)
        };
    let preview_path = request_query_value(&request.target, "path")
        .unwrap_or_else(|| "/".to_owned())
        .trim()
        .to_owned();
    let base_path = format!("/{}", output_app_id.replace('_', "-"));
    let route_path = if preview_path.is_empty() || preview_path == base_path {
        "/".to_owned()
    } else if let Some(stripped) = preview_path.strip_prefix(&base_path) {
        stripped.to_owned()
    } else {
        preview_path.clone()
    };
    let preview_root = architect_ready_preview_asset_root(
        &preview_root,
        &preview_workspace,
        &output_app_id,
        &route_path,
        method,
    )
    .or_else(|| {
        architect_prepared_preview_root_if_ready(&preview_root, &preview_workspace, &output_app_id)
    })
    .or_else(|| {
        if has_accepted_editor_version || architect_task_is_validated(&store, task_id) {
            architect_materialized_preview_root(&preview_root, &preview_workspace, &output_app_id)
        } else {
            None
        }
    })
    .unwrap_or_else(|| preview_root.to_path_buf());
    if (route_path.starts_with("/media/images/")
        || request
            .content_type
            .as_deref()
            .is_some_and(|value| value.starts_with("multipart/form-data")))
        && !architect_configure_preview_media(&preview_root, &preview_workspace, &output_app_id)
    {
        return http_text_response(
            503,
            "Service Unavailable",
            "preview media storage unavailable\n",
        );
    }
    if route_path.starts_with("/media/architect-preview/") {
        return architect_preview_image_response(app, &route_path, method);
    }
    if route_path.starts_with("/static/") || route_path.starts_with("/media/") {
        let response = pharos_runtime_static::artifact_server::serve_artifact_request(
            &preview_root,
            method,
            &route_path,
        );
        return architect_generated_preview_static_response(
            response,
            task_id,
            &output_app_id,
            &route_path,
            method,
        );
    }
    let Some(mut preview_app) =
        architect_generated_preview_app_runtime(&preview_root, &preview_workspace, &output_app_id)
    else {
        return http_text_response(404, "Not Found", "generated app preview unavailable\n");
    };
    preview_app.connection_namespace = Some(connection_namespace);
    super::event_discovery::register_preview(&preview_app);
    let mut preview_request = request.clone();
    // Older UCAL exports embed the original mount in their public-view links.
    let route_path = if route_path.starts_with("/ucal/b/")
        && matched_app_route(&preview_app, method, &route_path).is_none()
        && matched_app_route(&preview_app, method, &route_path[5..]).is_some()
    {
        route_path[5..].to_owned()
    } else {
        route_path
    };
    let route_path = architect_preview_home_route(&preview_app, method, route_path);
    preview_request.target = match architect_preview_query_target(&route_path, &request.target) {
        Some(target) => target,
        None => return http_text_response(400, "Bad Request", "Invalid preview query.\n"),
    };
    let preview_cookie_name = format!("pharos_preview_{task_id}");
    let preview_token = dynamic::dynamic_cookie_value(
        request.cookie.as_deref().unwrap_or_default(),
        &preview_cookie_name,
    );
    preview_request.cookie = request.cookie.as_deref().map(|cookies| {
        let mut values = cookies
            .split(';')
            .map(str::trim)
            .filter(|cookie| !cookie.starts_with("pharos_session="))
            .map(str::to_owned)
            .collect::<Vec<_>>();
        if let Some(token) = preview_token {
            values.push(format!("pharos_session={token}"));
        }
        values.join("; ")
    });
    if let Some(response) = architect_preview_private_asset_response(&preview_app, &preview_request)
    {
        return response;
    }
    #[cfg(not(target_os = "wasi"))]
    if let Some(response) = super::social_connections::response_at(
        &preview_app,
        &preview_request,
        &preview_request.target,
        Some(&format!(
            "{}/apps/view?task_id={task_id}&path=%2F__pharos%2Fsocial%2F{{provider}}%2Fcallback",
            app.base_path.as_deref().unwrap_or("/architect")
        )),
    ) {
        return rewrite_architect_generated_preview_response(
            response,
            app,
            &preview_app,
            &output_app_id,
            task_id,
            &preview_request,
            &dynamic::csrf_token_for_response(request.cookie.as_deref()),
        );
    }
    if !matches!(method, "GET" | "HEAD")
        && let Err(response) = authorize_app_mutation(
            &preview_app,
            &preview_request,
            preview_request.target.split('?').next().unwrap_or("/"),
        )
    {
        return rewrite_architect_generated_preview_response(
            response,
            app,
            &preview_app,
            &output_app_id,
            task_id,
            &preview_request,
            &dynamic::csrf_token_for_response(request.cookie.as_deref()),
        );
    }
    let Some(response) = app_declarative_route_response(&preview_app, &preview_request) else {
        return http_text_response(404, "Not Found", "generated app route unavailable\n");
    };
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    rewrite_architect_generated_preview_response(
        response,
        app,
        &preview_app,
        &output_app_id,
        task_id,
        &preview_request,
        &csrf_token,
    )
}

/// Serves entitlement-authorized preview downloads through the normal private-asset boundary.
fn architect_preview_private_asset_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
) -> Option<Vec<u8>> {
    if !matches!(request.method.as_str(), "GET" | "HEAD") {
        return None;
    }
    let actor = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(actor) => actor,
        Err(error) => return Some(database_error_response(error)),
    };
    let path = request.target.split('?').next().unwrap_or("/");
    let asset = match feature_runtime::authorize_private_asset(app, path, actor) {
        Ok(Some(asset)) => asset,
        Ok(None) => return None,
        Err(_) => {
            return Some(http_text_response(
                503,
                "Service Unavailable",
                "private asset authorization unavailable\n",
            ));
        }
    };
    let range = dynamic::request_header_value(request, "range");
    let if_range = dynamic::request_header_value(request, "if-range");
    let stream = 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) => stream,
        Err(error) => return Some(http_stream_error(error, &request.method)),
    };
    // Architect rewrites buffered page responses; binary assets bypass that text-only step.
    let bound = app.resource_budgets.max_response_bytes.min(8 * 1024 * 1024);
    if stream.content_length > bound as u64 {
        return Some(http_text_response(
            413,
            "Payload Too Large",
            "preview download exceeds response budget\n",
        ));
    }
    let mut response = Vec::new();
    let capacity = if request.method == "HEAD" {
        4096
    } else {
        stream.content_length as usize + 4096
    };
    if response.try_reserve(capacity).is_err() {
        return Some(http_text_response(
            503,
            "Service Unavailable",
            "preview download unavailable\n",
        ));
    }
    write_stream_response(&mut response, &stream, &request.method);
    Some(response)
}

/// Resolves the default View link to the declared home page without changing explicit nested paths.
fn architect_preview_home_route(app: &AppRuntime, method: &str, path: String) -> String {
    if path != "/"
        || !matches!(method, "GET" | "HEAD")
        || matched_app_route(app, method, &path).is_some()
    {
        return path;
    }
    app.application_ir
        .as_ref()
        .and_then(|ir| {
            ir.routes
                .values()
                .find(|route| {
                    route.kind == "page"
                        && route.method == "GET"
                        && route
                            .page_id
                            .as_ref()
                            .is_some_and(|id| id.as_str() == "home")
                })
                .map(|route| route.path.clone())
        })
        .unwrap_or(path)
}

/// Configures only a materialized artifact to use stable, isolated preview media storage.
fn architect_configure_preview_media(root: &Path, workspace: &Path, app_id: &str) -> bool {
    let is_artifact = root
        .components()
        .any(|part| part.as_os_str() == ".preview-artifacts")
        || root.starts_with(workspace.join("dist").join("apps"));
    if !is_artifact || !root.join("pharos.app.json").is_file() {
        return false;
    }
    let media = super::architect_preview_accounts::state_root(workspace)
        .join(app_id)
        .join("media");
    if !media.is_absolute() || media.starts_with(root) {
        return false;
    }
    let path = root.join("app.conf");
    let Ok(text) = stdfs::read_to_string(&path) else {
        return false;
    };
    if text.len() > 1024 * 1024 {
        return false;
    }
    let setting = format!("MEDIA_ROOT={}", media.display());
    let mut found = false;
    let mut lines = Vec::new();
    for line in text.lines() {
        if line
            .split_once('=')
            .is_some_and(|(key, _)| key.trim() == "MEDIA_ROOT")
        {
            if !found {
                lines.push(setting.clone());
                found = true;
            }
        } else {
            lines.push(line.to_owned());
        }
    }
    if !found {
        lines.push(setting);
    }
    let updated = format!("{}\n", lines.join("\n"));
    if updated == text {
        return true;
    }
    super::fs::write_file_within(root, &path, updated.as_bytes(), 0o600).is_ok()
}

pub(super) fn architect_generated_preview_app_runtime(
    preview_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> Option<AppRuntime> {
    let manifest = read_source_manifest_value(preview_root).ok()?;
    let application_ir =
        pharos_runtime_core::application_ir::compile_application_ir(preview_root, &manifest)
            .ok()?;
    let runtime_conf_path = preview_workspace.join("runtime.conf");
    let preview = AppRuntime {
        is_editor_preview: true,
        application_ir: Some(std::sync::Arc::new(application_ir)),
        artifact_dir: Some(preview_root.to_string_lossy().into_owned()),
        app_id: Some(output_app_id.to_owned()),
        app_root: Some(preview_root.to_string_lossy().into_owned()),
        build_dir: preview_root
            .parent()
            .map(|path| path.to_string_lossy().into_owned()),
        host_profile: Some("dynamic-app".to_owned()),
        state_path: Some(
            super::architect_preview_accounts::state_root(preview_workspace)
                .join(output_app_id)
                .join("runtime-state.json")
                .to_string_lossy()
                .into_owned(),
        ),
        base_path: Some(format!("/{}", output_app_id.replace('_', "-"))),
        log_path: Some(
            preview_workspace
                .join("logs")
                .join(format!("{output_app_id}.log"))
                .to_string_lossy()
                .into_owned(),
        ),
        log_format: Some("service".to_owned()),
        error_report_path: Some(String::new()),
        log_level: Some("WARN".to_owned()),
        runtime_conf_path: Some(runtime_conf_path.to_string_lossy().into_owned()),
        ..AppRuntime::default()
    };
    Some(preview)
}

fn rewrite_architect_generated_preview_response(
    response: Vec<u8>,
    architect_app: &AppRuntime,
    preview_app: &AppRuntime,
    output_app_id: &str,
    task_id: i64,
    preview_request: &http::HttpRequest,
    csrf_token: &str,
) -> Vec<u8> {
    let method = preview_request.method.as_str();
    let Some(separator) = response.windows(4).position(|bytes| bytes == b"\r\n\r\n") else {
        return response;
    };
    let Ok(headers) = std::str::from_utf8(&response[..separator]) else {
        return http_text_response(
            500,
            "Internal Server Error",
            "generated app preview failed\n",
        );
    };
    let body = &response[separator + 4..];
    let headers = headers
        .lines()
        .map(|line| {
            if line.starts_with("Set-Cookie: pharos_session=") {
                return line
                    .replacen("pharos_session=", &format!("pharos_preview_{task_id}="), 1)
                    .replace(
                        &format!("Path=/{}", output_app_id.replace('_', "-")),
                        "Path=/architect",
                    );
            }
            if let Some((name, value)) = line.split_once(':')
                && (name.eq_ignore_ascii_case("location")
                    || name.eq_ignore_ascii_case("hx-redirect"))
                && let Some(location) =
                    architect_preview_redirect_location(value.trim(), output_app_id, task_id)
            {
                return format!("{name}: {location}");
            }
            line.to_owned()
        })
        .collect::<Vec<_>>()
        .join("\r\n");
    let is_html_response = headers.lines().any(|line| {
        line.split_once(':').is_some_and(|(name, value)| {
            name.trim().eq_ignore_ascii_case("content-type")
                && value.trim().to_ascii_lowercase().starts_with("text/html")
        })
    });
    if method == "HEAD" || !is_html_response {
        let mut rewritten = Vec::with_capacity(headers.len() + 4 + body.len());
        rewritten.extend_from_slice(headers.as_bytes());
        rewritten.extend_from_slice(b"\r\n\r\n");
        rewritten.extend_from_slice(body);
        return rewritten;
    }
    let Ok(body) = std::str::from_utf8(body) else {
        return http_text_response(
            500,
            "Internal Server Error",
            "generated app preview failed\n",
        );
    };
    let html = rewrite_architect_generated_preview_forms(
        &rewrite_architect_generated_preview_urls(body, output_app_id, task_id),
        preview_app,
        task_id,
    );
    let route = matched_app_route(
        preview_app,
        method,
        preview_request.target.split('?').next().unwrap_or("/"),
    );
    let source_template = route
        .as_ref()
        .and_then(|route| route.get("page_id"))
        .and_then(Value::as_str)
        .and_then(|page_id| {
            let root = Path::new(
                preview_app
                    .artifact_dir
                    .as_deref()
                    .or(preview_app.app_root.as_deref())?,
            );
            let declaration = json_commands::declared_page_relative_path(root, page_id)?;
            let page = json_commands::json_doc_load_file(&root.join(declaration))?;
            page.get("template_file")
                .and_then(Value::as_str)
                .map(str::to_owned)
        })
        .unwrap_or_default();
    let html = add_architect_edit_toolbar(
        &html,
        architect_app,
        task_id,
        csrf_token,
        preview_app,
        &source_template,
    );
    let mut rewritten_headers = Vec::new();
    for line in headers.lines() {
        if line.to_ascii_lowercase().starts_with("content-length:") {
            rewritten_headers.push(format!("Content-Length: {}", html.len()));
        } else {
            rewritten_headers.push(line.to_owned());
        }
    }
    format!("{}\r\n\r\n{}", rewritten_headers.join("\r\n"), html).into_bytes()
}

/// Keeps redirects within the selected app preview without absorbing another app or origin.
fn architect_preview_redirect_location(
    location: &str,
    output_app_id: &str,
    task_id: i64,
) -> Option<String> {
    let base = format!("/{}", output_app_id.replace('_', "-"));
    let suffix = location.strip_prefix(&base)?;
    let path = if suffix.is_empty() {
        "/".to_owned()
    } else if suffix.starts_with('/') && !suffix.starts_with("//") {
        suffix.to_owned()
    } else if suffix.starts_with('?') {
        format!("/{suffix}")
    } else {
        return None;
    };
    Some(format!(
        "/architect/app/edit?task_id={task_id}&app_id={}&path={}",
        json_commands::url_encode_query_component(output_app_id),
        json_commands::url_encode_query_component(&path)
    ))
}

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

    /// Binary downloads retain exact bytes while preview session cookies keep their isolation.
    #[test]
    fn preview_binary_download_preserves_body_and_scopes_cookie() {
        let body = [0x50, 0x4b, 0xff, 0xfe, 0, 0x81];
        let mut response = b"HTTP/1.1 200 OK\r\nContent-Type: application/zip\r\nContent-Length: 6\r\nSet-Cookie: pharos_session=controlled; Path=/commerce-app; HttpOnly\r\n\r\n".to_vec();
        response.extend_from_slice(&body);
        let app = AppRuntime::default();
        let request = http::HttpRequest {
            method: "GET".into(),
            ..Default::default()
        };
        let rewritten = rewrite_architect_generated_preview_response(
            response,
            &app,
            &app,
            "commerce_app",
            306,
            &request,
            "controlled-csrf",
        );
        let separator = rewritten
            .windows(4)
            .position(|bytes| bytes == b"\r\n\r\n")
            .unwrap();
        assert_eq!(&rewritten[separator + 4..], &body);
        let headers = std::str::from_utf8(&rewritten[..separator]).unwrap();
        assert!(headers.contains("pharos_preview_306=controlled; Path=/architect; HttpOnly"));
        assert!(headers.contains("Content-Length: 6"));
    }

    /// Tests text generation with the configured model instead of accepting model-catalog access as inference readiness.
    #[test]
    fn llm_connection_probe_exercises_generation_without_temperature_override() {
        for vendor in ["openai_compatible", "ollama_compatible", "nvidia_nim"] {
            let state = ArchitectLlmVendorState {
                llm_vendor_kind: "cloud".to_owned(),
                model_id: "configured-model".to_owned(),
                base_url: "https://provider.example/v1".to_owned(),
                enabled: true,
                cloud_egress_allowed: true,
                activation_status: "tested_active".to_owned(),
                secret_ref: "saved".to_owned(),
            };
            let (method, url, content_type, body, _, _) =
                architect_llm_vendor_connection_request(vendor, &state, "test-credential").unwrap();
            assert_eq!(method, "POST");
            assert_eq!(url, "https://provider.example/v1/chat/completions");
            assert_eq!(content_type, Some("application/json"));
            let payload: serde_json::Value = serde_json::from_str(&body).unwrap();
            assert_eq!(payload["model"], "configured-model");
            assert!(payload["messages"].is_array());
            assert!(payload.get("temperature").is_none());
        }
    }

    /// Preserves nested login query values and rejects cross-app and external locations.
    #[test]
    fn preview_login_redirect_keeps_app_scope_and_nested_query() {
        let redirect = architect_preview_redirect_location(
            "/complete-app/accounts/login/?next=/private?tab=1&sort=asc",
            "complete_app",
            12,
        )
        .unwrap();
        assert_eq!(
            request_query_value(&redirect, "path").as_deref(),
            Some("/accounts/login/?next=/private?tab=1&sort=asc")
        );
        assert_eq!(
            request_query_value(&redirect, "app_id").as_deref(),
            Some("complete_app")
        );
        assert!(
            architect_preview_redirect_location("https://other.example/login", "complete_app", 12)
                .is_none()
        );
        assert!(
            architect_preview_redirect_location("/complete-app-other/login", "complete_app", 12)
                .is_none()
        );
        assert!(
            architect_preview_redirect_location("/complete-app//other.example", "complete_app", 12)
                .is_none()
        );
    }
}

pub(super) fn architect_preview_artifact_root(
    preview_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> PathBuf {
    let preview_key_base = preview_root
        .file_name()
        .and_then(|name| name.to_str())
        .filter(|name| !name.is_empty())
        .unwrap_or("source");
    let preview_key_digest =
        dynamic::hex_digest(&Sha256::digest(preview_root.to_string_lossy().as_bytes()));
    let preview_key = format!(
        "{}-{}",
        preview_key_base
            .chars()
            .filter(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-'))
            .take(48)
            .collect::<String>(),
        &preview_key_digest[..16]
    );
    preview_workspace
        .join(".preview-artifacts")
        .join(preview_key)
        .join("apps")
        .join(output_app_id)
}

/// Shares a build lock only while requests are preparing the same editable preview artifact.
fn architect_preview_artifact_lock(root: &Path) -> std::sync::Arc<std::sync::Mutex<()>> {
    type Locks = std::collections::HashMap<PathBuf, std::sync::Weak<std::sync::Mutex<()>>>;
    static LOCKS: std::sync::OnceLock<std::sync::Mutex<Locks>> = std::sync::OnceLock::new();
    let mut locks = LOCKS
        .get_or_init(|| std::sync::Mutex::new(Locks::new()))
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    locks.retain(|_, lock| lock.strong_count() > 0);
    if let Some(lock) = locks.get(root).and_then(std::sync::Weak::upgrade) {
        return lock;
    }
    let lock = std::sync::Arc::new(std::sync::Mutex::new(()));
    locks.insert(root.to_path_buf(), std::sync::Arc::downgrade(&lock));
    lock
}

pub(super) fn architect_materialized_preview_root(
    preview_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> Option<PathBuf> {
    if preview_root.join("pharos.app.json").is_file() {
        return Some(preview_root.to_path_buf());
    }
    if !preview_root.join("pharos.app.yml").is_file() {
        return None;
    }
    let artifact_root =
        architect_preview_artifact_root(preview_root, preview_workspace, output_app_id);
    let lock = architect_preview_artifact_lock(&artifact_root);
    let _preparation = lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let build_dir = artifact_root.parent().and_then(Path::parent)?.to_path_buf();
    let artifact_manifest = artifact_root.join("pharos.app.json");
    if artifact_manifest.is_file()
        && !architect_preview_source_is_newer_than_artifact(preview_root, &artifact_manifest)
    {
        return architect_prepare_preview_database(
            &artifact_root,
            preview_workspace,
            output_app_id,
        )
        .then_some(artifact_root);
    }
    build_app_from_root(preview_root, &build_dir).ok()?;
    if artifact_manifest.is_file() {
        architect_prepare_preview_database(&artifact_root, preview_workspace, output_app_id)
            .then_some(artifact_root)
    } else {
        None
    }
}

pub(super) fn architect_prepare_preview_database(
    app_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> bool {
    if !app_root.join("pharos.app.json").is_file() && !app_root.join("pharos.app.yml").is_file() {
        return false;
    }
    let runtime_conf = preview_workspace.join("runtime.conf");
    if !runtime_conf.is_file() {
        return false;
    }
    database::dynamic_runtime_prepare(app_root, Some(&runtime_conf), Some(output_app_id)) == 0
        && super::architect_preview_accounts::prepare(app_root, preview_workspace, output_app_id)
            .is_ok()
}

/// Serves public files from an accepted fresh artifact without repeating database migrations or account preparation.
fn architect_ready_preview_asset_root(
    preview_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
    path: &str,
    method: &str,
) -> Option<PathBuf> {
    if !matches!(method, "GET" | "HEAD")
        || !(path.starts_with("/static/") || path.starts_with("/media/"))
        || !architect_preview_artifact_ready(preview_root, preview_workspace, output_app_id)
    {
        return None;
    }
    Some(if preview_root.join("pharos.app.json").is_file() {
        preview_root.to_path_buf()
    } else {
        architect_preview_artifact_root(preview_root, preview_workspace, output_app_id)
    })
}

pub(super) fn architect_prepared_preview_root_if_ready(
    preview_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> Option<PathBuf> {
    if preview_root.join("pharos.app.json").is_file() {
        return architect_prepare_preview_database(preview_root, preview_workspace, output_app_id)
            .then(|| preview_root.to_path_buf());
    }
    let artifact_root =
        architect_preview_artifact_root(preview_root, preview_workspace, output_app_id);
    let lock = architect_preview_artifact_lock(&artifact_root);
    let _preparation = lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let artifact_manifest = artifact_root.join("pharos.app.json");
    if artifact_manifest.is_file()
        && !architect_preview_source_is_newer_than_artifact(preview_root, &artifact_manifest)
    {
        architect_prepare_preview_database(&artifact_root, preview_workspace, output_app_id)
            .then_some(artifact_root)
    } else {
        None
    }
}

pub(super) fn architect_preview_artifact_ready(
    preview_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> bool {
    if preview_root.join("pharos.app.json").is_file() {
        return true;
    }
    let artifact_manifest =
        architect_preview_artifact_root(preview_root, preview_workspace, output_app_id)
            .join("pharos.app.json");
    artifact_manifest.is_file()
        && !architect_preview_source_is_newer_than_artifact(preview_root, &artifact_manifest)
}

pub(super) fn architect_editor_preview_workspace(preview_root: &Path) -> PathBuf {
    preview_root
        .parent()
        .map(Path::to_path_buf)
        .unwrap_or_else(|| preview_root.to_path_buf())
}

/// Gives an editor version the same backend and isolated data namespace as its validated task.
pub(super) fn architect_sync_editor_preview_config(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
    editor_workspace: &Path,
) -> bool {
    let Ok(Some((app_id, review_workspace))) =
        pharos_runtime_architect::task_repository::accepted_preview_configuration(store, task_id)
    else {
        return false;
    };
    pharos_runtime_architect::lifecycle_validation::synchronize_editor_preview_config(
        editor_workspace,
        &app_id,
        &review_workspace,
        store.config(),
    )
    .is_ok()
}

pub(super) fn architect_prepare_validated_generated_preview(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
) -> bool {
    let Some((output_app_id, preview_root)) = architect_current_editor_preview_root(store, task_id)
    else {
        return false;
    };
    let preview_workspace = architect_editor_preview_workspace(&preview_root);
    if !architect_sync_editor_preview_config(store, task_id, &preview_workspace) {
        return false;
    }
    architect_materialized_preview_root(&preview_root, &preview_workspace, &output_app_id)
        .is_some_and(|artifact_root| artifact_root.join("pharos.app.json").is_file())
}

pub(super) fn architect_guard_preview_actions(
    app: &AppRuntime,
    html: &str,
    prepare_missing: bool,
) -> String {
    let Ok(store) = architect_task_store_for_app(app) else {
        return html.to_owned();
    };
    let task_ids: std::collections::BTreeSet<i64> = html
        .split("?task_id=")
        .skip(1)
        .filter_map(|part| part.split(['&', '"']).next()?.parse().ok())
        .filter(|id| *id > 0)
        .take(65)
        .collect();
    let metadata = match pharos_runtime_architect::task_repository::task_action_metadata(
        &store,
        &task_ids.into_iter().collect::<Vec<_>>(),
    ) {
        Ok(metadata) => metadata,
        Err(error) => {
            eprintln!("Architect task actions unavailable: {error:?}");
            std::collections::BTreeMap::new()
        }
    };
    let guarded = architect_guard_task_action_anchors(
        app,
        &store,
        &metadata,
        html,
        prepare_missing,
        "<a class=\"icon-action-button secondary-button\" href=\"/architect/app/edit?task_id=",
        ArchitectTaskActionKind::Preview,
    );
    architect_guard_task_action_anchors(
        app,
        &store,
        &metadata,
        &guarded,
        prepare_missing,
        "<a class=\"icon-action-button secondary-button\" href=\"/architect/exports/download?task_id=",
        ArchitectTaskActionKind::Export,
    )
}

/// Identifies which task-card action is being guarded by validation state.
enum ArchitectTaskActionKind {
    Preview,
    Export,
}

/// Replaces task-card action anchors with inert declarative placeholders until the task state allows the action.
fn architect_guard_task_action_anchors(
    app: &AppRuntime,
    store: &pharos_runtime_architect::database::ArchitectStore,
    metadata: &std::collections::BTreeMap<
        i64,
        pharos_runtime_architect::task_repository::TaskActionMetadata,
    >,
    html: &str,
    prepare_missing: bool,
    needle: &str,
    action_kind: ArchitectTaskActionKind,
) -> String {
    let mut out = String::with_capacity(html.len());
    let mut rest = html;
    while let Some(index) = rest.find(needle) {
        out.push_str(&rest[..index]);
        let anchor_start = &rest[index..];
        let task_start = index + needle.len();
        let task_rest = &rest[task_start..];
        let task_end = task_rest
            .find('&')
            .or_else(|| task_rest.find('\"'))
            .unwrap_or(0);
        let task_id = task_rest[..task_end].parse::<i64>().unwrap_or(0);
        let Some(anchor_end) = anchor_start.find("</a>").map(|value| value + "</a>".len()) else {
            out.push_str(anchor_start);
            return out;
        };
        let anchor = &anchor_start[..anchor_end];
        let task = metadata.get(&task_id);
        let task_validated = task.is_some_and(|task| task.validated);
        match action_kind {
            ArchitectTaskActionKind::Export if task_validated => out.push_str(anchor),
            ArchitectTaskActionKind::Preview => {
                let preview_ready = task_validated
                    && (task.is_some_and(|task| {
                        let Some(root) = task.source_root.as_deref() else {
                            return false;
                        };
                        let workspace = architect_editor_preview_workspace(root);
                        pharos_runtime_architect::lifecycle_validation::synchronize_editor_preview_config(
                            &workspace, &task.app_id, &task.review_workspace, store.config(),
                        ).is_ok()
                            && architect_preview_artifact_ready(root, &workspace, &task.app_id)
                    }) || (prepare_missing
                        && architect_prepare_validated_generated_preview(store, task_id)));
                if preview_ready {
                    out.push_str(anchor);
                } else if task_validated {
                    out.push_str(
                        &architect_fragment_html(
                            app,
                            "templates/fragments/preview_pending_button.html",
                            &serde_json::json!({}),
                        )
                        .unwrap_or_default(),
                    );
                } else {
                    out.push_str(
                        &architect_fragment_html(
                            app,
                            "templates/fragments/preview_unavailable_spacer.html",
                            &serde_json::json!({}),
                        )
                        .unwrap_or_default(),
                    );
                }
            }
            ArchitectTaskActionKind::Export => out.push_str(
                &architect_fragment_html(
                    app,
                    "templates/fragments/preview_unavailable_spacer.html",
                    &serde_json::json!({}),
                )
                .unwrap_or_default(),
            ),
        }
        rest = &anchor_start[anchor_end..];
    }
    out.push_str(rest);
    out
}

pub(super) fn architect_task_is_validated(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
) -> bool {
    use pharos_runtime_database::operations::Predicate;
    store
        .query_one(
            "architect_task",
            &["task_status"],
            Predicate::Equal("id".to_owned(), serde_json::json!(task_id)),
        )
        .ok()
        .flatten()
        .and_then(|row| {
            row.get("task_status")
                .and_then(Value::as_str)
                .map(str::to_owned)
        })
        .is_some_and(|status| status == "validated")
}

pub(super) fn architect_preview_source_is_newer_than_artifact(
    source_root: &Path,
    artifact_path: &Path,
) -> bool {
    let artifact_modified = stdfs::metadata(artifact_path)
        .and_then(|metadata| metadata.modified())
        .unwrap_or(SystemTime::UNIX_EPOCH);
    let mut stack = vec![source_root.to_path_buf()];
    while let Some(path) = stack.pop() {
        let Ok(entries) = stdfs::read_dir(&path) else {
            return true;
        };
        for entry in entries.flatten() {
            let entry_path = entry.path();
            let file_name = entry_path
                .file_name()
                .and_then(|name| name.to_str())
                .unwrap_or_default();
            if matches!(file_name, ".git" | ".preview-artifacts" | "target" | "var") {
                continue;
            }
            let Ok(metadata) = stdfs::symlink_metadata(&entry_path) else {
                return true;
            };
            if metadata.is_dir() {
                stack.push(entry_path);
                continue;
            }
            if metadata
                .modified()
                .map(|modified| modified > artifact_modified)
                .unwrap_or(true)
            {
                return true;
            }
        }
    }
    false
}

pub(super) fn architect_generated_preview_static_response(
    mut response: artifact_server::StaticResponse,
    task_id: i64,
    output_app_id: &str,
    route_path: &str,
    method: &str,
) -> Vec<u8> {
    if method != "HEAD"
        && response.status_code == 200
        && response.content_type.starts_with("text/css")
        && let Ok(css) = String::from_utf8(response.body.clone())
    {
        let rewritten =
            rewrite_architect_generated_preview_css_urls(&css, task_id, output_app_id, route_path);
        response.content_length = rewritten.len() as u64;
        response.body = rewritten.into_bytes();
    }
    http_static_response(response, method)
}

fn add_architect_edit_toolbar(
    html: &str,
    architect_app: &AppRuntime,
    task_id: i64,
    csrf_token: &str,
    preview_app: &AppRuntime,
    source_template: &str,
) -> String {
    let Some(insert_at) = architect_preview_body_content_start(html) else {
        return html.to_owned();
    };
    let Some(artifact_root) = architect_app.artifact_dir.as_deref().map(Path::new) else {
        return html.to_owned();
    };
    let preview_overrides = architect_preview_overrides_json(preview_app);
    let Some(toolbar) = json_commands::template_render_file(
        &artifact_root.join("templates/fragments/edit_toolbar.html"),
        &serde_json::json!({
            "task_id": task_id,
            "csrf_token": csrf_token,
            "preview_overrides": architect_preview_script_json_text(&preview_overrides),
            "preview_source_template": json_commands::html_escape_text(source_template),
        }),
    ) else {
        return html.to_owned();
    };
    let toolbar = dynamic::csrf_inject_hidden_inputs(artifact_root, &toolbar, csrf_token);
    let toolbar = pharos_runtime_architect::editable_grouping::scope_groups(
        &toolbar,
        architect_app.app_id.as_deref().unwrap_or("architect"),
        true,
    )
    .unwrap_or(toolbar);
    format!("{}\n{}{}", &html[..insert_at], toolbar, &html[insert_at..])
}

/// Locates the end of a document body opening tag; partial app fragments have no host toolbar.
fn architect_preview_body_content_start(html: &str) -> Option<usize> {
    let bytes = html.as_bytes();
    let start = bytes.windows(5).enumerate().find_map(|(index, tag)| {
        (tag.eq_ignore_ascii_case(b"<body")
            && bytes
                .get(index + 5)
                .is_some_and(|byte| byte.is_ascii_whitespace() || *byte == b'>'))
        .then_some(index + 5)
    })?;
    let mut quote = None;
    for (offset, byte) in bytes[start..].iter().enumerate() {
        match (quote, *byte) {
            (Some(open), close) if open == close => quote = None,
            (None, b'\'' | b'"') => quote = Some(*byte),
            (None, b'>') => return Some(start + offset + 1),
            _ => {}
        }
    }
    None
}

pub(super) fn architect_preview_overrides_json(preview_app: &AppRuntime) -> String {
    let Some(app_root) = preview_app.app_root.as_deref().map(Path::new) else {
        return architect_empty_preview_overrides_json();
    };
    let path = app_root.join("static/architect-preview-overrides.json");
    let Ok(text) = stdfs::read_to_string(path) else {
        return architect_empty_preview_overrides_json();
    };
    if text.len() > 64 * 1024 {
        return architect_empty_preview_overrides_json();
    }
    match serde_json::from_str::<Value>(&text) {
        Ok(value)
            if value.get("schema").and_then(Value::as_str)
                == Some("pharos.architect.preview_overrides.v1") =>
        {
            text
        }
        _ => architect_empty_preview_overrides_json(),
    }
}

pub(super) fn architect_empty_preview_overrides_json() -> String {
    r#"{"schema":"pharos.architect.preview_overrides.v1","overrides":{}}"#.to_owned()
}

pub(super) fn architect_preview_script_json_text(json: &str) -> String {
    let value = serde_json::from_str::<Value>(json).unwrap_or_else(
        |_| serde_json::json!({"schema":"pharos.architect.preview_overrides.v1","overrides":{}}),
    );
    serde_json::to_string(&value)
        .unwrap_or_else(|_| architect_empty_preview_overrides_json())
        .replace('<', "\\u003c")
        .replace('>', "\\u003e")
        .replace('&', "\\u0026")
}

fn rewrite_architect_generated_preview_css_urls(
    css: &str,
    task_id: i64,
    output_app_id: &str,
    route_path: &str,
) -> String {
    pharos_runtime_architect::preview_style::rewrite_architect_generated_preview_css_urls(
        css,
        task_id,
        output_app_id,
        route_path,
    )
}

fn rewrite_architect_generated_preview_forms(
    html: &str,
    preview_app: &AppRuntime,
    task_id: i64,
) -> String {
    let Some(ir) = preview_app.application_ir.as_ref() else {
        return html.to_owned();
    };
    let routes = ir
        .routes
        .values()
        .map(
            |route| pharos_runtime_architect::preview_style::ArchitectPreviewActionRoute {
                kind: route.kind.clone(),
                action_id: route
                    .action_id
                    .as_ref()
                    .map(|value| value.as_str().to_owned()),
                path: route.path.clone(),
                method: route.method.clone(),
            },
        )
        .collect::<Vec<_>>();
    pharos_runtime_architect::preview_style::rewrite_architect_generated_preview_forms(
        html,
        preview_app.app_id.as_deref(),
        &routes,
        task_id,
    )
}

fn rewrite_architect_generated_preview_urls(
    html: &str,
    output_app_id: &str,
    task_id: i64,
) -> String {
    pharos_runtime_architect::preview_style::rewrite_architect_generated_preview_urls(
        html,
        output_app_id,
        task_id,
    )
}

/// Resolves preview workspace metadata through the configured Architect store.
pub(super) fn architect_validated_task_preview_info(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
) -> Option<(String, String)> {
    pharos_runtime_architect::task_repository::validated_preview_info(store, task_id)
        .ok()
        .flatten()
}

/// Resolves the current editor source from logical task and version records.
pub(super) fn architect_current_editor_preview_root(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
) -> Option<(String, PathBuf)> {
    pharos_runtime_architect::task_repository::current_editor_preview_root(store, task_id)
        .ok()
        .flatten()
}

pub(super) fn architect_view_editor_source_file_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let version_id = dynamic::request_form_value(request, "version_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let project_id = dynamic::request_form_value(request, "project_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let source_path = dynamic::request_form_value(request, "source_path").unwrap_or_default();
    if version_id <= 0 || source_path.trim().is_empty() {
        return http_text_response(422, "Unprocessable Entity", "invalid source file\n");
    }
    let source_view = if let (
        Some(generated_root),
        Some(output_app_id),
        Some(version_key),
        Some(source_root),
    ) = (
        architect_generated_source_root(app),
        dynamic::request_form_value(request, "output_app_id"),
        dynamic::request_form_value(request, "version_key"),
        dynamic::request_form_value(request, "source_root"),
    ) {
        let source_root_path = PathBuf::from(source_root.trim());
        let allowed_root = generated_root.join(".architect-editor").join("projects");
        let source_root_canon = source_root_path.canonicalize();
        let allowed_root_canon = allowed_root.canonicalize();
        match (source_root_canon, allowed_root_canon) {
            (Ok(source_root_canon), Ok(allowed_root_canon))
                if project_id > 0 && source_root_canon.starts_with(&allowed_root_canon) =>
            {
                agent_architect::load_architect_editor_source_view_from_root(
                    project_id,
                    version_id,
                    output_app_id.trim(),
                    version_key.trim(),
                    &source_root_canon,
                    Some(source_path.trim()),
                )
            }
            _ => agent_architect::load_architect_editor_source_view_in_store(
                &store,
                version_id,
                Some(source_path.trim()),
            ),
        }
    } else {
        agent_architect::load_architect_editor_source_view_in_store(
            &store,
            version_id,
            Some(source_path.trim()),
        )
    };
    let source_view = match source_view {
        Ok(view) => view,
        Err(error) => {
            eprintln!("architect editor source view failed: {error:?}");
            return http_text_response(422, "Unprocessable Entity", "source view unavailable\n");
        }
    };
    let Some(selected) = source_view.selected else {
        return http_text_response(422, "Unprocessable Entity", "source view unavailable\n");
    };
    let source_path_options = source_view
        .files
        .iter()
        .filter_map(|file| {
            json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_source_path_option.html"),
                &serde_json::json!({
                    "path": &file.path,
                    "selected": if file.path == selected.path { "selected" } else { "" },
                }),
            )
        })
        .collect::<String>();
    let params = serde_json::json!({
        "project_id": source_view.project_id.to_string(),
        "version_id": source_view.version_id.to_string(),
        "output_app_id": &source_view.output_app_id,
        "version_key": &source_view.version_key,
        "source_root": &source_view.source_root,
        "selected_path": &selected.path,
        "selected_sha256": &selected.sha256,
        "selected_size_bytes": selected.size_bytes.to_string(),
        "selected_content": &selected.content,
        "source_path_options": source_path_options,
    });
    let Some(body) = json_commands::template_render_file(
        &artifact_root.join("templates/fragments/editor_source_viewer.html"),
        &params,
    ) else {
        return http_text_response(500, "Internal Server Error", "source view unavailable\n");
    };
    let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
    let body = dynamic::csrf_inject_hidden_inputs(artifact_root, &body, &csrf_token);
    http_html_response(200, "OK", &body, method)
}

pub(super) fn architect_prepare_editor_source_edit_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let version_id = dynamic::request_form_value(request, "version_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let source_path = dynamic::request_form_value(request, "source_path").unwrap_or_default();
    let mut source_content =
        dynamic::request_form_value(request, "source_content").unwrap_or_default();
    let grouping = dynamic::request_form_value(request, "source_grouping").unwrap_or_default();
    let source_bundle = dynamic::request_form_value(request, "source_files");
    if !grouping.is_empty() && source_bundle.is_none() {
        if grouping != "existing"
            || !source_path.trim().ends_with(".html")
            || !agent_architect::source_export_relative_path_allowed(Path::new(source_path.trim()))
        {
            return architect_preview_edit_error_response(
                app,
                "Grouping preparation unavailable",
                "Choose an HTML source file to prepare existing container groups.",
                method,
            );
        }
        source_content = match pharos_runtime_architect::editable_grouping::prepare_existing_groups(
            &source_content,
            source_path.trim(),
        ) {
            Ok(proposed) => proposed,
            Err(diagnostic) => {
                return architect_preview_edit_error_response(
                    app,
                    "Source grouping rejected",
                    &format!(
                        "{} at byte {}: {}",
                        source_path.trim(),
                        diagnostic.offset,
                        diagnostic.message
                    ),
                    method,
                );
            }
        };
    }
    if grouping == "existing" && source_bundle.is_none() {
        let view = match agent_architect::load_architect_editor_source_view_in_store(
            &store, version_id, None,
        ) {
            Ok(view) => view,
            Err(_) => {
                return architect_preview_edit_error_response(
                    app,
                    "Grouping preparation unavailable",
                    "The selected source version is unavailable.",
                    method,
                );
            }
        };
        source_content = match pharos_runtime_architect::editable_grouping::scope_groups(
            &source_content,
            &view.output_app_id,
            false,
        ) {
            Ok(proposed) => proposed,
            Err(_) => {
                return architect_preview_edit_error_response(
                    app,
                    "Grouping preparation unavailable",
                    "The grouping proposal exceeds the source limits.",
                    method,
                );
            }
        };
    }
    if source_path.trim().ends_with(".html")
        && let Err(diagnostic) =
            pharos_runtime_architect::editable_grouping::validate(&source_content)
    {
        return architect_preview_edit_error_response(
            app,
            "Source grouping rejected",
            &format!(
                "{} at byte {}: {}",
                source_path.trim(),
                diagnostic.offset,
                diagnostic.message
            ),
            method,
        );
    }
    let source_prepare_result = if let Some(bundle) = source_bundle {
        if !grouping.is_empty() && grouping != "existing" {
            return architect_preview_edit_error_response(
                app,
                "Source grouping rejected",
                "Unknown grouping policy.",
                method,
            );
        }
        architect_prepare_source_bundle(
            &store,
            version_id,
            actor_id,
            &bundle,
            grouping == "existing",
        )
    } else if !agent_architect::source_export_relative_path_allowed(Path::new(source_path.trim())) {
        Err(agent_bridge::AgentErrorKind::PolicyViolation)
    } else {
        agent_architect::prepare_architect_editor_source_edit_in_store(
            &store,
            version_id,
            source_path.trim(),
            &source_content,
            actor_id,
        )
    };
    match source_prepare_result {
        Ok(plan) => {
            let params = serde_json::json!({
                "change_id": plan.change_id.to_string(),
                "source_path": &plan.source_path,
                "old_sha256": json_commands::html_escape_text(&plan.old_sha256),
                "new_sha256": json_commands::html_escape_text(&plan.new_sha256),
                "old_size_bytes": plan.old_size_bytes.to_string(),
                "new_size_bytes": plan.new_size_bytes.to_string(),
                "diff_preview": &plan.diff_preview,
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_source_edit_result.html"),
                &params,
            ) else {
                return http_text_response(
                    500,
                    "Internal Server Error",
                    "source edit unavailable\n",
                );
            };
            let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
            let body = dynamic::csrf_inject_hidden_inputs(artifact_root, &body, &csrf_token);
            http_html_response(200, "OK", &body, method)
        }
        Err(error) => {
            eprintln!("architect editor source edit prepare failed: {error:?}");
            let message = match error {
                agent_bridge::AgentErrorKind::PolicyViolation => {
                    "The selected path is outside the editable generated source snapshot."
                }
                agent_bridge::AgentErrorKind::CapacityExceeded => {
                    "The selected source file is too large for browser editing."
                }
                agent_bridge::AgentErrorKind::StalePlan => {
                    "The proposed content matches the current source, so no edit was prepared."
                }
                _ => {
                    "The source edit could not be prepared. Review the selected file and try again."
                }
            };
            let params = serde_json::json!({
                "error_message": json_commands::html_escape_text(message),
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_source_edit_error.html"),
                &params,
            ) else {
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    "source edit unavailable\n",
                );
            };
            http_html_response(422, "Unprocessable Entity", &body, method)
        }
    }
}

/// Stages a bounded multi-file source transaction for an owned editable project.
/// New declarations and their templates can therefore be validated and promoted together.
fn architect_prepare_source_bundle(
    store: &pharos_runtime_architect::database::ArchitectStore,
    version_id: i64,
    actor_id: i64,
    bundle: &str,
    prepare_grouping: bool,
) -> Result<
    pharos_runtime_architect::task_state::ArchitectEditorSourceEditPlan,
    agent_bridge::AgentErrorKind,
> {
    use agent_bridge::AgentErrorKind;
    if bundle.len() > 1024 * 1024 {
        return Err(AgentErrorKind::CapacityExceeded);
    }
    let mut files: Vec<(String, String)> =
        serde_json::from_str(bundle).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    if files.is_empty()
        || files.len() > pharos_runtime_architect::editor_state::MAX_SOURCE_EDIT_FILES
    {
        return Err(AgentErrorKind::CapacityExceeded);
    }
    let namespace = if prepare_grouping {
        Some(
            agent_architect::load_architect_editor_source_view_in_store(store, version_id, None)?
                .output_app_id,
        )
    } else {
        None
    };
    let mut paths = std::collections::BTreeSet::new();
    for (path, content) in &mut files {
        if !paths.insert(path.clone())
            || !agent_architect::source_export_relative_path_allowed(Path::new(path))
        {
            return Err(AgentErrorKind::PolicyViolation);
        }
        if path.ends_with(".html") {
            if let Some(namespace) = &namespace {
                let grouped = pharos_runtime_architect::editable_grouping::prepare_existing_groups(
                    content, path,
                )
                .map_err(|_| AgentErrorKind::InvalidEnvelope)?;
                *content = pharos_runtime_architect::editable_grouping::scope_groups(
                    &grouped, namespace, false,
                )?;
            }
            pharos_runtime_architect::editable_grouping::validate_for_edit(content)?;
        }
    }
    pharos_runtime_architect::editor_state::prepare_editor_changes_in_store(
        store,
        version_id,
        &files,
        actor_id,
        "source_edit",
    )
}

pub(super) fn architect_prepare_editor_structured_edit_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let version_id = dynamic::request_form_value(request, "version_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let edit_kind = dynamic::request_form_value(request, "edit_kind").unwrap_or_default();
    let mut params = serde_json::Map::new();
    for key in [
        "operation",
        "entity_id",
        "new_entity_id",
        "field_id",
        "new_field_id",
        "field_type",
        "required",
        "helper_text",
        "options",
        "pattern",
        "archetype",
        "title",
        "route_path",
        "button_count",
        "icon_name",
        "target_id",
        "accent",
        "placement",
        "body_copy",
    ] {
        if let Some(value) = dynamic::request_form_value(request, key) {
            params.insert(key.to_owned(), serde_json::Value::String(value));
        }
    }
    let params = serde_json::Value::Object(params);
    let edit_kind = if edit_kind == "field" {
        dynamic::request_form_value(request, "operation").unwrap_or_else(|| "field_add".to_owned())
    } else if edit_kind == "layout" {
        "layout_pattern".to_owned()
    } else {
        edit_kind
    };
    let structured_prepare_result =
        agent_architect::prepare_architect_editor_structured_edit_in_store(
            &store,
            version_id,
            edit_kind.trim(),
            &params,
            actor_id,
        );
    match structured_prepare_result {
        Ok(plan) => {
            let mut rows = String::new();
            for item in plan.plans {
                let params = serde_json::json!({
                    "change_id": item.change_id.to_string(),
                    "source_path": json_commands::html_escape_text(&item.source_path),
                    "old_size_bytes": item.old_size_bytes.to_string(),
                    "new_size_bytes": item.new_size_bytes.to_string(),
                    "diff_preview": &item.diff_preview,
                });
                if let Some(row) = json_commands::template_render_file(
                    &artifact_root.join("templates/fragments/editor_structured_edit_row.html"),
                    &params,
                ) {
                    rows.push_str(&row);
                }
            }
            let params = serde_json::json!({
                "structured_change_rows": rows,
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_structured_edit_result.html"),
                &params,
            ) else {
                return http_text_response(
                    500,
                    "Internal Server Error",
                    "structured edit unavailable\n",
                );
            };
            let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
            let body = dynamic::csrf_inject_hidden_inputs(artifact_root, &body, &csrf_token);
            http_html_response(200, "OK", &body, method)
        }
        Err(error) => {
            eprintln!("architect structured editor prepare failed: {error:?}");
            let message = match error {
                agent_bridge::AgentErrorKind::StalePlan => {
                    "The structured edit did not change the selected generated source."
                }
                agent_bridge::AgentErrorKind::InvalidIdentifier => {
                    "The structured edit references an unknown entity, field, page, or source file."
                }
                agent_bridge::AgentErrorKind::CapacityExceeded => {
                    "The structured edit is too large for browser review."
                }
                _ => {
                    "The structured edit could not be prepared. Review the selected project and try again."
                }
            };
            let params = serde_json::json!({
                "error_message": json_commands::html_escape_text(message),
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_source_edit_error.html"),
                &params,
            ) else {
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    "structured edit unavailable\n",
                );
            };
            http_html_response(422, "Unprocessable Entity", &body, method)
        }
    }
}

pub(super) fn architect_apply_editor_source_edit_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let change_id = dynamic::request_form_value(request, "change_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if change_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid source edit\n");
    }
    let inject_failure_after_validation =
        dynamic::request_form_value(request, "inject_failure_after_validation")
            .is_some_and(|value| value == "true" || value == "1");
    let preview_task_id =
        pharos_runtime_architect::editor_state::load_planned_edit_in_store(&store, change_id)
            .ok()
            .and_then(|edit| pharos_runtime_architect::editor_state::planned_editor_task_id(&edit));
    let apply_result = if inject_failure_after_validation {
        agent_architect::apply_architect_editor_source_edit_with_injected_failure(
            &store,
            change_id,
            &generated_root,
            actor_id,
        )
    } else {
        agent_architect::apply_architect_editor_source_edit(
            &store,
            change_id,
            &generated_root,
            actor_id,
        )
    };
    let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
        return http_text_response(500, "Internal Server Error", "response unavailable\n");
    };
    match apply_result {
        Ok(result) => {
            if let Some(task_id) = preview_task_id
                && !architect_prepare_validated_generated_preview(&store, task_id)
            {
                eprintln!("Architect source edit accepted; preview preparation remains pending");
            }
            let params = serde_json::json!({
                "change_id": result.change_id.to_string(),
                "output_app_id": json_commands::html_escape_text(&result.output_app_id),
                "source_path": json_commands::html_escape_text(&result.source_path),
                "source_fingerprint": json_commands::html_escape_text(&result.source_fingerprint),
                "validation_summary": json_commands::html_escape_text(&result.validation_summary),
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_source_edit_applied.html"),
                &params,
            ) else {
                return http_text_response(
                    500,
                    "Internal Server Error",
                    "source edit response unavailable\n",
                );
            };
            http_html_response(200, "OK", &body, method)
        }
        Err(error) => {
            eprintln!("architect editor source edit apply failed: {error:?}");
            let message = if inject_failure_after_validation {
                "The injected failure proof ran after validation and rolled back without promoting the generated source."
            } else {
                "The source edit could not be applied. Validation, rollback, or persistence blocked the change."
            };
            let params = serde_json::json!({
                "error_message": json_commands::html_escape_text(message),
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_source_edit_error.html"),
                &params,
            ) else {
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    "source edit unavailable\n",
                );
            };
            http_html_response(422, "Unprocessable Entity", &body, method)
        }
    }
}

pub(super) fn architect_apply_preview_edit_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let task_id = dynamic::request_form_value(request, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if task_id <= 0 {
        return architect_preview_edit_error_response(
            app,
            "Preview edit unavailable",
            "The preview editor did not receive a valid generated app task.",
            method,
        );
    }
    if pharos_runtime_architect::task_ownership::task_owner(&store, task_id)
        .ok()
        .flatten()
        != Some(actor_id)
    {
        return http_text_response(403, "Forbidden", "This task belongs to another user.\n");
    }
    let Some(version_id) = architect_current_editor_version_id_for_task(&store, task_id) else {
        return architect_preview_edit_error_response(
            app,
            "Preview edit unavailable",
            "The generated app is not registered as an editable Architect project version yet.",
            method,
        );
    };
    let ui_element = dynamic::request_form_value(request, "preview_ui_element").unwrap_or_default();
    let operation = dynamic::request_form_value(request, "preview_operation").unwrap_or_default();
    let selector = dynamic::request_form_value(request, "preview_selector").unwrap_or_default();
    let style_payload =
        dynamic::request_form_value(request, "preview_style_payload").unwrap_or_default();
    if operation == "undo_edit" || operation == "redo_edit" {
        let preview_history_result = architect_commit_preview_edit(
            &store,
            version_id,
            &generated_root,
            actor_id,
            &operation,
            false,
            |_| {
                architect_apply_preview_history_edit(
                    &store,
                    version_id,
                    &generated_root,
                    operation == "redo_edit",
                )
            },
        );
        return match preview_history_result {
            Ok(_) => {
                let body = architect_fragment_html(
                    app,
                    "templates/fragments/preview_edit_applied.html",
                    &serde_json::json!({}),
                )
                .unwrap_or_default();
                http_html_response(200, "OK", &body, method)
            }
            Err(error) => {
                eprintln!("architect preview history edit failed: {error:?}");
                architect_preview_edit_error_response(
                    app,
                    if operation == "redo_edit" {
                        "Redo failed"
                    } else {
                        "Undo failed"
                    },
                    architect_preview_style_error_message(error),
                    method,
                )
            }
        };
    }
    if operation == "edit_selected" && !style_payload.trim().is_empty() {
        let preview_apply_result = architect_commit_preview_edit(
            &store,
            version_id,
            &generated_root,
            actor_id,
            "preview styles",
            true,
            |_| {
                architect_apply_preview_style_edit(
                    &store,
                    task_id,
                    version_id,
                    &generated_root,
                    actor_id,
                    &selector,
                    &style_payload,
                )
            },
        );
        return match preview_apply_result {
            Ok(_) => {
                let body = architect_fragment_html(
                    app,
                    "templates/fragments/preview_edit_saved.html",
                    &serde_json::json!({}),
                )
                .unwrap_or_default();
                http_html_response(200, "OK", &body, method)
            }
            Err(error) => {
                eprintln!("architect preview style edit apply failed: {error:?}");
                architect_preview_edit_error_response(
                    app,
                    "Style edit failed",
                    architect_preview_style_error_message(error),
                    method,
                )
            }
        };
    }
    if operation == "delete_element" || operation == "duplicate_element" {
        let preview_apply_result = architect_commit_preview_edit(
            &store,
            version_id,
            &generated_root,
            actor_id,
            if operation == "duplicate_element" {
                "preview duplication"
            } else {
                "preview deletion"
            },
            true,
            |_| {
                architect_apply_preview_unit_edit(
                    &store,
                    version_id,
                    &generated_root,
                    &selector,
                    operation == "duplicate_element",
                )
            },
        );
        return match preview_apply_result {
            Ok(_) => {
                let body = architect_fragment_html(
                    app,
                    "templates/fragments/preview_edit_applied.html",
                    &serde_json::json!({}),
                )
                .unwrap_or_default();
                http_html_response(200, "OK", &body, method)
            }
            Err(error) => {
                eprintln!("architect preview delete edit apply failed: {error:?}");
                architect_preview_edit_error_response(
                    app,
                    "Preview edit failed",
                    architect_preview_style_error_message(error),
                    method,
                )
            }
        };
    }
    if operation == "move_element" {
        let source_selector =
            dynamic::request_form_value(request, "preview_move_source").unwrap_or_default();
        let target_selector =
            dynamic::request_form_value(request, "preview_move_target").unwrap_or_default();
        let placement =
            dynamic::request_form_value(request, "preview_move_placement").unwrap_or_default();
        let source_template = dynamic::request_form_value(request, "preview_source_template");
        let preview_apply_result = architect_commit_preview_edit(
            &store,
            version_id,
            &generated_root,
            actor_id,
            "preview move",
            true,
            |view| {
                architect_apply_preview_move_from_view(
                    view.clone(),
                    &generated_root,
                    &source_selector,
                    &target_selector,
                    &placement,
                    source_template.as_deref(),
                )
            },
        );
        return match preview_apply_result {
            Ok(_) => {
                let body = architect_fragment_html(
                    app,
                    "templates/fragments/preview_edit_applied.html",
                    &serde_json::json!({}),
                )
                .unwrap_or_default();
                http_html_response(200, "OK", &body, method)
            }
            Err(error) => {
                eprintln!(
                    "architect preview move edit apply failed: {error:?}; source={:?}; target={:?}; placement={:?}",
                    source_selector.chars().take(2048).collect::<String>(),
                    target_selector.chars().take(2048).collect::<String>(),
                    placement.chars().take(32).collect::<String>()
                );
                architect_preview_edit_error_response(
                    app,
                    "Preview move failed",
                    match error {
                        agent_bridge::AgentErrorKind::PolicyViolation => {
                            "The move could not be applied safely. Check that the destination is outside the moved element and that its source definitions agree."
                        }
                        _ => architect_preview_style_error_message(error),
                    },
                    method,
                )
            }
        };
    }
    let title = dynamic::request_form_value(request, "preview_title").unwrap_or_default();
    let body_copy = dynamic::request_form_value(request, "preview_body_copy").unwrap_or_default();
    let button_count = dynamic::request_form_value(request, "preview_button_count")
        .and_then(|value| value.parse::<u8>().ok())
        .unwrap_or(3)
        .clamp(1, 8)
        .to_string();
    let icon_name = dynamic::request_form_value(request, "preview_icon_name").unwrap_or_default();
    let Some((pattern, placement, editor_operation)) =
        architect_preview_edit_mapping(&ui_element, &operation)
    else {
        return architect_preview_edit_error_response(
            app,
            "Preview edit unavailable",
            "Choose an add, edit, duplicate, or delete operation for an Architect-managed UI element.",
            method,
        );
    };
    let element_markup = if pattern == "element_template" {
        let Some(markup) = architect_preview_element_template(app, &ui_element) else {
            return architect_preview_edit_error_response(
                app,
                "Preview edit unavailable",
                "Architect could not load the selected element template.",
                method,
            );
        };
        markup
    } else {
        String::new()
    };
    let source_paths = if operation == "add_element" && !selector.trim().is_empty() {
        match architect_preview_selected_source(&store, version_id, &selector) {
            Ok(selected) => selected
                .files
                .into_iter()
                .map(|(path, _)| path)
                .collect::<Vec<_>>(),
            Err(error) => {
                return architect_preview_edit_error_response(
                    app,
                    "Preview edit failed",
                    architect_preview_style_error_message(error),
                    method,
                );
            }
        }
    } else {
        Vec::new()
    };
    let params = serde_json::json!({
        "source_paths": source_paths,
        "selector": selector,
        "operation": editor_operation,
        "pattern": pattern,
        "archetype": ui_element.trim(),
        "title": title.trim(),
        "body_copy": body_copy.trim(),
        "placement": placement,
        "button_count": button_count,
        "icon_name": icon_name.trim(),
        "element_markup": element_markup,
    });
    let preview_prepare_result = agent_architect::prepare_architect_editor_structured_edit_in_store(
        &store,
        version_id,
        "layout_pattern",
        &params,
        actor_id,
    );
    let plan = match preview_prepare_result {
        Ok(plan) => plan,
        Err(error) => {
            eprintln!("architect preview edit prepare failed: {error:?}");
            return architect_preview_edit_error_response(
                app,
                "Preview edit unavailable",
                "Architect could not prepare a bounded source change for the selected preview element.",
                method,
            );
        }
    };
    let Some(change_id) = plan.plans.first().map(|item| item.change_id) else {
        return architect_preview_edit_error_response(
            app,
            "Preview edit unavailable",
            "Architect did not produce a source change for the selected preview operation.",
            method,
        );
    };
    let preview_apply_result = (|| {
        architect_record_preview_undo_snapshot(&store, version_id)?;
        agent_architect::apply_architect_editor_source_edit(
            &store,
            change_id,
            &generated_root,
            actor_id,
        )
    })();
    match preview_apply_result {
        Ok(result) => {
            if let Err(error) = architect_stage_validated_preview_artifact(
                &store,
                task_id,
                result.change_id,
                &generated_root,
            ) {
                eprintln!("architect preview artifact staging failed: {error:?}");
            }
            let body = architect_fragment_html(
                app,
                "templates/fragments/preview_edit_applied.html",
                &serde_json::json!({}),
            )
            .unwrap_or_default();
            http_html_response(200, "OK", &body, method)
        }
        Err(error) => {
            eprintln!("architect preview edit apply failed: {error:?}");
            architect_preview_edit_error_response(
                app,
                "Preview edit failed validation",
                "The source change was not written because the generated app did not pass the validation gate.",
                method,
            )
        }
    }
}

/// Reuses the artifact that passed the editor gate for the new version's first preview request.
fn architect_stage_validated_preview_artifact(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
    change_id: i64,
    generated_root: &Path,
) -> Result<(), agent_bridge::AgentErrorKind> {
    use pharos_runtime_database::operations::Predicate;
    let task = store
        .query_one(
            "architect_task",
            &["output_app_id"],
            Predicate::Equal("id".to_owned(), serde_json::json!(task_id)),
        )
        .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?
        .ok_or(agent_bridge::AgentErrorKind::InvalidPath)?;
    let output_app_id = task
        .get("output_app_id")
        .and_then(serde_json::Value::as_str)
        .ok_or(agent_bridge::AgentErrorKind::InvalidEnvelope)?;
    let output_app_id = agent_architect::normalize_architect_preview_app_id(output_app_id)?;
    let validated_root = generated_root
        .join(".architect-editor")
        .join("validation")
        .join(format!("change-{change_id}"))
        .join("dist")
        .join("apps")
        .join(&output_app_id);
    if !validated_root.join("pharos.app.json").is_file() {
        return Err(agent_bridge::AgentErrorKind::InvalidPath);
    }
    let mut staged = false;
    if let Some((version_app_id, source_root)) =
        architect_current_editor_preview_root(store, task_id)
    {
        let expected_source_root = generated_root
            .join(".architect-editor")
            .join("projects")
            .join(&output_app_id)
            .join("versions")
            .join(format!("edit-{change_id}"));
        if version_app_id == output_app_id
            && source_root.canonicalize().ok() == expected_source_root.canonicalize().ok()
            && source_root.is_dir()
        {
            let workspace = architect_editor_preview_workspace(&source_root);
            if !architect_sync_editor_preview_config(store, task_id, &workspace) {
                return Err(agent_bridge::AgentErrorKind::InvalidPath);
            }
            architect_copy_validated_preview_artifact(
                &validated_root,
                &source_root,
                &workspace,
                &output_app_id,
            )?;
            staged = true;
        }
    }
    staged
        .then_some(())
        .ok_or(agent_bridge::AgentErrorKind::InvalidPath)
}

/// Places a validated build at the artifact cache path used by one generated preview root.
fn architect_copy_validated_preview_artifact(
    validated_root: &Path,
    source_root: &Path,
    preview_workspace: &Path,
    output_app_id: &str,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let artifact_root =
        architect_preview_artifact_root(source_root, preview_workspace, output_app_id);
    let lock = architect_preview_artifact_lock(&artifact_root);
    let _preparation = lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    pharos_runtime_architect::source_management::copy_generated_app_artifact(
        validated_root,
        &artifact_root,
    )?;
    let manifest_path = artifact_root.join("pharos.app.json");
    let manifest =
        stdfs::read(&manifest_path).map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
    stdfs::write(&manifest_path, manifest)
        .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
    if architect_preview_source_is_newer_than_artifact(source_root, &manifest_path) {
        return Err(agent_bridge::AgentErrorKind::StalePlan);
    }
    if !architect_prepare_preview_database(&artifact_root, preview_workspace, output_app_id) {
        return Err(agent_bridge::AgentErrorKind::InvalidPath);
    }
    Ok(())
}

const ARCHITECT_PREVIEW_HISTORY_LIMIT: usize = 20;
const ARCHITECT_PREVIEW_LEGACY_HISTORY_PATH: &str = "static/architect-preview-history.json";
const ARCHITECT_PREVIEW_HISTORY_MAX_BYTES: usize = 64 * 1024 * 1024;
const ARCHITECT_PREVIEW_HISTORY_FILES: [&str; 6] = [
    "templates/home.body.html",
    "static/css/site.css",
    "static/css/style.css",
    "static/css/styles.css",
    "static/css/app.css",
    "static/architect-preview-overrides.json",
];

/// Returns the empty on-disk value used when a preview file has not been created yet.
fn architect_preview_default_file_content(relative_path: &str) -> String {
    match relative_path {
        "static/architect-preview-overrides.json" => architect_empty_preview_overrides_json(),
        _ => String::new(),
    }
}

/// Captures the editable preview files that participate in one undo history entry.
fn architect_preview_file_snapshot(
    source_root: &Path,
    stylesheet: Option<&str>,
) -> Result<serde_json::Value, agent_bridge::AgentErrorKind> {
    let mut files = serde_json::Map::new();
    let mut paths = ARCHITECT_PREVIEW_HISTORY_FILES
        .iter()
        .map(|path| (*path).to_owned())
        .collect::<std::collections::BTreeSet<_>>();
    paths.extend(stylesheet.map(str::to_owned));
    paths.extend(
        pharos_runtime_architect::source_bundle::source_paths(source_root)?
            .into_iter()
            .filter(|path| {
                path.extension()
                    .is_some_and(|extension| extension == "html")
            })
            .map(|path| path.to_string_lossy().into_owned()),
    );
    let mut total_bytes = 0_usize;
    for relative_path in paths {
        let relative_path = relative_path.as_str();
        if (relative_path.ends_with(".css") || relative_path == "templates/home.body.html")
            && !source_root.join(relative_path).is_file()
        {
            continue;
        }
        let path = source_root.join(relative_path);
        let content = if !path.exists() {
            architect_preview_default_file_content(relative_path)
        } else {
            let file =
                stdfs::File::open(path).map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
            let mut content = String::new();
            let mut reader = std::io::Read::take(file, 256 * 1024 + 1);
            std::io::Read::read_to_string(&mut reader, &mut content)
                .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
            if content.len() > 256 * 1024 {
                return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
            }
            content
        };
        total_bytes = total_bytes.saturating_add(content.len());
        if total_bytes > 2 * 1024 * 1024 {
            return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
        }
        files.insert(relative_path.to_owned(), serde_json::Value::String(content));
    }
    Ok(serde_json::Value::Object(files))
}

/// Resolves the generated-source-local history file for an Architect preview version.
fn architect_preview_history_path(view: &agent_architect::ArchitectEditorSourceView) -> PathBuf {
    // Source versions are stored at projects/<app>/versions/<version>.
    Path::new(&view.source_root)
        .parent()
        .and_then(Path::parent)
        .unwrap_or_else(|| Path::new(&view.source_root))
        .join("architect-preview-history.json")
}

/// Serializes preview changes and preserves accepted snapshots on promotion failure.
fn architect_commit_preview_edit<F>(
    store: &pharos_runtime_architect::database::ArchitectStore,
    version_id: i64,
    generated_root: &Path,
    actor_id: i64,
    summary: &str,
    record_undo: bool,
    apply: F,
) -> Result<(), agent_bridge::AgentErrorKind>
where
    F: FnOnce(
        &agent_architect::ArchitectEditorSourceView,
    ) -> Result<(), agent_bridge::AgentErrorKind>,
{
    let _guard = pharos_runtime_architect::lifecycle_validation::architect_current_dir_lock()
        .lock()
        .map_err(|_| agent_bridge::AgentErrorKind::PolicyViolation)?;
    let view =
        agent_architect::load_architect_editor_source_view_in_store(store, version_id, None)?;
    let project = store
        .query_one(
            "architect_editor_project",
            &["current_version_id"],
            pharos_runtime_database::operations::Predicate::Equal(
                "id".to_owned(),
                serde_json::json!(view.project_id),
            ),
        )
        .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
    if project
        .as_ref()
        .and_then(|p| p.get("current_version_id"))
        .and_then(Value::as_i64)
        != Some(version_id)
    {
        return Err(agent_bridge::AgentErrorKind::StalePlan);
    }
    let base_root = Path::new(&view.source_root);
    let workspace = architect_editor_preview_workspace(base_root);
    let reusable_artifact =
        architect_preview_artifact_ready(base_root, &workspace, &view.output_app_id)
            .then(|| architect_preview_artifact_root(base_root, &workspace, &view.output_app_id));
    let history = architect_read_preview_history(&view);
    pharos_runtime_architect::source_management::copy_generated_app_source(
        Path::new(&view.source_root),
        &generated_root.join(&view.output_app_id),
    )?;
    let result = (|| {
        if record_undo {
            architect_record_preview_undo_snapshot_from_view(&view)?;
        }
        apply(&view)?;
        let live_root = generated_root
            .join(&view.output_app_id)
            .canonicalize()
            .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        let legacy_history = live_root.join(ARCHITECT_PREVIEW_LEGACY_HISTORY_PATH);
        if legacy_history.exists() {
            if !legacy_history
                .canonicalize()
                .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?
                .starts_with(&live_root)
            {
                return Err(agent_bridge::AgentErrorKind::PolicyViolation);
            }
            stdfs::remove_file(legacy_history)
                .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        }
        pharos_runtime_architect::editor_state::persist_preview_version_from_view_in_store(
            store,
            view.clone(),
            generated_root,
            actor_id,
            summary,
        )
    })();
    if result.is_err() {
        pharos_runtime_architect::source_management::copy_generated_app_source(
            Path::new(&view.source_root),
            &generated_root.join(&view.output_app_id),
        )?;
        architect_write_preview_history(&view, &history)?;
    }
    if result.is_ok()
        && let Some(artifact) = reusable_artifact
        && let Err(error) = architect_stage_preview_only_successor(store, &view, &artifact)
    {
        // Accepted source remains authoritative; a cache failure falls back to the normal build path.
        eprintln!("architect preview artifact reuse unavailable: {error:?}");
    }
    result
}

/// Carries a checked, patched preview artifact into its immediate accepted successor without recompiling contracts.
/// Only visual preview transactions use this path; source/model/contract changes retain their full build gate.
fn architect_stage_preview_only_successor(
    store: &pharos_runtime_architect::database::ArchitectStore,
    base: &agent_architect::ArchitectEditorSourceView,
    artifact: &Path,
) -> Result<(), agent_bridge::AgentErrorKind> {
    use agent_bridge::AgentErrorKind;
    use pharos_runtime_database::operations::Predicate;
    let project = store
        .query_one(
            "architect_editor_project",
            &["current_version_id"],
            Predicate::Equal("id".to_owned(), serde_json::json!(base.project_id)),
        )
        .map_err(|_| AgentErrorKind::InvalidPath)?
        .ok_or(AgentErrorKind::InvalidIdentifier)?;
    let current = project
        .get("current_version_id")
        .and_then(Value::as_i64)
        .ok_or(AgentErrorKind::InvalidEnvelope)?;
    let version = store
        .query_one(
            "architect_editor_version",
            &["project_id", "parent_version_id", "source_root"],
            Predicate::Equal("id".to_owned(), serde_json::json!(current)),
        )
        .map_err(|_| AgentErrorKind::InvalidPath)?
        .ok_or(AgentErrorKind::InvalidIdentifier)?;
    if version.get("project_id").and_then(Value::as_i64) != Some(base.project_id)
        || version.get("parent_version_id").and_then(Value::as_i64) != Some(base.version_id)
    {
        return Err(AgentErrorKind::StalePlan);
    }
    let root = Path::new(
        version
            .get("source_root")
            .and_then(Value::as_str)
            .ok_or(AgentErrorKind::InvalidEnvelope)?,
    )
    .canonicalize()
    .map_err(|_| AgentErrorKind::InvalidPath)?;
    let parent = Path::new(&base.source_root)
        .canonicalize()
        .map_err(|_| AgentErrorKind::InvalidPath)?;
    if root == parent || root.parent() != parent.parent() {
        return Err(AgentErrorKind::PolicyViolation);
    }
    let workspace = architect_editor_preview_workspace(&root);
    let result =
        architect_copy_validated_preview_artifact(artifact, &root, &workspace, &base.output_app_id);
    if result.is_err() {
        architect_invalidate_preview_artifact(&architect_preview_artifact_root(
            &root,
            &workspace,
            &base.output_app_id,
        ))?;
    }
    result
}

/// Removes only a failed derived cache's readiness marker so the next request rebuilds from accepted source.
fn architect_invalidate_preview_artifact(root: &Path) -> Result<(), agent_bridge::AgentErrorKind> {
    match stdfs::remove_file(root.join("pharos.app.json")) {
        Ok(()) => Ok(()),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(_) => Err(agent_bridge::AgentErrorKind::InvalidPath),
    }
}

/// Loads preview edit history and falls back to an empty bounded history on stale data.
fn architect_read_preview_history(
    view: &agent_architect::ArchitectEditorSourceView,
) -> serde_json::Value {
    let path = architect_preview_history_path(view);
    let mut parsed = stdfs::File::open(path)
        .or_else(|_| {
            stdfs::File::open(
                Path::new(&view.source_root).join(ARCHITECT_PREVIEW_LEGACY_HISTORY_PATH),
            )
        })
        .ok()
        .and_then(|file| {
            let mut text = String::new();
            let mut reader =
                std::io::Read::take(file, ARCHITECT_PREVIEW_HISTORY_MAX_BYTES as u64 + 1);
            std::io::Read::read_to_string(&mut reader, &mut text).ok()?;
            (text.len() <= ARCHITECT_PREVIEW_HISTORY_MAX_BYTES).then_some(text)
        })
        .and_then(|text| serde_json::from_str::<serde_json::Value>(&text).ok())
        .unwrap_or_else(|| {
            serde_json::json!({
                "schema": "pharos.architect.preview-history.v1",
                "undo": [],
                "redo": []
            })
        });
    if parsed.get("schema").and_then(serde_json::Value::as_str)
        == Some("pharos.architect.preview-history.v1")
    {
        for key in ["undo", "redo"] {
            if let Some(items) = parsed.get_mut(key).and_then(Value::as_array_mut) {
                architect_trim_preview_history(items);
            }
        }
        parsed
    } else {
        serde_json::json!({
            "schema": "pharos.architect.preview-history.v1",
            "undo": [],
            "redo": []
        })
    }
}

/// Retains the newest history entries with one linear compaction.
fn architect_trim_preview_history(items: &mut Vec<Value>) {
    let excess = items.len().saturating_sub(ARCHITECT_PREVIEW_HISTORY_LIMIT);
    if excess > 0 {
        items.drain(..excess);
    }
}

/// Persists the bounded preview edit history beside the generated source files.
fn architect_write_preview_history(
    view: &agent_architect::ArchitectEditorSourceView,
    history: &serde_json::Value,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let path = architect_preview_history_path(view);
    let Some(parent) = path.parent() else {
        return Err(agent_bridge::AgentErrorKind::InvalidPath);
    };
    stdfs::create_dir_all(parent).map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
    let text = serde_json::to_string_pretty(history)
        .map_err(|_| agent_bridge::AgentErrorKind::InvalidEnvelope)?;
    if text.len() > ARCHITECT_PREVIEW_HISTORY_MAX_BYTES {
        return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
    }
    stdfs::write(path, text).map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)
}

/// Records the current preview source before a mutating edit and clears redo state.
fn architect_record_preview_undo_snapshot(
    store: &pharos_runtime_architect::database::ArchitectStore,
    version_id: i64,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let view =
        agent_architect::load_architect_editor_source_view_in_store(store, version_id, None)?;
    architect_record_preview_undo_snapshot_from_view(&view)
}

/// Captures undo content from the base inventory already validated for this editor operation.
fn architect_record_preview_undo_snapshot_from_view(
    view: &agent_architect::ArchitectEditorSourceView,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let snapshot = architect_preview_file_snapshot(
        Path::new(&view.source_root),
        pharos_runtime_architect::preview_style::architect_preview_stylesheet_path(view),
    )?;
    let mut history = architect_read_preview_history(view);
    let Some(object) = history.as_object_mut() else {
        return Err(agent_bridge::AgentErrorKind::InvalidEnvelope);
    };
    let undo = object
        .entry("undo".to_owned())
        .or_insert_with(|| serde_json::Value::Array(Vec::new()));
    let Some(undo_items) = undo.as_array_mut() else {
        return Err(agent_bridge::AgentErrorKind::InvalidEnvelope);
    };
    if undo_items.last() != Some(&snapshot) {
        undo_items.push(snapshot);
    }
    architect_trim_preview_history(undo_items);
    object.insert("redo".to_owned(), serde_json::Value::Array(Vec::new()));
    architect_write_preview_history(view, &history)
}

/// Restores all source files captured in a single preview undo or redo snapshot.
fn architect_restore_preview_snapshot(
    generated_root: &Path,
    view: &agent_architect::ArchitectEditorSourceView,
    snapshot: &serde_json::Value,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let Some(files) = snapshot.as_object() else {
        return Err(agent_bridge::AgentErrorKind::InvalidEnvelope);
    };
    for relative_path in files.keys() {
        let relative_path = relative_path.as_str();
        if !ARCHITECT_PREVIEW_HISTORY_FILES.contains(&relative_path)
            && !relative_path.ends_with(".html")
            && Some(relative_path)
                != pharos_runtime_architect::preview_style::architect_preview_stylesheet_path(view)
        {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
        let content = files
            .get(relative_path)
            .and_then(serde_json::Value::as_str)
            .map(str::to_owned)
            .unwrap_or_else(|| architect_preview_default_file_content(relative_path));
        architect_write_preview_source_file(generated_root, view, relative_path, &content)?;
    }
    Ok(())
}

/// Applies one undo or redo operation to the generated preview source files.
fn architect_apply_preview_history_edit(
    store: &pharos_runtime_architect::database::ArchitectStore,
    version_id: i64,
    generated_root: &Path,
    redo: bool,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let view =
        agent_architect::load_architect_editor_source_view_in_store(store, version_id, None)?;
    let current = architect_preview_file_snapshot(
        Path::new(&view.source_root),
        pharos_runtime_architect::preview_style::architect_preview_stylesheet_path(&view),
    )?;
    let mut history = architect_read_preview_history(&view);
    let Some(object) = history.as_object_mut() else {
        return Err(agent_bridge::AgentErrorKind::InvalidEnvelope);
    };
    let mut undo_items = object
        .remove("undo")
        .and_then(|value| value.as_array().cloned())
        .unwrap_or_default();
    let mut redo_items = object
        .remove("redo")
        .and_then(|value| value.as_array().cloned())
        .unwrap_or_default();
    let snapshot = if redo {
        redo_items
            .pop()
            .ok_or(agent_bridge::AgentErrorKind::StalePlan)?
    } else {
        undo_items
            .pop()
            .ok_or(agent_bridge::AgentErrorKind::StalePlan)?
    };
    if redo {
        undo_items.push(current);
        architect_trim_preview_history(&mut undo_items);
    } else {
        redo_items.push(current);
        architect_trim_preview_history(&mut redo_items);
    }
    object.insert("undo".to_owned(), serde_json::Value::Array(undo_items));
    object.insert("redo".to_owned(), serde_json::Value::Array(redo_items));
    architect_restore_preview_snapshot(generated_root, &view, &snapshot)?;
    architect_write_preview_history(&view, &history)
}

/// Moves source units using the transaction's checked base inventory, avoiding a second media scan.
fn architect_apply_preview_move_from_view(
    view: agent_architect::ArchitectEditorSourceView,
    generated_root: &Path,
    source_selector: &str,
    target_selector: &str,
    placement: &str,
    source_template: Option<&str>,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let selected =
        architect_preview_move_sources_from_view(view, source_selector, source_template)?;
    let changes = selected
        .files
        .iter()
        .map(|(path, content)| {
            pharos_runtime_architect::preview_move::move_preview_html_element(
                content,
                source_selector,
                target_selector,
                placement,
            )
            .map(|updated| (path, updated))
        })
        .collect::<Result<Vec<_>, _>>()?;
    for (path, updated) in changes {
        architect_write_preview_source_file(generated_root, &selected.view, path, &updated)?;
    }
    Ok(())
}

/// Uses a declared page template to disambiguate source keys shared by different pages.
fn architect_preview_move_sources_from_view(
    view: agent_architect::ArchitectEditorSourceView,
    source_selector: &str,
    source_template: Option<&str>,
) -> Result<ArchitectPreviewSources, agent_bridge::AgentErrorKind> {
    architect_preview_sources_with_template(view, source_selector, source_template)
}

/// Deletes or duplicates a selected unit in its owning source fragment.
fn architect_apply_preview_unit_edit(
    store: &pharos_runtime_architect::database::ArchitectStore,
    version_id: i64,
    generated_root: &Path,
    selector: &str,
    duplicate: bool,
) -> Result<(), agent_bridge::AgentErrorKind> {
    let selected = architect_preview_selected_source(store, version_id, selector)?;
    let view = selected.view;
    if !duplicate {
        let changes = selected
            .files
            .iter()
            .map(|(path, content)| {
                pharos_runtime_architect::preview_move::delete_preview_html_element(
                    content, selector,
                )
                .map(|updated| (path, updated))
            })
            .collect::<Result<Vec<_>, _>>()?;
        for (path, updated) in changes {
            architect_write_preview_source_file(generated_root, &view, path, &updated)?;
        }
        return Ok(());
    }
    let (path, content) = selected
        .files
        .first()
        .ok_or(agent_bridge::AgentErrorKind::InvalidIdentifier)?;
    let unit =
        pharos_runtime_architect::preview_move::duplicate_preview_html_unit(content, selector)?;
    let mut changes = vec![(path.clone(), unit.content.clone())];
    for (path, content) in selected.files.iter().skip(1) {
        let copied =
            pharos_runtime_architect::preview_move::duplicate_preview_html_unit(content, selector)?;
        if copied.keys != unit.keys || copied.ids != unit.ids {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
        changes.push((path.clone(), copied.content));
    }
    if let Some(stylesheet) =
        pharos_runtime_architect::preview_style::architect_preview_stylesheet_path(&view)
    {
        let selected = agent_architect::load_architect_editor_source_view_in_store(
            store,
            version_id,
            Some(stylesheet),
        )?;
        let source = selected
            .selected
            .as_ref()
            .ok_or(agent_bridge::AgentErrorKind::InvalidPath)?;
        let styles = pharos_runtime_architect::preview_style::duplicate_component_styles(
            &source.content,
            &unit,
        )?;
        if styles != source.content {
            changes.push((stylesheet.to_owned(), styles));
        }
    }
    let properties = "static/architect-preview-overrides.json";
    if view.files.iter().any(|file| file.path == properties) {
        let selected = agent_architect::load_architect_editor_source_view_in_store(
            store,
            version_id,
            Some(properties),
        )?;
        let source = selected
            .selected
            .as_ref()
            .ok_or(agent_bridge::AgentErrorKind::InvalidPath)?;
        let copied = pharos_runtime_architect::preview_style::duplicate_component_properties(
            &source.content,
            &unit,
        )?;
        changes.push((properties.to_owned(), copied));
    }
    for (path, source) in changes {
        architect_write_preview_source_file(generated_root, &view, &path, &source)?;
    }
    Ok(())
}

/// Source files sharing one byte-identical logical editor unit.
struct ArchitectPreviewSources {
    view: agent_architect::ArchitectEditorSourceView,
    files: Vec<(String, String)>,
}

/// Resolves shared alias declarations while rejecting conflicting cross-file identities.
fn architect_preview_selected_source(
    store: &pharos_runtime_architect::database::ArchitectStore,
    version_id: i64,
    selector: &str,
) -> Result<ArchitectPreviewSources, agent_bridge::AgentErrorKind> {
    let view =
        agent_architect::load_architect_editor_source_view_in_store(store, version_id, None)?;
    architect_preview_sources_from_view(view, selector)
}

/// Reads bounded source units inside one accepted app root before planning any writes.
fn architect_preview_sources_from_view(
    view: agent_architect::ArchitectEditorSourceView,
    selector: &str,
) -> Result<ArchitectPreviewSources, agent_bridge::AgentErrorKind> {
    architect_preview_sources_with_template(view, selector, None)
}

/// Resolves shared units together, using a known template only for conflicting page declarations.
fn architect_preview_sources_with_template(
    view: agent_architect::ArchitectEditorSourceView,
    selector: &str,
    source_template: Option<&str>,
) -> Result<ArchitectPreviewSources, agent_bridge::AgentErrorKind> {
    let keyed = pharos_runtime_architect::editable_grouping::style_key_selector(selector).is_some();
    let root = Path::new(&view.source_root)
        .canonicalize()
        .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
    let mut selected = Vec::new();
    let mut shared_unit: Option<String> = None;
    let mut conflicting = false;
    let mut total = 0_usize;
    for file in view.files.iter().filter(|file| {
        if keyed {
            file.path.ends_with(".html")
        } else {
            file.path == "templates/home.body.html"
        }
    }) {
        if file.size_bytes > 256 * 1024 {
            return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
        }
        total = total.saturating_add(file.size_bytes);
        if total > 2 * 1024 * 1024 {
            return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
        }
        let path = root
            .join(&file.path)
            .canonicalize()
            .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        if !path.starts_with(&root) {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
        let mut reader = std::io::Read::take(
            stdfs::File::open(path).map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?,
            256 * 1024 + 1,
        );
        let mut content = String::new();
        std::io::Read::read_to_string(&mut reader, &mut content)
            .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        if content.len() > 256 * 1024 {
            return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
        }
        if let Some(unit) =
            pharos_runtime_architect::preview_move::preview_element_source(&content, selector)?
        {
            if shared_unit
                .as_deref()
                .is_some_and(|previous| previous != unit)
            {
                conflicting = true;
            }
            if shared_unit.is_none() {
                shared_unit = Some(unit.to_owned());
            }
            selected.push((file.path.clone(), content));
        }
    }
    if selected.is_empty() {
        return Err(agent_bridge::AgentErrorKind::InvalidIdentifier);
    }
    if conflicting {
        let template = source_template
            .filter(|template| template.len() <= 512 && template.ends_with(".html"))
            .ok_or(agent_bridge::AgentErrorKind::PolicyViolation)?;
        selected.retain(|(path, _)| path == template);
        if selected.len() != 1 {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
    }
    Ok(ArchitectPreviewSources {
        view,
        files: selected,
    })
}

pub(super) fn architect_apply_preview_style_edit(
    store: &pharos_runtime_architect::database::ArchitectStore,
    _task_id: i64,
    version_id: i64,
    generated_root: &Path,
    _actor_id: i64,
    selector: &str,
    style_payload: &str,
) -> Result<(), agent_bridge::AgentErrorKind> {
    if style_payload.len() > 4096 {
        return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
    }
    let selector = architect_preview_css_selector(selector)?;
    let payload: serde_json::Value = serde_json::from_str(style_payload)
        .map_err(|_| agent_bridge::AgentErrorKind::InvalidEnvelope)?;
    let declarations = architect_preview_style_declarations(&payload)?;
    let property_override = architect_preview_property_override(&payload)?;
    if declarations.is_empty() && property_override.is_empty() {
        return Err(agent_bridge::AgentErrorKind::StalePlan);
    }
    let view =
        agent_architect::load_architect_editor_source_view_in_store(store, version_id, None)?;
    if pharos_runtime_architect::editable_grouping::key_namespace(&selector)
        .is_some_and(|namespace| namespace != view.output_app_id)
    {
        return Err(agent_bridge::AgentErrorKind::PolicyViolation);
    }
    if !declarations.is_empty() {
        let path =
            pharos_runtime_architect::preview_style::architect_preview_stylesheet_path(&view)
                .ok_or(agent_bridge::AgentErrorKind::InvalidIdentifier)?;
        let selected_view = agent_architect::load_architect_editor_source_view_in_store(
            store,
            version_id,
            Some(path),
        )?;
        let selected = selected_view
            .selected
            .as_ref()
            .ok_or(agent_bridge::AgentErrorKind::InvalidIdentifier)?;
        let updated =
            architect_preview_append_style_override(&selected.content, &selector, &declarations)?;
        architect_write_preview_source_file(generated_root, &view, path, &updated)?;
    }
    if !property_override.is_empty() {
        let overrides =
            architect_preview_merge_property_override(&view, &selector, property_override)?;
        architect_write_preview_source_file(
            generated_root,
            &view,
            "static/architect-preview-overrides.json",
            &overrides,
        )?;
    }
    Ok(())
}

pub(super) fn architect_write_preview_source_file(
    generated_root: &Path,
    view: &agent_architect::ArchitectEditorSourceView,
    relative_path: &str,
    content: &str,
) -> Result<(), agent_bridge::AgentErrorKind> {
    if content.len() > 256 * 1024 {
        return Err(agent_bridge::AgentErrorKind::CapacityExceeded);
    }
    let version_root = Path::new(&view.source_root);
    let generated_app_root = generated_root.join(&view.output_app_id);
    let editor_preview_workspace = architect_editor_preview_workspace(version_root);
    let editor_preview_artifact_root = architect_preview_artifact_root(
        version_root,
        &editor_preview_workspace,
        &view.output_app_id,
    );
    let mut roots = vec![generated_app_root];
    if editor_preview_artifact_root
        .join("pharos.app.json")
        .is_file()
    {
        roots.push(editor_preview_artifact_root);
    }
    for root in roots {
        let canonical_root = root
            .canonicalize()
            .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        let canonical_allowed = if root.starts_with(generated_root) {
            generated_root
                .canonicalize()
                .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?
        } else {
            generated_root
                .join(".architect-editor")
                .canonicalize()
                .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?
        };
        if !canonical_root.starts_with(&canonical_allowed) {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
        let relative = Path::new(relative_path);
        if !agent_architect::source_export_relative_path_allowed(relative) {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
        let output_path = root.join(relative);
        let Some(parent) = output_path.parent() else {
            return Err(agent_bridge::AgentErrorKind::InvalidPath);
        };
        stdfs::create_dir_all(parent).map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        let canonical_parent = parent
            .canonicalize()
            .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
        if !canonical_parent.starts_with(&canonical_root)
            || stdfs::symlink_metadata(&output_path)
                .is_ok_and(|metadata| metadata.file_type().is_symlink())
        {
            return Err(agent_bridge::AgentErrorKind::PolicyViolation);
        }
        stdfs::write(output_path, content)
            .map_err(|_| agent_bridge::AgentErrorKind::InvalidPath)?;
    }
    Ok(())
}

pub(super) fn architect_preview_edit_mapping(
    ui_element: &str,
    operation: &str,
) -> Option<(&'static str, &'static str, &'static str)> {
    let placement = match operation {
        "edit_selected" => "append",
        "delete_element" => "append",
        "add_element" | "duplicate_element" => "append",
        _ => return None,
    };
    if operation == "delete_element" {
        return Some(("card_section", placement, "delete_layout_pattern"));
    }
    let pattern = match ui_element {
        "app_shell" | "icon_nav" => "compact_nav",
        "card_grid" | "card" => "card_section",
        "form_row" | "select_options" => "form_row",
        "button_bar_vertical" => "vertical_button_bar",
        "button_bar_horizontal" => "horizontal_button_bar",
        "popup" => "modal_popup",
        "status_panel" => "status_panel",
        "separator" => "green_wave_separator",
        "div" | "span" | "section" | "article" | "aside" | "header" | "footer" | "nav" | "form"
        | "paragraph" | "heading_1" | "heading_2" | "heading_3" | "strong" | "emphasis"
        | "small" | "label" | "button" | "field" | "text_input" | "number_input" | "checkbox"
        | "textarea" | "select" | "link" => "element_template",
        _ => return None,
    };
    Some((pattern, placement, "upsert_layout_pattern"))
}

fn architect_preview_element_template(app: &AppRuntime, ui_element: &str) -> Option<String> {
    let root = app.artifact_dir.as_deref().or(app.app_root.as_deref())?;
    let path = Path::new(root).join("data/editor/element_templates.json");
    let text = stdfs::read_to_string(path).ok()?;
    if text.len() > 16 * 1024 {
        return None;
    }
    let templates: serde_json::Map<String, Value> = serde_json::from_str(&text).ok()?;
    let markup = templates.get(ui_element)?.as_str()?;
    (markup.len() <= 1024).then(|| markup.to_owned())
}

pub(super) fn architect_preview_edit_error_response(
    app: &AppRuntime,
    title: &str,
    detail: &str,
    method: &str,
) -> Vec<u8> {
    let params = serde_json::json!({
        "title": json_commands::html_escape_text(title),
        "detail": json_commands::html_escape_text(detail),
    });
    let Some(body) =
        architect_fragment_html(app, "templates/fragments/preview_edit_error.html", &params)
    else {
        return http_text_response(422, "Unprocessable Entity", "preview edit unavailable\n");
    };
    http_html_response(422, "Unprocessable Entity", &body, method)
}

/// Uses the same validated accepted version for editing as preview rendering, regardless of retry state.
pub(super) fn architect_current_editor_version_id_for_task(
    store: &pharos_runtime_architect::database::ArchitectStore,
    task_id: i64,
) -> Option<i64> {
    pharos_runtime_architect::task_repository::accepted_editor_version_for_task(store, task_id)
        .ok()
        .flatten()
        .map(|accepted| accepted.version_id)
}

pub(super) fn architect_import_source_app_project_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    _method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let source_app_id = dynamic::request_form_value(request, "source_app_id").unwrap_or_default();
    let output_app_id = dynamic::request_form_value(request, "output_app_id").unwrap_or_default();
    let content_type = request.content_type.as_deref().unwrap_or_default();
    let import_result = if content_type
        .to_ascii_lowercase()
        .starts_with("multipart/form-data")
    {
        let Some(state_parent) = architect_state_parent(app) else {
            return http_text_response(503, "Service Unavailable", "state unavailable\n");
        };
        let upload = match architect_import::stage_upload(request, content_type, &state_parent) {
            Ok(upload) => upload,
            Err(message) => return http_text_response(422, "Unprocessable Entity", message),
        };
        pharos_runtime_architect::project_state::import_architect_source_app_project_from_root_in_store(
            &store,
            &upload.app_root,
            (!output_app_id.trim().is_empty()).then_some(output_app_id.trim()),
            &generated_root,
            actor_id,
        )
    } else {
        if source_app_id.trim().is_empty() || output_app_id.trim().is_empty() {
            return http_text_response(422, "Unprocessable Entity", "invalid source app import\n");
        }
        let roots = architect_import_source_app_roots(app);
        pharos_runtime_architect::project_state::import_architect_source_app_project_in_store(
            &store,
            source_app_id.trim(),
            output_app_id.trim(),
            &roots,
            &generated_root,
            actor_id,
        )
    };
    match import_result {
        Ok(imported) => {
            if !architect_prepare_validated_generated_preview(&store, imported.task_id) {
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    "source imported but preview validation failed; inspect the project source\n",
                );
            }
            http_route_redirect_for_request(
                request,
                &app_scope_path(
                    app,
                    &format!(
                        "/app/edit?task_id={}&app_id={}&path=/",
                        imported.task_id, imported.output_app_id,
                    ),
                ),
            )
        }
        Err(error) => {
            eprintln!("architect source app import failed: {error:?}");
            let message = match error {
                pharos_runtime_architect::AgentErrorKind::CapacityExceeded => {
                    "Source app exceeds the supported limit of 512 files or 80 MiB expanded source."
                }
                pharos_runtime_architect::AgentErrorKind::PolicyViolation => {
                    "Source import conflicts with an existing app id or contains prohibited runtime, secret or linked files. Choose a new editable app id and upload app source only."
                }
                pharos_runtime_architect::AgentErrorKind::InvalidIdentifier => {
                    "Source app manifest or editable app id is invalid. Use a valid pharos.app.yml and app id."
                }
                _ => {
                    "Source app could not be imported. Check the manifest and source files; diagnostic details are recorded in the server log."
                }
            };
            http_text_response(422, "Unprocessable Entity", message)
        }
    }
}

pub(super) fn architect_rename_editor_project_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let mut project_id = dynamic::request_form_value(request, "project_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let title = dynamic::request_form_value(request, "title").unwrap_or_default();
    let new_id = dynamic::request_form_value(request, "new_output_app_id").unwrap_or_default();
    if !new_id.trim().is_empty() {
        let Ok(store) = architect_task_store_for_app(app) else {
            return http_text_response(503, "Service Unavailable", "database unavailable\n");
        };
        if project_id <= 0 {
            let old_id =
                dynamic::request_form_value(request, "source_output_app_id").unwrap_or_default();
            project_id = store
                .query_one(
                    "architect_editor_project",
                    &["id"],
                    pharos_runtime_database::operations::Predicate::Equal(
                        "output_app_id".into(),
                        serde_json::json!(old_id),
                    ),
                )
                .ok()
                .flatten()
                .and_then(|row| row["id"].as_i64())
                .unwrap_or(0);
        }
        let Some(root) = architect_generated_source_root(app) else {
            return http_text_response(
                503,
                "Service Unavailable",
                "generated source unavailable\n",
            );
        };
        let mut preview =
            super::architect_project_identity::NativeIdentityPreview::new(app, request, actor_id);
        match pharos_runtime_architect::project_identity::rename_app_identity(
            &store,
            project_id,
            actor_id,
            new_id.trim(),
            &root,
            &mut preview,
        ) {
            Ok(_) => return architect_task_console_response(app, request, method),
            Err(error) => {
                eprintln!("Architect app identity rename failed: {error:?}");
                return http_text_response(
                    422,
                    "Unprocessable Entity",
                    match error {
                        AgentErrorKind::LockBusy => {
                            "Finish or cancel the active build before renaming this app.\n"
                        }
                        AgentErrorKind::StalePlan => {
                            "The project or preview changed during rename. Reload and retry; accepted identity is unchanged.\n"
                        }
                        AgentErrorKind::InvalidIdentifier => {
                            "Use a valid app ID containing lowercase letters, numbers and underscores.\n"
                        }
                        _ => {
                            "App ID rename unavailable. Check that the ID is unused and the project belongs to you; accepted identity is unchanged.\n"
                        }
                    },
                );
            }
        }
    }
    if project_id <= 0 || title.trim().is_empty() {
        return http_text_response(
            422,
            "Unprocessable Entity",
            "invalid editor project rename\n",
        );
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    match store.query_one(
        "architect_editor_project",
        &["created_by"],
        pharos_runtime_database::operations::Predicate::Equal(
            "id".into(),
            serde_json::json!(project_id),
        ),
    ) {
        Ok(Some(project)) if project["created_by"] == serde_json::json!(actor_id) => {}
        Ok(_) => return http_text_response(403, "Forbidden", "project belongs to another user\n"),
        Err(_) => return http_text_response(503, "Service Unavailable", "database unavailable\n"),
    }
    let rename_result =
        agent_architect::rename_architect_editor_project_for_app(app, project_id, &title);
    match rename_result {
        Ok(_) => architect_editor_panel_response(app, request, method),
        Err(error) => {
            eprintln!("architect editor project rename failed: {error:?}");
            http_text_response(
                422,
                "Unprocessable Entity",
                "editor project rename unavailable\n",
            )
        }
    }
}

pub(super) fn architect_duplicate_editor_project_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let project_id = dynamic::request_form_value(request, "project_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let output_app_id = dynamic::request_form_value(request, "output_app_id").unwrap_or_default();
    if project_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid editor project\n");
    }
    let duplicate_fragment = |output_app_id: &str| {
        let params = serde_json::json!({
            "output_app_id": json_commands::html_escape_text(output_app_id),
            "csrf_token": json_commands::html_escape_text(&dynamic::csrf_token_for_response(request.cookie.as_deref())),
        });
        let Some(body) = architect_fragment_html(
            app,
            "templates/fragments/editor_duplicate_applied.html",
            &params,
        ) else {
            return http_text_response(
                500,
                "Internal Server Error",
                "project duplicate unavailable\n",
            );
        };
        http_html_response(200, "OK", &body, method)
    };
    let duplicate_result =
        pharos_runtime_architect::project_state::duplicate_architect_editor_project_in_store(
            &store,
            project_id,
            &output_app_id,
            &generated_root,
        );
    match duplicate_result {
        Ok(result) => duplicate_fragment(&result.output_app_id),
        Err(error) => {
            eprintln!("architect editor project duplicate failed: {error:?}");
            http_text_response(
                422,
                "Unprocessable Entity",
                "editor project duplicate unavailable\n",
            )
        }
    }
}

pub(super) fn architect_delete_editor_project_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let Some(state_parent) = architect_state_parent(app) else {
        return http_text_response(503, "Service Unavailable", "state unavailable\n");
    };
    let project_id = dynamic::request_form_value(request, "project_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if project_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid editor project\n");
    }
    let export_root = state_parent.join("exports/source");
    let Some(media_root) = architect_media_root(app) else {
        return http_text_response(503, "Service Unavailable", "media storage unavailable\n");
    };
    if stdfs::create_dir_all(&export_root).is_err() || stdfs::create_dir_all(&media_root).is_err() {
        return http_text_response(503, "Service Unavailable", "project storage unavailable\n");
    }
    let delete_project_result =
        pharos_runtime_architect::project_state::delete_architect_editor_project_in_store(
            &store,
            project_id,
            &generated_root,
            &export_root,
            &media_root,
        );
    match delete_project_result {
        Ok(_) => architect_editor_panel_response(app, request, method),
        Err(error) => {
            eprintln!("architect editor project delete failed: {error:?}");
            http_text_response(
                422,
                "Unprocessable Entity",
                "editor project delete unavailable\n",
            )
        }
    }
}

pub(super) fn architect_rollback_editor_version_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/editor");
    }
    if !match actor_has_route_policy(app, actor_id, "review_builder_plan") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok(store) = architect_task_store_for_app(app) else {
        return http_text_response(503, "Service Unavailable", "database unavailable\n");
    };
    let Some(generated_root) = architect_generated_source_root(app) else {
        return http_text_response(503, "Service Unavailable", "generated source unavailable\n");
    };
    let project_id = dynamic::request_form_value(request, "project_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    let version_id = dynamic::request_form_value(request, "version_id")
        .and_then(|value| value.parse::<i64>().ok())
        .unwrap_or(0);
    if project_id <= 0 || version_id <= 0 {
        return http_text_response(422, "Unprocessable Entity", "invalid editor version\n");
    }
    let rollback_result =
        pharos_runtime_architect::project_state::rollback_architect_editor_project_in_store(
            &store,
            project_id,
            version_id,
            &generated_root,
        );
    match rollback_result {
        Ok(result) => {
            let Some(artifact_root) = app.artifact_dir.as_deref().map(Path::new) else {
                return http_text_response(500, "Internal Server Error", "response unavailable\n");
            };
            let csrf_token = dynamic::csrf_token_for_response(request.cookie.as_deref());
            let params = serde_json::json!({
                "output_app_id": json_commands::html_escape_text(&result.output_app_id),
                "version_id": result.version_id.to_string(),
                "csrf_token": csrf_token,
            });
            let Some(body) = json_commands::template_render_file(
                &artifact_root.join("templates/fragments/editor_rollback_applied.html"),
                &params,
            ) else {
                return http_text_response(500, "Internal Server Error", "response unavailable\n");
            };
            http_html_response(200, "OK", &body, method)
        }
        Err(error) => {
            eprintln!("architect editor rollback failed: {error:?}");
            http_text_response(422, "Unprocessable Entity", "editor rollback unavailable\n")
        }
    }
}

pub(super) fn architect_download_source_export_response(
    app: &AppRuntime,
    request: &http::HttpRequest,
    method: &str,
) -> Vec<u8> {
    if app.app_id.as_deref() != Some("architect") {
        return http_text_response(404, "Not Found", "not found\n");
    }
    let actor_id = match active_session_user_id(app, request.cookie.as_deref()) {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    };
    if actor_id <= 0 {
        return app_login_redirect(app, "/settings");
    }
    if !match actor_has_route_policy(app, actor_id, "export_builder_source") {
        Ok(value) => value,
        Err(error) => return std::convert::identity(database_error_response(error)),
    } {
        return http_text_response(403, "Forbidden", "capability denied\n");
    }
    let Ok((config, adapter, schema)) = architect_database_storage_for_app(
        app,
        &[
            "architect_task",
            "architect_source_export",
            "architect_task_event",
            "architect_editor_project",
            "architect_editor_version",
        ],
    ) else {
        return architect_export_diagnostic_response(
            app,
            503,
            "Service Unavailable",
            "Export database unavailable",
            "Architect could not open the project database that tracks generated source exports.",
            method,
        );
    };
    let Some(state_parent) = architect_state_parent(app) else {
        return architect_export_diagnostic_response(
            app,
            503,
            "Service Unavailable",
            "Export state unavailable",
            "Architect could not resolve the runtime state directory used for source-export storage.",
            method,
        );
    };
    let export_root = state_parent.join("exports/source");
    if stdfs::create_dir_all(&export_root).is_err() {
        return architect_export_diagnostic_response(
            app,
            503,
            "Service Unavailable",
            "Export storage unavailable",
            "Architect could not create or open the source-export storage directory.",
            method,
        );
    }
    let export_id = if let Some(export_id) = request_query_value(&request.target, "export_id") {
        export_id
    } else if let Some(task_id) = request_query_value(&request.target, "task_id")
        .and_then(|value| value.parse::<i64>().ok())
        .filter(|value| *value > 0)
    {
        let Some(generated_root) = architect_generated_source_root(app) else {
            return architect_export_diagnostic_response(
                app,
                503,
                "Service Unavailable",
                "Generated source unavailable",
                "Architect could not resolve the generated source root for this app.",
                method,
            );
        };
        let (archive_name, source_root) =
            match pharos_runtime_architect::source_export::validated_architect_task_source(
                &config,
                adapter.as_ref(),
                &schema,
                task_id,
                &generated_root,
            ) {
                Ok(source) => source,
                Err(agent_bridge::AgentErrorKind::PolicyViolation) => {
                    return architect_export_diagnostic_response(
                        app,
                        422,
                        "Unprocessable Entity",
                        "Export task unavailable",
                        "Source export is available only after Architect validates the generated app.",
                        method,
                    );
                }
                Err(_) => {
                    return architect_export_diagnostic_response(
                        app,
                        422,
                        "Unprocessable Entity",
                        "Export task unavailable",
                        "No validated generated app source tree is available for this task. Rebuild or reopen the generated app before downloading an export.",
                        method,
                    );
                }
            };
        if method == "HEAD" {
            return http_download_response(
                &[],
                "application/x-tar",
                &format!("{archive_name}.tar"),
                method,
            );
        }
        let Ok(bytes) = architect_source_tar_archive(&source_root, &archive_name) else {
            return architect_export_diagnostic_response(
                app,
                422,
                "Unprocessable Entity",
                "Source archive unavailable",
                "Architect found the source tree but rejected the archive because it was empty, too large, contained unsafe paths, or included runtime-only material.",
                method,
            );
        };
        return http_download_response(
            &bytes,
            "application/x-tar",
            &format!("{archive_name}.tar"),
            method,
        );
    } else {
        return architect_export_diagnostic_response(
            app,
            422,
            "Unprocessable Entity",
            "Missing export id",
            "Use Download export from a built app or project card so Architect can resolve the generated source bundle.",
            method,
        );
    };
    let download = match agent_architect::read_architect_source_export(
        &config,
        adapter.as_ref(),
        &schema,
        &export_id,
        &export_root,
    ) {
        Ok(download) => download,
        Err(_) => {
            return architect_export_diagnostic_response(
                app,
                404,
                "Not Found",
                "Source export unavailable",
                "The requested export id is missing, expired, or no longer matches the source bundle digest.",
                method,
            );
        }
    };
    let Ok(bytes) = stdfs::read(&download.bundle_path) else {
        return architect_export_diagnostic_response(
            app,
            404,
            "Not Found",
            "Source export file unavailable",
            "The export metadata exists, but the bundle file is missing from export storage.",
            method,
        );
    };
    let Ok((archive_name, archive_bytes)) = architect_source_bundle_json_to_tar(&bytes) else {
        return architect_export_diagnostic_response(
            app,
            422,
            "Unprocessable Entity",
            "Source archive unavailable",
            "Architect found export metadata but could not convert it into a complete app archive.",
            method,
        );
    };
    http_download_response(
        &archive_bytes,
        "application/x-tar",
        &format!("{archive_name}.tar"),
        method,
    )
}

pub(super) fn architect_export_diagnostic_response(
    app: &AppRuntime,
    status_code: u16,
    status_text: &str,
    title: &str,
    detail: &str,
    method: &str,
) -> Vec<u8> {
    let params = serde_json::json!({
        "title": json_commands::html_escape_text(title),
        "detail": json_commands::html_escape_text(detail),
    });
    let Some(body) =
        architect_fragment_html(app, "templates/fragments/export_diagnostic.html", &params)
    else {
        return http_text_response(status_code, status_text, "export unavailable\n");
    };
    http_html_response(status_code, status_text, &body, method)
}

/// Converts an Architect JSON source bundle into the same tar format used by task downloads.
pub(super) fn architect_source_bundle_json_to_tar(bundle: &[u8]) -> Result<(String, Vec<u8>), ()> {
    pharos_runtime_architect::source_export::source_bundle_json_to_tar(bundle)
}

/// Builds a deterministic tar archive from one generated Architect app source tree.
pub(super) fn architect_source_tar_archive(
    source_root: &Path,
    archive_root: &str,
) -> Result<Vec<u8>, ()> {
    pharos_runtime_architect::source_export::source_tar_archive(source_root, archive_root)
}

#[cfg(test)]
mod preview_history_tests {

    /// Failed cache promotion cannot leave a ready marker or modify accepted source and adjacent caches.
    #[test]
    fn failed_preview_cache_loses_only_its_readiness_marker() {
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp/preview-cache-failure")
            .join(format!(
                "{}-{}",
                std::process::id(),
                std::time::SystemTime::now()
                    .duration_since(std::time::UNIX_EPOCH)
                    .unwrap()
                    .as_nanos()
            ));
        let source = root.join("source");
        let cache = root.join("cache");
        std::fs::create_dir_all(&source).unwrap();
        std::fs::create_dir_all(&cache).unwrap();
        std::fs::write(source.join("pharos.app.yml"), "app_id: cache_check\n").unwrap();
        std::fs::write(cache.join("pharos.app.json"), "{}").unwrap();
        std::fs::write(cache.join("retained.txt"), "retained cache evidence").unwrap();
        super::architect_invalidate_preview_artifact(&cache).unwrap();
        super::architect_invalidate_preview_artifact(&cache).unwrap();
        assert!(!cache.join("pharos.app.json").exists());
        assert!(source.join("pharos.app.yml").is_file());
        assert!(cache.join("retained.txt").is_file());
        std::fs::remove_dir_all(root).unwrap();
    }
    use super::*;

    /// Identical alias units share edits, while conflicting definitions remain immutable.
    #[test]
    fn shared_preview_alias_units_preserve_source_safety() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp/0.8.4-testing")
            .join(format!("shared-preview-alias-unit-{}", std::process::id()));
        stdfs::create_dir_all(root.join("templates/pages")).unwrap();
        stdfs::write(root.join("pharos.app.yml"), "app_id: alias_unit\n").unwrap();
        let unit = "<div data-editor-key=\"shared-back\" data-editor-element=\"action\"><a href=\"/\">Back to site</a></div>";
        let first = format!("<main id=\"first\">{unit}</main>");
        let second = format!("<main id=\"second\">{unit}</main>");
        stdfs::write(root.join("templates/pages/first.html"), &first).unwrap();
        stdfs::write(root.join("templates/pages/second.html"), &second).unwrap();
        let view = agent_architect::load_architect_editor_source_view_from_root(
            1,
            1,
            "alias_unit",
            "test",
            &root,
            None,
        )
        .unwrap();
        let selector = "div[data-editor-key=\"shared-back\"]";
        let selected = architect_preview_sources_from_view(view.clone(), selector).unwrap();
        assert_eq!(selected.files.len(), 2);
        assert_eq!(
            architect_preview_move_sources_from_view(
                view.clone(),
                selector,
                Some("templates/pages/first.html")
            )
            .unwrap()
            .files
            .len(),
            2
        );
        let child_selector = "div[data-editor-key=\"shared-back\"] > a:nth-of-type(1)";
        let children = architect_preview_sources_from_view(view.clone(), child_selector).unwrap();
        assert_eq!(children.files.len(), 2);
        for (_, content) in &children.files {
            assert!(
                pharos_runtime_architect::preview_move::preview_element_source(
                    content,
                    child_selector
                )
                .unwrap()
                .unwrap()
                .starts_with("<a ")
            );
        }
        for (_, content) in &selected.files {
            let deleted = pharos_runtime_architect::preview_move::delete_preview_html_element(
                content, selector,
            )
            .unwrap();
            assert!(!deleted.contains("Back to site"));
            let duplicated = pharos_runtime_architect::preview_move::duplicate_preview_html_unit(
                content, selector,
            )
            .unwrap();
            assert!(duplicated.content.contains("shared-back-copy-1"));
        }
        let conflicting = second.replace("Back to site", "Different action");
        stdfs::write(root.join("templates/pages/second.html"), &conflicting).unwrap();
        let page = architect_preview_move_sources_from_view(
            view.clone(),
            selector,
            Some("templates/pages/first.html"),
        )
        .unwrap();
        assert_eq!(page.files.len(), 1);
        assert_eq!(page.files[0].0, "templates/pages/first.html");
        assert!(matches!(
            architect_preview_move_sources_from_view(
                view.clone(),
                selector,
                Some("../../outside.html")
            ),
            Err(agent_bridge::AgentErrorKind::PolicyViolation)
        ));
        assert!(matches!(
            architect_preview_sources_from_view(view.clone(), selector),
            Err(agent_bridge::AgentErrorKind::PolicyViolation)
        ));
        assert_eq!(
            stdfs::read_to_string(root.join("templates/pages/first.html")).unwrap(),
            first
        );
        assert_eq!(
            stdfs::read_to_string(root.join("templates/pages/second.html")).unwrap(),
            conflicting
        );
        #[cfg(unix)]
        {
            let mut escaped = view;
            let mut file = escaped.files[0].clone();
            file.path = "templates/pages/escape.html".into();
            std::os::unix::fs::symlink(
                Path::new(env!("CARGO_MANIFEST_DIR")).join("Cargo.toml"),
                root.join(&file.path),
            )
            .unwrap();
            escaped.files.insert(0, file);
            assert!(matches!(
                architect_preview_sources_from_view(escaped, selector),
                Err(agent_bridge::AgentErrorKind::PolicyViolation)
            ));
        }
        stdfs::remove_dir_all(root).unwrap();
    }

    /// Distinguishes complete attributed layout documents from replacement fragments.
    #[test]
    fn toolbar_is_inserted_inside_the_document_body_and_never_inside_fragments() {
        let document = include_str!("../../apps/commerce_spa/templates/layout/base.html");
        let index = architect_preview_body_content_start(document).unwrap();
        assert!(document[..index].contains("<body class="));
        assert!(document[..index].ends_with('>'));
        let fragment = include_str!("../../apps/menu_spa/templates/cart.body.html");
        assert_eq!(architect_preview_body_content_start(fragment), None);
        let opening = document.find("<body").unwrap();
        assert_eq!(
            architect_preview_body_content_start(&document[..opening + 5]),
            None
        );
    }

    /// Exercises the actual shared fragment and includes, including HTML validation patterns.
    #[test]
    fn shared_preview_toolbar_renders_with_color_hex_fields() {
        let template = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("apps/architect/templates/fragments/edit_toolbar.html");
        let html = json_commands::template_render_file(
            &template,
            &serde_json::json!({
                "task_id": 306,
                "csrf_token": "test-token",
                "preview_overrides": "{}",
                "preview_source_template": "templates/pages/bookings.html",
            }),
        )
        .expect("Shared toolbar must render; literal template braces in HTML patterns break it");
        assert!(html.contains("data-pharos-preview-scope"));
        assert!(html.contains("data-pharos-preview-config-menu"));
        assert!(html.contains("generated-preview.js?v="));
        assert!(html.contains("data-pharos-color-hex=\"border_color\""));
        assert!(html.contains("data-pharos-color-hex=\"shadow_color\""));
        assert!(html.contains("data-pharos-border-opacity"));
        for name in [
            "font_size",
            "font_weight",
            "text_case",
            "label_text",
            "helper_text",
            "tooltip",
        ] {
            assert!(html.contains(&format!("data-pharos-edit-control=\"{name}\"")));
        }
        assert!(html.contains("&#123;6&#125;"));
        assert!(!html.contains("{include:"));
    }

    /// Imported oversized history retains the newest twenty edits in each direction.
    #[test]
    fn imported_history_enforces_twenty_entry_limit() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp/0.8.4-testing")
            .join(format!("preview-history-limit-unit-{}", std::process::id()));
        let version_root = root.join("versions/test");
        stdfs::create_dir_all(version_root.join("static")).unwrap();
        let view = agent_architect::ArchitectEditorSourceView {
            schema: String::new(),
            project_id: 0,
            version_id: 0,
            output_app_id: "history_unit".into(),
            version_key: "test".into(),
            source_root: version_root.to_string_lossy().into_owned(),
            files: vec![],
            total_bytes: 0,
            selected: None,
        };
        let items = (0..25).map(|i| serde_json::json!({"static/css/style.css": format!("#field {{ width: {i}px; }}")})).collect::<Vec<_>>();
        architect_write_preview_history(
            &view,
            &serde_json::json!({
                "schema": "pharos.architect.preview-history.v1", "undo": items, "redo": items,
            }),
        )
        .unwrap();
        let loaded = architect_read_preview_history(&view);
        for key in ["undo", "redo"] {
            let entries = loaded[key].as_array().unwrap();
            assert_eq!(entries.len(), 20);
            assert_eq!(entries[0]["static/css/style.css"], "#field { width: 5px; }");
            assert_eq!(
                entries[19]["static/css/style.css"],
                "#field { width: 24px; }"
            );
        }
        stdfs::remove_dir_all(root).unwrap();
    }

    /// Preview file and history writes leave the accepted snapshot fingerprint intact.
    #[test]
    fn preview_writes_preserve_accepted_source_snapshot() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp/0.8.4-testing")
            .join(format!("preview-snapshot-unit-{}", std::process::id()));
        let version_root = root.join(".architect-editor/projects/history_unit/versions/original");
        let live_root = root.join("history_unit");
        for directory in [&version_root, &live_root] {
            stdfs::create_dir_all(directory.join("static/css")).unwrap();
            stdfs::write(
                directory.join("static/css/style.css"),
                "main { color: blue; }",
            )
            .unwrap();
        }
        let view = agent_architect::ArchitectEditorSourceView {
            schema: String::new(),
            project_id: 1,
            version_id: 1,
            output_app_id: "history_unit".into(),
            version_key: "original".into(),
            source_root: version_root.to_string_lossy().into_owned(),
            files: vec![],
            total_bytes: 0,
            selected: None,
        };
        let fingerprint =
            pharos_runtime_architect::source_management::source_tree_fingerprint(&version_root)
                .unwrap();
        architect_write_preview_source_file(
            &root,
            &view,
            "static/css/style.css",
            "main { color: green; }",
        )
        .unwrap();
        architect_write_preview_history(&view, &serde_json::json!({"schema":"pharos.architect.preview-history.v1","undo":[],"redo":[]})).unwrap();
        assert_eq!(
            stdfs::read_to_string(live_root.join("static/css/style.css")).unwrap(),
            "main { color: green; }"
        );
        assert_eq!(
            pharos_runtime_architect::source_management::source_tree_fingerprint(&version_root)
                .unwrap(),
            fingerprint
        );
        assert!(!architect_preview_history_path(&view).starts_with(&version_root));
        stdfs::remove_dir_all(root).unwrap();
    }

    /// Coalesces concurrent preparation of one artifact without blocking an unrelated preview.
    #[test]
    fn preview_artifact_preparation_locks_are_scoped() {
        let root = Path::new("preview-artifact-lock-test");
        let first = architect_preview_artifact_lock(root);
        let second = architect_preview_artifact_lock(root);
        assert!(std::sync::Arc::ptr_eq(&first, &second));
        let guard = first.lock().unwrap();
        let contender = std::thread::spawn(move || {
            assert!(second.try_lock().is_err());
            let other = architect_preview_artifact_lock(Path::new("other-preview-lock-test"));
            assert!(other.try_lock().is_ok());
        });
        contender.join().unwrap();
        drop(guard);
        drop(first);
        assert!(architect_preview_artifact_lock(root).try_lock().is_ok());
    }

    /// Imported styles participate in undo without creating unused stylesheet files.
    #[test]
    fn imported_stylesheet_history_captures_only_existing_css() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp/0.8.4-testing")
            .join(format!("preview-history-unit-{}", std::process::id()));
        stdfs::create_dir_all(root.join("static/css")).unwrap();
        stdfs::write(root.join("static/css/style.css"), "#field { width: 98px; }").unwrap();
        let before = architect_preview_file_snapshot(&root, None).unwrap();
        assert_eq!(before["static/css/style.css"], "#field { width: 98px; }");
        assert!(before.get("static/css/site.css").is_none());
        assert!(before.get("templates/home.body.html").is_none());
        stdfs::write(root.join("static/css/style.css"), "#field { width: auto; }").unwrap();
        let after = architect_preview_file_snapshot(&root, None).unwrap();
        assert_ne!(
            before["static/css/style.css"],
            after["static/css/style.css"]
        );
        stdfs::write(root.join("static/css/theme.css"), "main { color: blue; }").unwrap();
        let custom = architect_preview_file_snapshot(&root, Some("static/css/theme.css")).unwrap();
        assert_eq!(custom["static/css/theme.css"], "main { color: blue; }");
        stdfs::write(
            root.join("static/css/style.css"),
            vec![b'x'; 256 * 1024 + 1],
        )
        .unwrap();
        assert_eq!(
            architect_preview_file_snapshot(&root, None),
            Err(agent_bridge::AgentErrorKind::CapacityExceeded)
        );
        stdfs::remove_dir_all(root).unwrap();
    }
    /// Keeps app search filters without forwarding encoded or duplicate preview-control parameters.
    #[test]
    fn preview_query_parameters_remain_inside_the_selected_app() {
        assert_eq!(
            architect_preview_query_target(
                "/__pharos/social/x/callback",
                "/architect/apps/view?task_id=306&path=%2F__pharos%2Fsocial%2Fx%2Fcallback&code=one-time&state=opaque"
            ),
            Some("/__pharos/social/x/callback?code=one-time&state=opaque".into())
        );

        assert_eq!(
            architect_preview_query_target(
                "/artists",
                "/architect/app/edit?task_id=7&app_id=catalog&path=%2Fartists&q=Beta&%74ask_id=99"
            ),
            Some("/artists?q=Beta".into())
        );
        assert_eq!(
            architect_preview_query_target(
                "/artists?q=Alpha",
                "/architect/app/edit?task_id=7&path=%2Fartists&genre=house"
            ),
            Some("/artists?q=Alpha&genre=house".into())
        );
        assert!(
            architect_preview_query_target("/artists", "/architect/app/edit?%GG=bad").is_none()
        );
        assert!(
            architect_preview_query_target(
                "/artists",
                &format!("/architect/app/edit?{}", "q=too-long&".repeat(2000))
            )
            .is_none()
        );
    }
    /// Public assets require a compiled artifact, while pages, private downloads and writes retain database preparation.
    #[test]
    fn ready_preview_assets_do_not_require_database_preparation() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tmp/0.8.4-testing")
            .join(format!("preview-assets-unit-{}", std::process::id()));
        stdfs::create_dir_all(&root).unwrap();
        assert!(
            architect_ready_preview_asset_root(&root, &root, "sample", "/static/a.css", "GET")
                .is_none()
        );
        stdfs::write(root.join("pharos.app.json"), "{}").unwrap();
        assert_eq!(
            architect_ready_preview_asset_root(&root, &root, "sample", "/static/a.css", "GET"),
            Some(root.clone())
        );
        assert_eq!(
            architect_ready_preview_asset_root(&root, &root, "sample", "/media/a.png", "HEAD"),
            Some(root.clone())
        );
        assert!(
            architect_ready_preview_asset_root(&root, &root, "sample", "/artists", "GET").is_none()
        );
        assert!(
            architect_ready_preview_asset_root(
                &root,
                &root,
                "sample",
                "/private/downloads/a.zip",
                "GET"
            )
            .is_none()
        );
        assert!(
            architect_ready_preview_asset_root(&root, &root, "sample", "/static/a.css", "POST")
                .is_none()
        );
        stdfs::remove_dir_all(root).unwrap();
    }
}

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

    /// Keeps image uploads across preview versions without rewriting imported source configuration.
    #[test]
    fn preview_image_upload_uses_stable_external_storage() {
        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("tmp")
            .join(format!(
                "pharos-preview-images-{}",
                dynamic::random_secret_hex(8).unwrap()
            ));
        let workspace = root.join("workspace");
        let state = root.join("state");
        stdfs::create_dir_all(&workspace).unwrap();
        stdfs::write(
            workspace.join("runtime.conf"),
            format!("state_dir={}\n", state.display()),
        )
        .unwrap();
        for version in ["one", "two"] {
            let artifact = root
                .join(".preview-artifacts")
                .join(version)
                .join("apps/sample");
            stdfs::create_dir_all(&artifact).unwrap();
            stdfs::write(artifact.join("pharos.app.json"), "{}").unwrap();
            stdfs::write(
                artifact.join("app.conf"),
                "MEDIA_ROOT=/var/lib/pharos/media/sample\nother=value\n",
            )
            .unwrap();
            assert!(architect_configure_preview_media(
                &artifact, &workspace, "sample"
            ));
            let media = config::app_media_root(&artifact).unwrap();
            assert_eq!(media, state.join("sample/media"));
            assert!(
                stdfs::read_to_string(artifact.join("app.conf"))
                    .unwrap()
                    .contains("other=value")
            );
            assert!(architect_configure_preview_media(
                &artifact, &workspace, "sample"
            ));
        }
        let source = root.join("source");
        stdfs::create_dir_all(&source).unwrap();
        stdfs::write(source.join("pharos.app.json"), "{}").unwrap();
        stdfs::write(source.join("app.conf"), "MEDIA_ROOT=/keep/source/value\n").unwrap();
        assert!(!architect_configure_preview_media(
            &source, &workspace, "sample"
        ));
        assert_eq!(
            stdfs::read_to_string(source.join("app.conf")).unwrap(),
            "MEDIA_ROOT=/keep/source/value\n"
        );
        stdfs::remove_dir_all(root).unwrap();
    }
}