pharos_native/runtime/

agent_bridge.rs

#[cfg(test)]
use std::collections::BTreeMap;
use std::fs;
use std::path::{Component, Path, PathBuf};

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

use serde::{Deserialize, Serialize};
use serde_json::Value;

pub use pharos_runtime_architect::{
    AgentErrorKind, CredentialBackend, EncryptedFileCredentialBackend, PathClassification,
    SecretRefMetadata, classify_repo_path, redact_secret_like_text, secret_token_like,
    validate_secret_ref,
};

pub use pharos_runtime_architect::json_rpc::{
    AgentOutput, AgentToolResult, ArtifactKind, ArtifactManifest, CapabilityClass, ExportKind,
    JsonRpcDispatcher, JsonRpcError, JsonRpcErrorData, JsonRpcFailure, JsonRpcRequest,
    JsonRpcSuccess, ProviderCompletion, ProviderToolCall, ReleaseLedgerRecord, TargetEnvironment,
    TargetListFormat, TargetTransport, ToolParams,
};

pub use pharos_runtime_architect::model::{
    AppAcceptanceCriterionModel, AppActionModel, AppChangePlan, AppEntityModel, AppManifestModel,
    AppModel, AppModelSynthesis, AppRouteModel, AppStateMutationModel, AppStaticAssetModel,
    AppTemplateModel, AppUiArchetypeModel, AppWorkflowModel, FilePatch, PlannedFileChange,
    app_model_digest, normalize_app_id,
};

#[cfg(test)]
const RPC_REQUEST_LIMIT_BYTES: usize = 1024 * 1024;
/// Versioned target profile record supplied by Architect configuration.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TargetProfile {
    pub schema: String,
    pub target_id: String,
    pub environment: TargetEnvironment,
    pub transport: TargetTransport,
    pub artifact_kind: ArtifactKind,
    #[serde(default)]
    pub allowed_app_ids: Vec<String>,
    #[serde(default)]
    pub secret_refs: Vec<String>,
}

pub use pharos_runtime_architect::change_plan::{
    AgentOperationLock, acquire_operation_lock, apply_app_change, inspect_change_plan,
    plan_app_change, plan_digest_current, resolve_authoring_output_root,
    resolve_existing_repo_path,
};

pub use pharos_runtime_architect::builder_model::{
    builtin_authoring_patches, synthesize_builtin_app_model,
};

struct RuntimeJsonRpcDispatcher;

impl JsonRpcDispatcher for RuntimeJsonRpcDispatcher {
    fn synthesize_app_model(&self, request: JsonRpcRequest) -> String {
        execute_synthesize_app_model(request)
    }

    fn scaffold_app(&self, request: JsonRpcRequest) -> String {
        execute_scaffold_app(request)
    }

    fn read_app_model(&self, request: JsonRpcRequest) -> String {
        execute_read_app_model(request)
    }

    fn plan_app_change(&self, request: JsonRpcRequest) -> String {
        execute_plan_app_change(request)
    }

    fn inspect_change(&self, request: JsonRpcRequest) -> String {
        execute_inspect_change(request)
    }

    fn apply_app_change(&self, request: JsonRpcRequest) -> String {
        execute_apply_app_change(request)
    }

    fn lifecycle_app(&self, request: JsonRpcRequest, verb: &'static str) -> String {
        execute_lifecycle_app(request, verb)
    }

    fn seed_app(&self, request: JsonRpcRequest) -> String {
        execute_seed_app(request)
    }

    fn validate_local(&self, request: JsonRpcRequest) -> String {
        execute_validate_local(request)
    }

    fn backup_app(&self, request: JsonRpcRequest) -> String {
        execute_backup_app(request)
    }

    fn restore_app(&self, request: JsonRpcRequest) -> String {
        execute_restore_app(request)
    }

    fn jobs_app(&self, request: JsonRpcRequest, operation: &'static str) -> String {
        execute_jobs_app(request, operation)
    }

    fn integrations_app(&self, request: JsonRpcRequest, operation: &'static str) -> String {
        execute_integrations_app(request, operation)
    }

    fn deploy_target(&self, request: JsonRpcRequest) -> String {
        execute_deploy_target(request)
    }

    fn list_targets(&self, request: JsonRpcRequest) -> String {
        execute_list_targets(request)
    }

    fn host_detect(&self, request: JsonRpcRequest) -> String {
        execute_host_detect(request)
    }

    fn production_readiness(&self, request: JsonRpcRequest) -> String {
        execute_production_readiness(request)
    }
}

/// Executes one JSON-RPC request through the crate-owned dispatch table.
pub fn execute_json_rpc(input: &str) -> String {
    pharos_runtime_architect::json_rpc::execute_json_rpc_with_dispatcher(
        input,
        &RuntimeJsonRpcDispatcher,
    )
}

/// Executes the built-in app-model synthesis JSON-RPC method.
fn execute_synthesize_app_model(request: JsonRpcRequest) -> String {
    pharos_runtime_architect::json_rpc::execute_synthesize_app_model(request)
}

/// Executes the shared scaffold helper through the bounded JSON-RPC method.
fn execute_scaffold_app(request: JsonRpcRequest) -> String {
    let params: ScaffoldAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    let app_id = match normalize_app_id(&params.app_id) {
        Ok(app_id) => app_id,
        Err(error) => return json_rpc_failure(Some(request.id), error),
    };
    if params
        .template
        .as_deref()
        .is_some_and(|template| !matches!(template, "dynamic" | "dynamic_declarative"))
    {
        return json_rpc_failure(Some(request.id), AgentErrorKind::PolicyViolation);
    }
    let output_root = match resolve_authoring_output_root(&params.output_root) {
        Ok(output_root) => output_root,
        Err(error) => return json_rpc_failure(Some(request.id), error),
    };
    let repo_root = match default_repo_root() {
        Ok(repo_root) => repo_root,
        Err(error) => return json_rpc_failure(Some(request.id), error),
    };
    let _lock = match acquire_operation_lock(&repo_root) {
        Ok(lock) => lock,
        Err(error) => return json_rpc_failure(Some(request.id), error),
    };
    match pharos_runtime_architect::scaffold::scaffold_app(&app_id, &output_root) {
        Ok(result) => match serde_json::from_str::<Value>(&result) {
            Ok(mut value) => {
                if let Some(app_root) = value.get("app_root").and_then(Value::as_str) {
                    let relative = repo_relative_path(&repo_root, Path::new(app_root));
                    if let Some(object) = value.as_object_mut() {
                        object.insert("app_root".to_owned(), Value::String(relative));
                    }
                }
                json_rpc_success(request.id, value)
            }
            Err(_) => json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
        },
        Err(64) => json_rpc_failure(Some(request.id), AgentErrorKind::InvalidIdentifier),
        Err(75) => json_rpc_failure(Some(request.id), AgentErrorKind::LockBusy),
        Err(73) => json_rpc_failure(Some(request.id), AgentErrorKind::InvalidPath),
        Err(_) => json_rpc_failure(Some(request.id), AgentErrorKind::PolicyViolation),
    }
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ScaffoldAppParams {
    app_id: String,
    output_root: String,
    template: Option<String>,
}

/// Executes a read-only app model inspection for one checked-in app root.
fn execute_read_app_model(request: JsonRpcRequest) -> String {
    let params: ReadAppModelParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match read_existing_app_model(&params.app_id) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ReadAppModelParams {
    app_id: String,
}

/// Reads the current declarative model surfaces for one source app root.
pub fn read_existing_app_model(app_id: &str) -> Result<Value, AgentErrorKind> {
    let repo_root = default_repo_root()?;
    pharos_runtime_architect::product_knowledge::read_existing_app_model(&repo_root, app_id)
}

/// Executes deterministic source-change planning without mutating app source.
fn execute_plan_app_change(request: JsonRpcRequest) -> String {
    pharos_runtime_architect::json_rpc::execute_plan_app_change(request)
}

/// Executes a bounded inspection for one saved change plan.
fn execute_inspect_change(request: JsonRpcRequest) -> String {
    pharos_runtime_architect::json_rpc::execute_inspect_change(request)
}

/// Applies one previously planned app change atomically with preimage rollback.
fn execute_apply_app_change(request: JsonRpcRequest) -> String {
    pharos_runtime_architect::json_rpc::execute_apply_app_change(request)
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct LifecycleAppParams {
    app_id: String,
    app_dir: Option<String>,
    build_dir: Option<String>,
    conf: Option<String>,
    backend: Option<String>,
}

/// Executes one generic runtime lifecycle command through the agent bridge.
fn execute_lifecycle_app(request: JsonRpcRequest, verb: &str) -> String {
    let params: LifecycleAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match run_lifecycle_app_tool(
        verb,
        &params.app_id,
        params.app_dir.as_deref(),
        params.build_dir.as_deref(),
        params.conf.as_deref(),
    ) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Executes the standalone seed compatibility tool without shelling out.
fn execute_seed_app(request: JsonRpcRequest) -> String {
    let params: LifecycleAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match seed_app_tool(
        &params.app_id,
        params.app_dir.as_deref(),
        params.conf.as_deref(),
        params.backend.as_deref().unwrap_or(""),
    ) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct BackupAppParams {
    app_id: String,
    app_dir: Option<String>,
    build_dir: Option<String>,
    conf: Option<String>,
    backend: Option<String>,
    state_dir: Option<String>,
    state_path: Option<String>,
    output_dir: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RestoreAppParams {
    app_id: String,
    app_dir: Option<String>,
    build_dir: Option<String>,
    conf: Option<String>,
    backend: Option<String>,
    state_dir: Option<String>,
    state_path: Option<String>,
    input_dir: String,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct JobsAppParams {
    app_id: String,
    app_dir: Option<String>,
    conf: Option<String>,
    backend: Option<String>,
    db_path: Option<String>,
    case: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IntegrationsAppParams {
    pub app_id: String,
    pub build_dir: Option<String>,
    pub conf: Option<String>,
    pub state_path: String,
    pub adapter_id: Option<String>,
    pub event_kind: Option<String>,
    pub resource_id: Option<String>,
    pub tenant_id: Option<String>,
    pub subject_id: Option<String>,
    pub payload_json: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct DeployTargetParams {
    app_id: String,
    target_id: String,
    app_dir: Option<String>,
    artifact_root: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ListTargetsParams {
    format: Option<TargetListFormat>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ProductionReadinessParams {
    app_id: Option<String>,
}

/// Executes build, verify, and doctor as the local validation bundle.
fn execute_validate_local(request: JsonRpcRequest) -> String {
    let params: LifecycleAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    let build = run_lifecycle_app_tool(
        "build",
        &params.app_id,
        params.app_dir.as_deref(),
        params.build_dir.as_deref(),
        params.conf.as_deref(),
    );
    let verify = build.as_ref().ok().and_then(|_| {
        run_lifecycle_app_tool(
            "verify",
            &params.app_id,
            params.app_dir.as_deref(),
            params.build_dir.as_deref(),
            params.conf.as_deref(),
        )
        .ok()
    });
    let doctor = verify.as_ref().and_then(|_| {
        run_lifecycle_app_tool(
            "doctor",
            &params.app_id,
            params.app_dir.as_deref(),
            params.build_dir.as_deref(),
            params.conf.as_deref(),
        )
        .ok()
    });
    match (build, verify, doctor) {
        (Ok(build), Some(verify), Some(doctor)) => json_rpc_success(
            request.id,
            serde_json::json!({
                "schema": "pharos.agent.validate_local.v1",
                "status": "validated",
                "app_id": params.app_id,
                "build": build,
                "verify": verify,
                "doctor": doctor
            }),
        ),
        (Err(error), _, _) => json_rpc_failure(Some(request.id), error),
        _ => json_rpc_failure(Some(request.id), AgentErrorKind::PolicyViolation),
    }
}

/// Executes one native backup operation through the agent bridge.
fn execute_backup_app(request: JsonRpcRequest) -> String {
    let params: BackupAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match backup_restore_runtime_context(
        &params.app_id,
        params.app_dir.as_deref(),
        params.build_dir.as_deref(),
        params.conf.as_deref(),
        params.state_dir.as_deref(),
        params.state_path.as_deref(),
    )
    .and_then(|(config, app)| {
        let output_dir = params
            .output_dir
            .as_deref()
            .and_then(normalize_lifecycle_path);
        super::backup::build_backup_report_local_json(
            &config,
            &app,
            params.backend.as_deref(),
            output_dir.as_deref(),
        )
        .map_err(|_| AgentErrorKind::PolicyViolation)
        .and_then(|text| {
            serde_json::from_str::<Value>(&text).map_err(|_| AgentErrorKind::InvalidEnvelope)
        })
    }) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Executes one native restore operation through the agent bridge.
fn execute_restore_app(request: JsonRpcRequest) -> String {
    let params: RestoreAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match backup_restore_runtime_context(
        &params.app_id,
        params.app_dir.as_deref(),
        params.build_dir.as_deref(),
        params.conf.as_deref(),
        params.state_dir.as_deref(),
        params.state_path.as_deref(),
    )
    .and_then(|(config, app)| {
        let input_dir =
            normalize_lifecycle_path(&params.input_dir).ok_or(AgentErrorKind::InvalidPath)?;
        super::backup::build_restore_report_local_json(
            &config,
            &app,
            params.backend.as_deref(),
            &input_dir,
        )
        .map_err(|_| AgentErrorKind::PolicyViolation)
        .and_then(|text| {
            serde_json::from_str::<Value>(&text).map_err(|_| AgentErrorKind::InvalidEnvelope)
        })
    }) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Executes bounded job inspection or local job execution through the agent bridge.
fn execute_jobs_app(request: JsonRpcRequest, operation: &str) -> String {
    let params: JobsAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match run_jobs_app_tool(&params, operation) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Executes bounded integration inspection or delivery through the agent bridge.
fn execute_integrations_app(request: JsonRpcRequest, operation: &str) -> String {
    let params: IntegrationsAppParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match run_integrations_app_tool(&params, operation) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Inspects or processes queued local job rows through the configured adapter.
fn run_jobs_app_tool(params: &JobsAppParams, operation: &str) -> Result<Value, AgentErrorKind> {
    if !matches!(operation, "inspect" | "run") {
        return Err(AgentErrorKind::MethodNotFound);
    }
    let app_id = normalize_app_id(&params.app_id)?;
    let app_dir = params
        .app_dir
        .as_deref()
        .and_then(normalize_lifecycle_path)
        .unwrap_or_else(|| PathBuf::from(format!("apps/{app_id}")));
    if !app_dir.join("pharos.app.yml").is_file() {
        return Err(AgentErrorKind::InvalidPath);
    }
    let store = super::database::source_app_operations_store(
        &app_dir,
        params.conf.as_deref().map(Path::new),
        &app_id,
        None,
    )
    .map_err(|_| AgentErrorKind::PolicyViolation)?;
    if params
        .backend
        .as_deref()
        .is_some_and(|backend| backend != store.config.backend)
    {
        return Err(AgentErrorKind::PolicyViolation);
    }
    if let Some(path) = params.db_path.as_deref() {
        let path = normalize_lifecycle_path(path).ok_or(AgentErrorKind::InvalidPath)?;
        if !store.config.matches_local_path_hint(&path) {
            return Err(AgentErrorKind::PolicyViolation);
        }
    }
    if operation == "run" {
        pharos_runtime_database::queue::complete_one_local_job(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
        )
        .map_err(|_| AgentErrorKind::PolicyViolation)?;
    }
    let (jobs, status_counts) = pharos_runtime_database::queue::local_job_report(
        store.adapter.as_ref(),
        &store.config,
        &store.schema,
    )
    .map_err(|_| AgentErrorKind::PolicyViolation)?;
    Ok(serde_json::json!({
        "schema": "pharos.agent.jobs.v1",
        "operation": operation,
        "app_id": app_id,
        "db_path": store.config.sqlite_path.as_ref().map(|path| path.to_string_lossy().into_owned()),
        "conf": params.conf,
        "case": params.case,
        "status": "ok",
        "jobs": jobs,
        "status_counts": status_counts,
    }))
}

/// Inspects or delivers one configured integration event from app-owned contracts.
pub fn run_integrations_app_tool(
    params: &IntegrationsAppParams,
    operation: &str,
) -> Result<Value, AgentErrorKind> {
    if !matches!(operation, "inspect" | "deliver") {
        return Err(AgentErrorKind::MethodNotFound);
    }
    let app_id = normalize_app_id(&params.app_id)?;
    let build_dir = params
        .build_dir
        .as_deref()
        .and_then(normalize_lifecycle_path)
        .unwrap_or_else(|| PathBuf::from("dist"));
    let built_app_root = build_dir.join("apps").join(&app_id);
    let runtime_conf = params.conf.as_deref().map(Path::new);
    let app_root = super::runtime_apps_dir(runtime_conf)
        .map(PathBuf::from)
        .map(|apps_dir| apps_dir.join(&app_id))
        .filter(|candidate| candidate.is_dir())
        .unwrap_or_else(|| built_app_root.clone());
    let app = AppRuntime {
        app_id: Some(app_id.clone()),
        app_root: Some(app_root.to_string_lossy().into_owned()),
        artifact_dir: Some(built_app_root.to_string_lossy().into_owned()),
        runtime_conf_path: params.conf.clone(),
        ..AppRuntime::default()
    };
    if super::database::relational_runtime_authority_enabled(&app_root) {
        let store = super::database::runtime_logical_app_store(&app)
            .map_err(|_| AgentErrorKind::PolicyViolation)?;
        if operation == "inspect" {
            let mut root = serde_json::json!({});
            for (entity, section) in [
                ("integration_delivery", "integration_deliveries"),
                (
                    "integration_delivery_attempt",
                    "integration_delivery_attempts",
                ),
                ("webhook_receipt", "webhook_receipts"),
            ] {
                let rows = pharos_runtime_database::integration::integration_rows(
                    store.adapter.as_ref(),
                    &store.config,
                    &store.schema,
                    entity,
                    256,
                )
                .map_err(|_| AgentErrorKind::PolicyViolation)?;
                root[section] = Value::Array(rows);
            }
            let report = super::business::dynamic_integrations_inspect_report_json(&root)
                .ok_or(AgentErrorKind::InvalidEnvelope)?;
            return serde_json::from_str(&report).map_err(|_| AgentErrorKind::InvalidEnvelope);
        }
        let integrations_text =
            fs::read_to_string(built_app_root.join("data/contracts/integrations.json"))
                .map_err(|_| AgentErrorKind::InvalidPath)?;
        let integrations_root: Value = serde_json::from_str(&integrations_text)
            .map_err(|_| AgentErrorKind::InvalidEnvelope)?;
        let mut root = serde_json::json!({"integration_deliveries": []});
        let report = super::business::dynamic_integrations_deliver_report_json(
            &mut root,
            &integrations_root,
            params
                .adapter_id
                .as_deref()
                .ok_or(AgentErrorKind::InvalidIdentifier)?,
            params.event_kind.as_deref(),
            params.resource_id.as_deref(),
            params.tenant_id.as_deref(),
            params.subject_id.as_deref(),
            params.payload_json.as_deref().unwrap_or("{}"),
        )
        .ok_or(AgentErrorKind::PolicyViolation)?;
        let row = root["integration_deliveries"][0]
            .as_object()
            .ok_or(AgentErrorKind::InvalidEnvelope)?;
        let id = pharos_runtime_database::integration::enqueue_delivery(
            store.adapter.as_ref(),
            &store.config,
            &store.schema,
            row,
        )
        .map_err(|error| {
            eprintln!("integration enqueue failed: {error:?}");
            AgentErrorKind::PolicyViolation
        })?;
        let mut report: Value =
            serde_json::from_str(&report).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
        report["processed"][0]["id"] = Value::from(id);
        report["deliveries"][0]["id"] = Value::from(id);
        return Ok(report);
    }
    let state_path =
        normalize_lifecycle_path(&params.state_path).ok_or(AgentErrorKind::InvalidPath)?;
    let _guard = super::state_store::StateMutationGuard::acquire(&state_path)
        .map_err(|_| AgentErrorKind::LockBusy)?;
    let original_state_text =
        fs::read_to_string(&state_path).map_err(|_| AgentErrorKind::InvalidPath)?;
    let mut root: Value =
        serde_json::from_str(&original_state_text).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    if operation == "inspect" {
        let report = super::business::dynamic_integrations_inspect_report_json(&root)
            .ok_or(AgentErrorKind::InvalidEnvelope)?;
        let mut report: Value =
            serde_json::from_str(&report).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
        if let Ok(store) = super::database::runtime_logical_app_store(&app)
            && store
                .schema
                .entities
                .iter()
                .any(|entity| entity.name == "webhook_receipt")
        {
            let count = store
                .adapter
                .aggregate(
                    &store.config,
                    &store.schema,
                    &pharos_runtime_database::operations::AggregateQuery {
                        entity: "webhook_receipt".to_owned(),
                        filter: None,
                        aggregate: pharos_runtime_database::operations::Aggregate::Count,
                    },
                )
                .map_err(|_| AgentErrorKind::PolicyViolation)?;
            report["counts"]["webhook_receipts"] = count;
        }
        return Ok(report);
    }
    let integrations_text =
        fs::read_to_string(built_app_root.join("data/contracts/integrations.json"))
            .map_err(|_| AgentErrorKind::InvalidPath)?;
    let integrations_root: Value =
        serde_json::from_str(&integrations_text).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    let report = super::business::dynamic_integrations_deliver_report_json(
        &mut root,
        &integrations_root,
        params
            .adapter_id
            .as_deref()
            .ok_or(AgentErrorKind::InvalidIdentifier)?,
        params.event_kind.as_deref(),
        params.resource_id.as_deref(),
        params.tenant_id.as_deref(),
        params.subject_id.as_deref(),
        params.payload_json.as_deref().unwrap_or("{}"),
    )
    .ok_or(AgentErrorKind::PolicyViolation)?;
    let state_text = serde_json::to_string(&root).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    super::fs::write_text_file(&state_path, &state_text)
        .eq(&0)
        .then_some(())
        .ok_or(AgentErrorKind::InvalidPath)?;
    let value: Value =
        serde_json::from_str(&report).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    if params.conf.is_some() {
        // Import is intentionally left to the app runtime config path and fails closed if unavailable.
    }
    Ok(value)
}

/// Executes the declared deployment gate without claiming remote transport completion.
fn execute_deploy_target(request: JsonRpcRequest) -> String {
    let params: DeployTargetParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match deploy_target_gate(&params) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Lists checked-in cross-platform targets through JSON-RPC.
fn execute_list_targets(request: JsonRpcRequest) -> String {
    let params: ListTargetsParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    let repo_root = match default_repo_root() {
        Ok(repo_root) => repo_root,
        Err(error) => return json_rpc_failure(Some(request.id), error),
    };
    let output = match params.format.unwrap_or(TargetListFormat::Json) {
        TargetListFormat::Json => target_registry_projection(&repo_root),
        TargetListFormat::Text => target_registry_list_text(&repo_root).map(|text| {
            serde_json::json!({"schema":"pharos.targets.text.v1","text":text}).to_string()
        }),
    };
    match output.and_then(|text| serde_json::from_str::<Value>(&text).map_err(|_| 70)) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(_) => json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    }
}

/// Detects the local host target through JSON-RPC.
fn execute_host_detect(request: JsonRpcRequest) -> String {
    if !request.params.is_null()
        && !request
            .params
            .as_object()
            .is_some_and(|object| object.is_empty())
    {
        return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope);
    }
    let repo_root = match default_repo_root() {
        Ok(repo_root) => repo_root,
        Err(error) => return json_rpc_failure(Some(request.id), error),
    };
    let text = host_detection_report(&repo_root, std::env::consts::OS, std::env::consts::ARCH);
    match text.and_then(|text| serde_json::from_str::<Value>(&text).map_err(|_| 70)) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(_) => json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    }
}

/// Reports production readiness for hard integration capabilities.
fn execute_production_readiness(request: JsonRpcRequest) -> String {
    let params: ProductionReadinessParams = match serde_json::from_value(request.params) {
        Ok(params) => params,
        Err(_) => return json_rpc_failure(Some(request.id), AgentErrorKind::InvalidEnvelope),
    };
    match production_readiness_report(params.app_id.as_deref()) {
        Ok(value) => json_rpc_success(request.id, value),
        Err(error) => json_rpc_failure(Some(request.id), error),
    }
}

/// Runs build, verify, or doctor through the existing generic app lifecycle dispatcher.
pub fn run_lifecycle_app_tool(
    verb: &str,
    app_id: &str,
    app_dir: Option<&str>,
    build_dir: Option<&str>,
    conf: Option<&str>,
) -> Result<Value, AgentErrorKind> {
    if !matches!(verb, "build" | "verify" | "doctor") {
        return Err(AgentErrorKind::MethodNotFound);
    }
    let app_id = normalize_app_id(app_id)?;
    let app_dir = normalize_lifecycle_path(app_dir.unwrap_or(""))
        .unwrap_or_else(|| PathBuf::from(format!("apps/{app_id}")));
    if !app_dir.join("pharos.app.yml").is_file() {
        return Err(AgentErrorKind::InvalidPath);
    }
    let build_dir = normalize_lifecycle_path(build_dir.unwrap_or("dist"))
        .unwrap_or_else(|| PathBuf::from("dist"));
    let build_dir = if build_dir.is_absolute() {
        build_dir
    } else {
        std::env::current_dir()
            .map_err(|_| AgentErrorKind::InvalidPath)?
            .join(build_dir)
    };
    let conf_path = conf.and_then(normalize_lifecycle_path);
    let mut config_record = ServeConfig {
        kind: Some("app".to_owned()),
        target_id: Some(app_id.clone()),
        conf_path: conf_path
            .as_ref()
            .map(|path| path.to_string_lossy().into_owned()),
        app_dir: Some(app_dir.to_string_lossy().into_owned()),
        build_dir: Some(build_dir.to_string_lossy().into_owned()),
        ..ServeConfig::default()
    };
    // Lifecycle inputs are relative to the active validation workspace. A
    // generated app workspace has apps/ but no repository scripts/ directory.
    let workspace_root = std::env::current_dir().map_err(|_| AgentErrorKind::InvalidPath)?;
    let report = super::handle_runtime_command_direct(
        verb,
        &mut config_record,
        Some(workspace_root.as_path()),
        None,
    )
    .map_err(|_| AgentErrorKind::PolicyViolation)?;
    serde_json::from_str(&report).map_err(|_| AgentErrorKind::InvalidEnvelope)
}

/// Applies seed data through the existing runtime migration preparation path.
pub fn seed_app_tool(
    app_id: &str,
    app_dir: Option<&str>,
    conf: Option<&str>,
    backend: &str,
) -> Result<Value, AgentErrorKind> {
    let app_id = normalize_app_id(app_id)?;
    let app_dir = normalize_lifecycle_path(app_dir.unwrap_or(""))
        .unwrap_or_else(|| PathBuf::from(format!("apps/{app_id}")));
    if !app_dir.join("pharos.app.yml").is_file() {
        return Err(AgentErrorKind::InvalidPath);
    }
    let conf_path = conf.and_then(normalize_lifecycle_path);
    let config =
        super::database::load_cli_backend_config(&app_dir, conf_path.as_deref(), Some(&app_id))
            .ok_or(AgentErrorKind::PolicyViolation)?;
    if !backend.is_empty() && config.backend != backend {
        return Err(AgentErrorKind::PolicyViolation);
    }
    if let Some(contract) = super::database::source_selected_logical_contract(
        &app_dir,
        conf_path.as_deref(),
        &app_id,
        None,
    )
    .map_err(|_| AgentErrorKind::PolicyViolation)?
    {
        let adapter = super::database::operations::resolve(&config)
            .map_err(|_| AgentErrorKind::PolicyViolation)?;
        adapter
            .ensure_database(&config, &contract.schema)
            .map_err(|_| AgentErrorKind::PolicyViolation)?;
        adapter
            .apply_contract(&config, &contract)
            .map_err(|_| AgentErrorKind::PolicyViolation)?;
        return Ok(serde_json::json!({
            "schema": "pharos.agent.seed_app.v1",
            "status": "seeded",
            "app_id": app_id,
            "backend": config.backend
        }));
    }
    // An app without a database declaration has no database seed operation.
    // Never infer an alternate migration path from files in its source tree.
    Ok(serde_json::json!({
        "schema": "pharos.agent.seed_app.v1",
        "status": "no_seed_required",
        "app_id": app_id,
        "backend": config.backend
    }))
}

/// Normalizes lifecycle paths without permitting traversal.
fn normalize_lifecycle_path(value: &str) -> Option<PathBuf> {
    let trimmed = value.trim();
    if trimmed.is_empty() {
        return None;
    }
    let path = Path::new(trimmed);
    if path.is_absolute() {
        return None;
    }
    if path
        .components()
        .any(|component| matches!(component, Component::ParentDir))
    {
        return None;
    }
    Some(path.to_path_buf())
}

/// Builds the same app runtime context used by native backup and restore entrypoints.
fn backup_restore_runtime_context(
    app_id: &str,
    app_dir: Option<&str>,
    build_dir: Option<&str>,
    conf: Option<&str>,
    state_dir: Option<&str>,
    state_path: Option<&str>,
) -> Result<(ServeConfig, AppRuntime), AgentErrorKind> {
    let app_id = normalize_app_id(app_id)?;
    let app_dir = normalize_lifecycle_path(app_dir.unwrap_or(""))
        .unwrap_or_else(|| PathBuf::from(format!("apps/{app_id}")));
    if !app_dir.is_dir() || !app_dir.join("pharos.app.yml").is_file() {
        return Err(AgentErrorKind::InvalidPath);
    }
    let build_dir_path = normalize_lifecycle_path(build_dir.unwrap_or("dist"))
        .unwrap_or_else(|| PathBuf::from("dist"));
    let conf_path = conf.and_then(normalize_lifecycle_path);
    let state_dir_path = state_dir.and_then(normalize_lifecycle_path);
    let state_path_value = state_path
        .and_then(normalize_lifecycle_path)
        .or_else(|| Some(PathBuf::from(format!("tmp/agent-state/{app_id}.json"))));
    let mut config_record = ServeConfig {
        kind: Some("app".to_owned()),
        target_id: Some(app_id.clone()),
        conf_path: conf_path
            .as_ref()
            .map(|path| path.to_string_lossy().into_owned()),
        app_dir: Some(app_dir.to_string_lossy().into_owned()),
        build_dir: Some(build_dir_path.to_string_lossy().into_owned()),
        state_dir: state_dir_path
            .as_ref()
            .map(|path| path.to_string_lossy().into_owned()),
        state_path: state_path_value
            .as_ref()
            .map(|path| path.to_string_lossy().into_owned()),
        ..ServeConfig::default()
    };
    crate::config::apply_serve_config_defaults_from_conf(&mut config_record);
    let state_path = config_record
        .state_path
        .clone()
        .or_else(|| state_path_value.map(|path| path.to_string_lossy().into_owned()))
        .ok_or(AgentErrorKind::InvalidPath)?;
    let app = AppRuntime {
        app_id: Some(app_id),
        app_root: Some(app_dir.to_string_lossy().into_owned()),
        build_dir: Some(build_dir_path.to_string_lossy().into_owned()),
        state_path: Some(state_path),
        runtime_conf_path: config_record.conf_path.clone(),
        ..AppRuntime::default()
    };
    Ok((config_record, app))
}

/// Returns a deploy gate report backed by built artifacts and target registry data.
fn deploy_target_gate(params: &DeployTargetParams) -> Result<Value, AgentErrorKind> {
    let app_id = normalize_app_id(&params.app_id)?;
    let target_id = normalize_app_id(&params.target_id)?;
    let repo_root = default_repo_root()?;
    let artifact_root = params
        .artifact_root
        .as_deref()
        .and_then(normalize_lifecycle_path)
        .unwrap_or_else(|| PathBuf::from(format!("dist/apps/{app_id}")));
    let app_dir = params
        .app_dir
        .as_deref()
        .and_then(normalize_lifecycle_path)
        .unwrap_or_else(|| artifact_root.clone());
    let absolute_app_dir = repo_root.join(&app_dir);
    let check_text =
        super::ops_bridge::build_app_deploy_check_report_local_json(&absolute_app_dir, &target_id)
            .map_err(|_| AgentErrorKind::InvalidPath)?;
    let deploy_check: Value =
        serde_json::from_str(&check_text).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    let registry_text =
        target_registry_projection(&repo_root).map_err(|_| AgentErrorKind::InvalidPath)?;
    let registry: Value =
        serde_json::from_str(&registry_text).map_err(|_| AgentErrorKind::InvalidEnvelope)?;
    let target_declared = registry
        .get("targets")
        .and_then(Value::as_array)
        .is_some_and(|targets| {
            targets.iter().any(|target| {
                target.get("target_id").and_then(Value::as_str) == Some(target_id.as_str())
            })
        });
    let status =
        if deploy_check.get("status").and_then(Value::as_str) == Some("ok") && target_declared {
            "preflight_ready"
        } else {
            "blocked"
        };
    Ok(serde_json::json!({
        "schema": "pharos.agent.deploy_target_gate.v1",
        "status": status,
        "app_id": app_id,
        "target_id": target_id,
        "target_declared": target_declared,
        "deploy_check": deploy_check,
        "remote_execution": {
            "status": "not_enabled",
            "reason": "remote target deployment requires Phase 4 transport fixtures, target credentials, rollback evidence, and explicit release authorization before execution"
        }
    }))
}

/// Reports the maturity of hard production integrations without faking missing engines.
pub fn production_readiness_report(app_id: Option<&str>) -> Result<Value, AgentErrorKind> {
    let repo_root = default_repo_root()?;
    let normalized_app_id = app_id.map(normalize_app_id).transpose()?;
    #[cfg(not(target_os = "wasi"))]
    let media_artifacts = super::agent_media::local_media_artifact_report(&repo_root);
    #[cfg(target_os = "wasi")]
    let media_artifacts = serde_json::json!({
        "schema": "pharos.agent.media_artifacts.v1",
        "status": "unavailable_on_wasi"
    });
    let offline_stt_ready = media_artifacts
        .pointer("/capabilities/offline_rust_stt")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let scanned_pdf_ocr_rust_ready = media_artifacts
        .pointer("/capabilities/scanned_pdf_ocr_rust")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let riva_speech_ready = media_artifacts
        .pointer("/capabilities/nvidia_riva_speech")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let checks = vec![
        readiness_check(
            "builtin_offline_speech_to_text",
            if offline_stt_ready {
                "available"
            } else {
                "blocked"
            },
            vec![
                readiness_prerequisite(
                    "platform speech helper available",
                    media_artifacts
                        .pointer("/features/agent_stt_rust")
                        .and_then(Value::as_bool)
                        .unwrap_or(false),
                ),
                readiness_prerequisite(
                    "workspace-local OxiWhisper GGML model artifact",
                    media_artifacts
                        .pointer("/artifacts/rust_stt_model")
                        .and_then(Value::as_str)
                        .is_some(),
                ),
                readiness_prerequisite(
                    "Rust audio decoder and Rust-native STT adapter enabled",
                    offline_stt_ready,
                ),
            ],
        ),
        readiness_check(
            "nvidia_riva_speech",
            if riva_speech_ready {
                "available_with_config"
            } else {
                "blocked"
            },
            vec![
                readiness_prerequisite(
                    "Rust-native Riva client artifact",
                    media_artifacts
                        .pointer("/artifacts/riva_client_manifest")
                        .and_then(Value::as_str)
                        .is_some(),
                ),
                readiness_prerequisite(
                    "configured Riva endpoint",
                    media_artifacts
                        .pointer("/artifacts/riva_endpoint_configured")
                        .and_then(Value::as_bool)
                        .unwrap_or(false),
                ),
                readiness_prerequisite(
                    "Riva execution adapter implemented",
                    media_artifacts
                        .pointer("/features/agent_riva_rust")
                        .and_then(Value::as_bool)
                        .unwrap_or(false),
                ),
                readiness_prerequisite("Rust-native local integration fixture", riva_speech_ready),
            ],
        ),
        readiness_check(
            "ocr_scanned_pdf_extraction",
            if scanned_pdf_ocr_rust_ready {
                "available_with_config"
            } else {
                "blocked"
            },
            vec![
                readiness_prerequisite(
                    "platform scanned-PDF helper available",
                    media_artifacts
                        .pointer("/features/agent_pdf_ocr_rust")
                        .and_then(Value::as_bool)
                        .unwrap_or(false),
                ),
                readiness_prerequisite(
                    "workspace-local OCRS detection model",
                    media_artifacts
                        .pointer("/artifacts/ocrs_detection_model")
                        .and_then(Value::as_str)
                        .is_some(),
                ),
                readiness_prerequisite(
                    "workspace-local OCRS recognition model",
                    media_artifacts
                        .pointer("/artifacts/ocrs_recognition_model")
                        .and_then(Value::as_str)
                        .is_some(),
                ),
                readiness_prerequisite(
                    "bounded Rust-native scanned-PDF OCR adapter",
                    scanned_pdf_ocr_rust_ready,
                ),
                readiness_prerequisite("extractable-text PDF parser", true),
                readiness_prerequisite(
                    "Rust-native PDF rasterizer/image extractor",
                    media_artifacts
                        .pointer("/artifacts/rust_pdf_rasterizer_manifest")
                        .and_then(Value::as_str)
                        .is_some(),
                ),
            ],
        ),
        readiness_check(
            "live_external_integration_delivery",
            "available_with_config",
            vec![
                readiness_prerequisite("built app integrations contract", true),
                readiness_prerequisite("state path", true),
                readiness_prerequisite("configured adapter env refs", true),
            ],
        ),
        readiness_check(
            "scheduled_job_execution",
            "available",
            vec![
                readiness_prerequisite("SQLite app DB", true),
                readiness_prerequisite("jobs contract/migrations", true),
                readiness_prerequisite("idempotent execution proof", true),
            ],
        ),
        readiness_check(
            "backup_restore_execution",
            "available",
            vec![
                readiness_prerequisite("SQLite DB", true),
                readiness_prerequisite("state path", true),
                readiness_prerequisite("backup output/input directory", true),
            ],
        ),
        readiness_check(
            "target_deployment_execution",
            "preflight_only",
            vec![
                readiness_prerequisite("built app artifact", true),
                readiness_prerequisite("declared target", true),
                readiness_prerequisite("Phase 4 remote transport fixture and credentials", false),
            ],
        ),
    ];
    Ok(serde_json::json!({
        "schema": "pharos.agent.production_readiness.v1",
        "app_id": normalized_app_id,
        "repo_root": repo_root.to_string_lossy(),
        "status": readiness_rollup_status(&checks),
        "local_detection": {
            "media_artifacts": media_artifacts
        },
        "checks": checks,
        "policy": "Hard capabilities must fail closed until their local engine, model, credential, or target transport prerequisite is present and tested."
    }))
}

fn readiness_check(capability_id: &str, status: &str, prerequisites: Vec<Value>) -> Value {
    serde_json::json!({
        "capability_id": capability_id,
        "status": status,
        "missing_or_required": prerequisites,
    })
}

fn readiness_prerequisite(name: &str, present: bool) -> Value {
    serde_json::json!({"name": name, "present": present})
}

fn readiness_rollup_status(checks: &[Value]) -> &'static str {
    if checks
        .iter()
        .any(|check| check.get("status").and_then(Value::as_str) == Some("blocked"))
    {
        "blocked_on_external_artifacts"
    } else if checks
        .iter()
        .any(|check| check.get("status").and_then(Value::as_str) == Some("preflight_only"))
    {
        "preflight_only"
    } else {
        "available"
    }
}

/// Resolves the current Pharos repository root for local agent commands.
fn default_repo_root() -> Result<PathBuf, AgentErrorKind> {
    let cwd = std::env::current_dir().map_err(|_| AgentErrorKind::InvalidPath)?;
    let mut current = Some(cwd.as_path());
    while let Some(path) = current {
        if path.join("apps").is_dir() && path.join("scripts").is_dir() {
            return path.canonicalize().map_err(|_| AgentErrorKind::InvalidPath);
        }
        current = path.parent();
    }
    Err(AgentErrorKind::InvalidPath)
}

fn json_rpc_success<T: Serialize>(id: String, data: T) -> String {
    pharos_runtime_architect::json_rpc::json_rpc_success(id, data)
}

/// Serializes a JSON-RPC failure envelope with stable advice.
fn json_rpc_failure(id: Option<String>, kind: AgentErrorKind) -> String {
    pharos_runtime_architect::json_rpc::json_rpc_failure(id, kind)
}

/// Parses a bounded JSON-RPC request envelope.
pub fn parse_json_rpc_request(input: &str) -> Result<JsonRpcRequest, AgentErrorKind> {
    pharos_runtime_architect::json_rpc::parse_json_rpc_request(input)
}

/// Validates the JSON-RPC envelope fields used for dispatch.
pub fn validate_json_rpc_request(request: &JsonRpcRequest) -> Result<(), AgentErrorKind> {
    pharos_runtime_architect::json_rpc::validate_json_rpc_request(request)
}

/// Parses and validates one versioned target profile document.
pub fn parse_target_profile(input: &str) -> Result<TargetProfile, AgentErrorKind> {
    let profile: TargetProfile =
        serde_json::from_str(input).map_err(|_| AgentErrorKind::InvalidJson)?;
    validate_target_profile(&profile)?;
    Ok(profile)
}

/// Validates target-profile policy without requiring any tracked target addresses.
pub fn validate_target_profile(profile: &TargetProfile) -> Result<(), AgentErrorKind> {
    if profile.schema != "pharos.agent.target_profile.v1" {
        return Err(AgentErrorKind::InvalidEnvelope);
    }
    normalize_app_id(&profile.target_id)?;
    if profile.allowed_app_ids.is_empty() {
        return Err(AgentErrorKind::PolicyViolation);
    }
    for app_id in &profile.allowed_app_ids {
        normalize_app_id(app_id)?;
    }
    for secret_ref in &profile.secret_refs {
        validate_secret_ref(secret_ref)?;
        if secret_token_like(secret_ref) {
            return Err(AgentErrorKind::SecretRedacted);
        }
    }
    match (profile.transport, profile.artifact_kind) {
        (TargetTransport::SshDebian, ArtifactKind::NativePackage)
        | (TargetTransport::OciRegistry, ArtifactKind::OciService)
        | (TargetTransport::Kubernetes, ArtifactKind::OciService) => {}
        _ => return Err(AgentErrorKind::PolicyViolation),
    }
    if profile.environment == TargetEnvironment::Production && profile.secret_refs.is_empty() {
        return Err(AgentErrorKind::PolicyViolation);
    }
    Ok(())
}

/// Validates deterministic product knowledge outputs without writing files.
pub fn check_product_knowledge(repo_root: &Path) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::check_product_knowledge(repo_root)
}

/// Validates written product knowledge artifacts against the current source fingerprint.
pub fn check_written_product_knowledge(
    repo_root: &Path,
    output_root: &Path,
) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::check_written_product_knowledge(
        repo_root,
        output_root,
    )
}

/// Writes deterministic product knowledge outputs for the Architect webapp agent.
pub fn write_product_knowledge(repo_root: &Path, output_root: &Path) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::write_product_knowledge(repo_root, output_root)
}

/// Builds the deterministic agent sync report used by local hooks and checks.
pub fn agent_sync_report(
    repo_root: &Path,
    output_root: &Path,
    check_only: bool,
    changed_paths: &[String],
    requested_features: &[String],
) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::agent_sync_report(
        repo_root,
        output_root,
        check_only,
        changed_paths,
        requested_features,
    )
}

pub fn product_knowledge_outputs(repo_root: &Path) -> Result<Vec<(&'static str, Value)>, i32> {
    pharos_runtime_architect::product_knowledge::product_knowledge_outputs(repo_root)
}

#[cfg(test)]
/// Validates generated product knowledge documents through the Architect crate.
fn validate_product_knowledge_documents(
    repo_root: &Path,
    outputs: &[(&'static str, Value)],
) -> Result<Value, i32> {
    pharos_runtime_architect::product_knowledge::validate_product_knowledge_documents(
        repo_root, outputs,
    )
}

#[cfg(test)]
/// Returns product-knowledge source files through the Architect crate.
fn knowledge_source_files(repo_root: &Path) -> Vec<String> {
    pharos_runtime_architect::product_knowledge::knowledge_source_files(repo_root)
}

#[cfg(test)]
/// Computes a product-knowledge fingerprint with in-memory overrides.
fn source_fingerprint_with_overrides(
    repo_root: &Path,
    source_files: &[String],
    overrides: &BTreeMap<String, Vec<u8>>,
) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::source_fingerprint_with_overrides(
        repo_root,
        source_files,
        overrides,
    )
}

#[cfg(test)]
/// Writes one pretty JSON output file with a trailing newline.
fn write_json_output(path: &Path, value: &Value) -> Result<(), i32> {
    let text = serde_json::to_string_pretty(value).map_err(|_| 70)?;
    fs::write(path, format!("{text}\n")).map_err(|_| 73)
}

/// Emits the registry-declared target catalog as a stable JSON projection.
pub fn target_registry_projection(repo_root: &Path) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::target_registry_projection(repo_root)
}

/// Emits a bounded human-readable target list backed by the registry file.
pub fn target_registry_list_text(repo_root: &Path) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::target_registry_list_text(repo_root)
}

/// Detects the local host build target using the registry-backed native target map.
pub fn host_detection_report(repo_root: &Path, os: &str, arch: &str) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::host_detection_report(repo_root, os, arch)
}

/// Writes the Phase 0 agent baseline inventory into the requested repository-local directory.
pub fn write_baseline_inventory(repo_root: &Path, output_root: &Path) -> Result<String, i32> {
    pharos_runtime_architect::product_knowledge::write_baseline_inventory(repo_root, output_root)
}

/// Builds the Phase 0 baseline inventory document from the current source tree.
pub fn baseline_inventory_value(repo_root: &Path) -> Result<Value, i32> {
    pharos_runtime_architect::product_knowledge::baseline_inventory_value(repo_root)
}

/// Returns the currently active top-level CLI verbs known at the native entrypoint.
pub fn active_cli_verbs() -> Vec<Value> {
    pharos_runtime_architect::product_knowledge::active_cli_verbs()
}

/// Returns the stable report identifiers used by active runtime app lifecycle verbs.
pub fn runtime_report_identifiers() -> Vec<Value> {
    pharos_runtime_architect::product_knowledge::runtime_report_identifiers()
}

fn repo_relative_path(repo_root: &Path, path: &Path) -> String {
    pharos_runtime_architect::product_knowledge::repo_relative_path(repo_root, path)
}

#[cfg(test)]
fn read_json_file(path: &Path) -> Result<Value, i32> {
    pharos_runtime_architect::product_knowledge::read_json_file(path)
}

#[cfg(test)]
fn read_target_registry(repo_root: &Path) -> Result<Value, i32> {
    pharos_runtime_architect::product_knowledge::read_target_registry(repo_root)
}

#[cfg(test)]
fn registry_targets(registry: &Value) -> Result<Vec<Value>, i32> {
    pharos_runtime_architect::product_knowledge::registry_targets(registry)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::{SystemTime, UNIX_EPOCH};

    /// Returns the repository root for tests that inspect checked-in fixtures.
    fn repo_root() -> PathBuf {
        PathBuf::from(env!("CARGO_MANIFEST_DIR"))
    }

    fn bridge_test_lock() -> std::sync::MutexGuard<'static, ()> {
        pharos_runtime_architect::lifecycle_validation::architect_current_dir_lock()
            .lock()
            .expect("bridge test lock")
    }

    #[test]
    fn lifecycle_build_accepts_generated_workspace_outside_repository() {
        let _guard = bridge_test_lock();
        let root = temp_root("lifecycle-outside-repo");
        pharos_runtime_architect::scaffold::scaffold_app("outside_repo", &root.join("apps"))
            .expect("scaffold generated app");
        assert!(!root.join("scripts").exists());
        let original_dir = std::env::current_dir().expect("original directory");
        std::env::set_current_dir(&root).expect("generated workspace directory");
        let results = ["build", "verify", "doctor"].map(|verb| {
            (
                verb,
                run_lifecycle_app_tool(
                    verb,
                    "outside_repo",
                    Some("apps/outside_repo"),
                    Some("dist"),
                    None,
                ),
            )
        });
        std::env::set_current_dir(original_dir).expect("restore directory");
        for (verb, result) in results {
            assert!(result.is_ok(), "generated workspace {verb}: {result:?}");
        }
    }

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

    /// Returns cloned product knowledge outputs after mutating one named output.
    fn mutated_product_outputs<F>(
        outputs: &[(&'static str, Value)],
        target_name: &str,
        mut mutate: F,
    ) -> Vec<(&'static str, Value)>
    where
        F: FnMut(&mut Value),
    {
        outputs
            .iter()
            .map(|(name, value)| {
                let mut cloned = value.clone();
                if *name == target_name {
                    mutate(&mut cloned);
                }
                (*name, cloned)
            })
            .collect()
    }

    /// Asserts one mutated product knowledge set returns a diagnostic maturity failure.
    fn assert_maturity_failure(
        repo: &Path,
        outputs: &[(&'static str, Value)],
        expected_check: &str,
    ) {
        let report = validate_product_knowledge_documents(repo, outputs).expect("failure report");
        assert_eq!(report.get("status").and_then(Value::as_str), Some("failed"));
        assert!(
            report
                .pointer("/maturity/failed_checks")
                .and_then(Value::as_array)
                .expect("failed checks")
                .iter()
                .any(|value| value.as_str() == Some(expected_check)),
            "missing diagnostic failure for {expected_check}: {report}"
        );
    }

    #[test]
    /// Proves plan, inspect, and apply perform a bounded app-owned text transaction.
    fn json_rpc_plans_inspects_and_applies_app_change() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-transaction");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        pharos_runtime_architect::scaffold::scaffold_app("agent_tx", &root.join("apps"))
            .expect("scaffold");
        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let plan_request = serde_json::json!({
            "jsonrpc": "2.0",
            "id": "req-plan",
            "method": "pharos.plan_app_change",
            "params": {
                "app_id": "agent_tx",
                "file_patches": [{
                    "path": "apps/agent_tx/data/features/agent-note.yml",
                    "expected_sha256": null,
                    "content": "contract_version: \"1.0\"\nfeature_id: agent_note\n"
                }]
            }
        })
        .to_string();
        let plan_response = execute_json_rpc(&plan_request);
        let plan_value: Value = serde_json::from_str(&plan_response).expect("plan response");
        let digest = plan_value
            .pointer("/result/data/plan_digest")
            .and_then(Value::as_str)
            .expect("digest")
            .to_owned();
        let inspect_response = execute_json_rpc(
            &serde_json::json!({
                "jsonrpc": "2.0",
                "id": "req-inspect",
                "method": "pharos.inspect_change",
                "params": {"app_id": "agent_tx", "change_digest": digest}
            })
            .to_string(),
        );
        let inspect_value: Value = serde_json::from_str(&inspect_response).expect("inspect");
        assert_eq!(
            inspect_value
                .pointer("/result/data/files/0/path")
                .and_then(Value::as_str),
            Some("apps/agent_tx/data/features/agent-note.yml")
        );
        let apply_response = execute_json_rpc(
            &serde_json::json!({
                "jsonrpc": "2.0",
                "id": "req-apply",
                "method": "pharos.apply_app_change",
                "params": {"app_id": "agent_tx", "plan_digest": digest}
            })
            .to_string(),
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        let apply_value: Value = serde_json::from_str(&apply_response).expect("apply");
        assert_eq!(
            apply_value
                .pointer("/result/data/status")
                .and_then(Value::as_str),
            Some("applied")
        );
        assert!(
            root.join("apps/agent_tx/data/features/agent-note.yml")
                .is_file()
        );
    }

    #[test]
    /// Proves similar-app requests preserve semantic archetype ids without copying source trees.
    fn synthesize_app_model_uses_existing_app_as_semantic_archetype() {
        let _bridge_test_guard = bridge_test_lock();
        let synthesis = synthesize_builtin_app_model(
            "todo_clone",
            "Create a todo webapp similar to todo_list",
            Some("todo_list"),
        )
        .expect("synthesis");
        assert_eq!(synthesis.model.archetype_id, "todo_list");
        assert_eq!(synthesis.model.entities[0].id, "task");
    }

    #[test]
    /// Proves generated CRUD and static-page template patches use the same transaction path.
    fn plan_app_change_accepts_generated_crud_and_static_page_fixtures() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-patterns");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        pharos_runtime_architect::scaffold::scaffold_app("agent_patterns", &root.join("apps"))
            .expect("scaffold");
        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let plan = plan_app_change(
            "agent_patterns",
            vec![
                FilePatch {
                    encoding: Default::default(),
                    path: "apps/agent_patterns/templates/generated_admin/item_admin.html"
                        .to_owned(),
                    expected_sha256: None,
                    content: "<section data-generated-surface=\"crud\">{title}</section>\n"
                        .to_owned(),
                },
                FilePatch {
                    encoding: Default::default(),
                    path: "apps/agent_patterns/templates/pages/about.html".to_owned(),
                    expected_sha256: None,
                    content: "<main><h1>About</h1><p>{summary}</p></main>\n".to_owned(),
                },
            ],
        )
        .expect("plan");
        let inspected = inspect_change_plan("agent_patterns", &plan.plan_digest).expect("inspect");
        assert_eq!(
            inspected.pointer("/files/0/path").and_then(Value::as_str),
            Some("apps/agent_patterns/templates/generated_admin/item_admin.html")
        );
        apply_app_change("agent_patterns", &plan.plan_digest).expect("apply");
        std::env::set_current_dir(original_dir).expect("restore dir");
        assert!(
            root.join("apps/agent_patterns/templates/generated_admin/item_admin.html")
                .is_file()
        );
        assert!(
            root.join("apps/agent_patterns/templates/pages/about.html")
                .is_file()
        );
    }

    #[test]
    /// Proves whole-root replacement attempts are rejected before planning.
    fn plan_app_change_rejects_root_replacement() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-root-reject");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        pharos_runtime_architect::scaffold::scaffold_app("agent_tx", &root.join("apps"))
            .expect("scaffold");
        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let rejected = plan_app_change(
            "agent_tx",
            vec![FilePatch {
                encoding: Default::default(),
                path: "apps/agent_tx".to_owned(),
                expected_sha256: None,
                content: "replace root".to_owned(),
            }],
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        assert_eq!(rejected.err(), Some(AgentErrorKind::InvalidPath));
    }

    #[test]
    /// Proves an apply failure restores files already changed in the transaction.
    fn apply_app_change_rolls_back_after_injected_stale_file() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-rollback");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        pharos_runtime_architect::scaffold::scaffold_app("agent_tx", &root.join("apps"))
            .expect("scaffold");
        let first_path = root.join("apps/agent_tx/data/features/agent-note.yml");
        let readme_path = root.join("apps/agent_tx/README.md");
        let original_readme = fs::read_to_string(&readme_path).expect("readme");
        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let plan = plan_app_change(
            "agent_tx",
            vec![
                FilePatch {
                    encoding: Default::default(),
                    path: "apps/agent_tx/data/features/agent-note.yml".to_owned(),
                    expected_sha256: None,
                    content: "contract_version: \"1.0\"\nfeature_id: agent_note\n".to_owned(),
                },
                FilePatch {
                    encoding: Default::default(),
                    path: "apps/agent_tx/README.md".to_owned(),
                    expected_sha256: Some("0".repeat(64)),
                    content: "# Replaced\n".to_owned(),
                },
            ],
        )
        .expect("plan");
        let applied = apply_app_change("agent_tx", &plan.plan_digest);
        std::env::set_current_dir(original_dir).expect("restore dir");
        assert_eq!(applied.err(), Some(AgentErrorKind::StalePlan));
        assert!(!first_path.exists());
        assert_eq!(
            fs::read_to_string(readme_path).expect("readme"),
            original_readme
        );
    }

    #[test]
    /// Proves authoring plans reject writes outside the named app root.
    fn plan_app_change_rejects_out_of_app_patch() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-transaction-reject");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        pharos_runtime_architect::scaffold::scaffold_app("agent_tx", &root.join("apps"))
            .expect("scaffold");
        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let rejected = plan_app_change(
            "agent_tx",
            vec![FilePatch {
                encoding: Default::default(),
                path: "apps/other_app/data/features/bad.yml".to_owned(),
                expected_sha256: None,
                content: "feature_id: bad\n".to_owned(),
            }],
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        assert_eq!(rejected.err(), Some(AgentErrorKind::InvalidPath));
    }

    #[test]
    /// Proves JSON-RPC reads an existing app model without mutating source.
    fn json_rpc_reads_existing_app_model() {
        let _bridge_test_guard = bridge_test_lock();
        let response = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"req-read","method":"pharos.read_app_model","params":{"app_id":"todo_list"}}"#,
        );
        let value: Value = serde_json::from_str(&response).expect("response");
        assert_eq!(
            value.pointer("/result/data/app_id").and_then(Value::as_str),
            Some("todo_list")
        );
        assert!(
            value
                .pointer("/result/data/manifest/asset_keys")
                .and_then(Value::as_array)
                .is_some_and(|keys| keys.iter().any(|key| key.as_str() == Some("static_dir")))
        );
        assert!(
            value
                .pointer("/result/data/manifest/contract_keys")
                .and_then(Value::as_array)
                .is_some_and(|keys| !keys.is_empty())
        );
    }

    #[test]
    /// Proves JSON-RPC scaffold uses the shared scaffold helper and rejects artifact output roots.
    fn json_rpc_scaffolds_app_with_repo_relative_output() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-scaffold");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        fs::create_dir_all(root.join("tmp")).expect("tmp");
        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let response = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"req-scaffold","method":"pharos.scaffold_app","params":{"app_id":"agent_scaffolded","output_root":"tmp"}}"#,
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        let value: Value = serde_json::from_str(&response).expect("response");
        assert_eq!(
            value.pointer("/result/data/status").and_then(Value::as_str),
            Some("created")
        );
        assert_eq!(
            value
                .pointer("/result/data/app_root")
                .and_then(Value::as_str),
            Some("tmp/agent_scaffolded")
        );
        assert!(root.join("tmp/agent_scaffolded/pharos.app.yml").is_file());

        let original_dir = std::env::current_dir().expect("current dir");
        std::env::set_current_dir(&root).expect("chdir");
        let rejected = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"req-artifact","method":"pharos.scaffold_app","params":{"app_id":"bad_output","output_root":"target/agent"}}"#,
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        let rejected_value: Value = serde_json::from_str(&rejected).expect("rejected");
        assert_eq!(
            rejected_value
                .pointer("/error/message")
                .and_then(Value::as_str),
            Some("policy_violation")
        );
    }

    #[test]
    /// Proves JSON-RPC can call the built-in app-model synthesis method safely.
    fn json_rpc_executes_builtin_app_model_synthesis() {
        let _bridge_test_guard = bridge_test_lock();
        let response = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"req-1","method":"pharos.synthesize_app_model","params":{"app_id":"starter_builder","requirement":"Create a todo webapp for tasks","provider_id":"builtin"}}"#,
        );
        let value: Value = serde_json::from_str(&response).expect("response");
        assert_eq!(value.get("jsonrpc").and_then(Value::as_str), Some("2.0"));
        assert_eq!(
            value
                .pointer("/result/data/provider_id")
                .and_then(Value::as_str),
            Some("builtin")
        );
        assert_eq!(
            value
                .pointer("/result/data/model/entities/0/id")
                .and_then(Value::as_str),
            Some("task")
        );
        let rejected = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"req-2","method":"pharos.synthesize_app_model","params":{"app_id":"starter_builder","requirement":"Create app","provider_id":"cloud"}}"#,
        );
        let rejected_value: Value = serde_json::from_str(&rejected).expect("rejected");
        assert_eq!(
            rejected_value
                .pointer("/error/message")
                .and_then(Value::as_str),
            Some("policy_violation")
        );
    }

    #[test]
    /// Proves the built-in app-model synthesizer creates a bounded useful baseline model.
    fn builtin_app_model_synthesis_creates_baseline_model() {
        let _bridge_test_guard = bridge_test_lock();
        let synthesis = synthesize_builtin_app_model(
            "starter_builder",
            "Create a todo webapp for tracking tasks",
            None,
        )
        .expect("synthesis");
        assert_eq!(synthesis.provider_id, "builtin");
        assert_eq!(synthesis.model.app_id, "starter_builder");
        assert_eq!(synthesis.model.entities[0].id, "task");
        assert!(
            synthesis
                .model
                .capabilities
                .contains(&"record_workflow".to_owned())
        );
        assert!(
            synthesis
                .model
                .capabilities
                .contains(&"dynamic_app_persistence".to_owned())
        );
        assert!(
            !synthesis
                .model
                .capabilities
                .contains(&"sqlite_runtime_state".to_owned())
        );
        assert!(synthesis.model.navigation.contains(&"Tasks".to_owned()));
        assert!(
            synthesis.model.ui_archetypes.iter().any(|archetype| {
                archetype.archetype_id == "form.compact_labeled_control_row.v1"
                    && archetype.ui_type == "form_layout"
                    && archetype
                        .css_tokens
                        .iter()
                        .any(|token| token == "form-grid" || token == "field")
                    && archetype
                        .source_examples
                        .iter()
                        .any(|source| source.starts_with("apps/"))
            }),
            "record-note synthesis should select compact form archetype from app examples"
        );
        assert!(
            synthesis.model.ui_archetypes.iter().any(|archetype| {
                archetype.archetype_id == "card.record_grid_with_empty_state.v1"
            }),
            "record-note synthesis should select record grid archetype"
        );
        assert!(
            synthesis
                .model
                .knowledge_sources
                .contains(&"docs/reference/library-reference.md".to_owned())
        );
        assert!(
            synthesis
                .model
                .knowledge_sources
                .contains(&"docs/reference/ui-styling-guide.md".to_owned())
        );
        assert!(
            synthesis
                .model
                .knowledge_sources
                .contains(&"target/agent/runtime-map.json#rustdoc".to_owned())
        );
        assert!(
            synthesis
                .model
                .acceptance_criteria
                .iter()
                .any(|criterion| criterion.id == "route_home_loads"
                    && criterion.category == "route"
                    && criterion.required)
        );
        assert!(
            synthesis
                .model
                .acceptance_criteria
                .iter()
                .any(|criterion| criterion.id == "task_form_submits"
                    && criterion.category == "interaction")
        );
        assert_eq!(
            synthesis.model.routes[0].template,
            "templates/pages/home.html"
        );
        let tabbed = synthesize_builtin_app_model(
            "hello_tabs",
            "make a dynamic hellow world spa with 2 tabs in the nav and flashing green orange text",
            None,
        )
        .expect("tabbed synthesis");
        assert!(tabbed.model.capabilities.contains(&"tabbed_spa".to_owned()));
        assert!(
            tabbed
                .model
                .capabilities
                .contains(&"animated_visual_state".to_owned())
        );
        assert!(
            !tabbed
                .model
                .capabilities
                .contains(&"record_workflow".to_owned())
        );
        assert!(tabbed.model.actions.is_empty());
        assert_eq!(
            tabbed.model.navigation,
            vec!["Home".to_owned(), "Tab 1".to_owned(), "Tab 2".to_owned()]
        );
        assert!(
            tabbed
                .model
                .ui_archetypes
                .iter()
                .any(|archetype| archetype.archetype_id == "panel.tabbed_spa_content.v1")
        );
        let catalog = synthesize_builtin_app_model(
            "catalog_app",
            "Create a commerce catalog webapp for products with SKU and price",
            None,
        )
        .expect("catalog synthesis");
        assert_eq!(catalog.model.app_family_id, "commerce_catalog");
        assert_eq!(catalog.model.entities[0].id, "product");
        assert!(catalog.model.entities[0].fields.contains(&"sku".to_owned()));
        assert!(
            catalog.model.entities[0]
                .fields
                .contains(&"amount".to_owned())
        );
        assert!(
            catalog
                .model
                .knowledge_sources
                .contains(&"apps/commerce_spa/pharos.app.yml".to_owned())
        );
        assert!(catalog.model.ui_archetypes.iter().any(|archetype| {
            archetype.archetype_id == "card.product_media_purchase.v1"
                && archetype.selection_rule == "preferred"
        }));
        let booking = synthesize_builtin_app_model(
            "booking_app",
            "Create a booking scheduler with appointment time and customer contact",
            None,
        )
        .expect("booking synthesis");
        assert_eq!(booking.model.app_family_id, "booking_scheduler");
        assert_eq!(booking.model.entities[0].id, "booking");
        assert!(
            booking.model.entities[0]
                .fields
                .contains(&"scheduled_at".to_owned())
        );
        assert!(
            booking.model.entities[0]
                .fields
                .contains(&"contact".to_owned())
        );
        assert!(
            booking
                .model
                .knowledge_sources
                .contains(&"apps/ucal/pharos.app.yml".to_owned())
        );
        assert!(booking.model.ui_archetypes.iter().any(|archetype| {
            archetype.archetype_id == "card.record_grid_with_empty_state.v1"
                && archetype.selection_rule == "booking list or schedule card grid"
        }));
        let dashboard = synthesize_builtin_app_model(
            "metrics_app",
            "Create a dashboard webapp for metrics and KPI reports",
            None,
        )
        .expect("dashboard synthesis");
        assert_eq!(dashboard.model.app_family_id, "dashboard");
        assert!(
            dashboard
                .model
                .capabilities
                .contains(&"dashboard_metrics".to_owned())
        );
        assert!(dashboard.model.navigation.contains(&"Metrics".to_owned()));
        assert!(dashboard.model.ui_archetypes.iter().any(|archetype| {
            archetype.archetype_id == "card.metric_stat_grid.v1"
                && archetype.selection_rule == "preferred"
        }));
        assert!(dashboard.model.ui_archetypes.iter().any(|archetype| {
            archetype.archetype_id == "form.editable_select_option_manager.v1"
                && archetype.selection_rule.contains("KPI categories")
        }));
        for field in [
            "category",
            "metric_type",
            "target_value",
            "trend",
            "scheduled_at",
        ] {
            assert!(
                dashboard.model.entities[0]
                    .fields
                    .contains(&field.to_owned()),
                "missing dashboard field {field}"
            );
        }
        assert!(
            !dashboard.model.entities[0]
                .fields
                .contains(&"period".to_owned())
        );
        let dashboard_patches =
            builtin_authoring_patches(&dashboard.model).expect("dashboard patches");
        let dashboard_home = dashboard_patches
            .iter()
            .find(|patch| patch.path.ends_with("templates/home.body.html"))
            .map(|patch| patch.content.as_str())
            .expect("dashboard home template");
        assert!(
            dashboard_home.contains(r#"name="category""#)
                && dashboard_home.contains("Financial Health")
        );
        assert!(
            dashboard_home.contains(r#"name="metric_type""#)
                && dashboard_home.contains("Business KPI")
        );
        assert!(
            dashboard_home.contains(r#"name="target_value""#)
                && dashboard_home.contains(r#"max="9999""#)
        );
        assert!(
            dashboard_home.contains(r#"class="form-line kpi-line kpi-line--top top_row""#)
                && dashboard_home.contains(r#"name="scheduled_at""#)
                && dashboard_home.contains(r#"line-cell line-cell--at""#)
        );
        assert!(
            dashboard_home.contains("icon-action-button--submit")
                && dashboard_home.contains("Add metric")
        );
        let dashboard_iteration = synthesize_builtin_app_model(
            "dashboard_app",
            r#"reorder top row so that Metric Type is followed by Category and then Metric or work item

Existing generated app context for same output_app_id. Preserve existing app behavior unless the new request explicitly replaces it, and apply this request as an iteration on the existing app.
--- README.md ---
Dashboard App is a Pharos KPI dashboard with selectable product/app performance and business intelligence metrics. Architect resolved these Pharos capabilities from the brief: app family dashboard, dashboard metrics.
--- templates/home.body.html ---
<main class="starter-shell architect-built family-dashboard" data-ui-archetypes="card.metric_stat_grid.v1 form.editable_select_option_manager.v1"></main>"#,
            None,
        )
        .expect("dashboard iteration synthesis");
        assert_eq!(dashboard_iteration.model.app_family_id, "dashboard");
        assert_eq!(dashboard_iteration.model.entities[0].id, "metric");
        assert_eq!(dashboard_iteration.model.actions[0].id, "create_metric");
        assert!(
            dashboard_iteration
                .model
                .ui_archetypes
                .iter()
                .any(|archetype| { archetype.archetype_id.contains("metric_stat_grid") })
        );

        let iteration = synthesize_builtin_app_model(
            "worker_notes",
            "Add priority to the existing generated notes app and make the same output_app_id build CRUD existing records.

Existing generated app context for same output_app_id. Preserve existing app behavior unless the new request explicitly replaces it, and apply this request as an iteration on the existing app.
--- data/contracts/entities.yml ---
contract_version: \"1.0\"
entities:
- entity_id: note
  table: note
  identity_field: id
  fields:
  - {field_id: id}
  - {field_id: title}
  - {field_id: customer_phone}
  - {field_id: note}
  - {field_id: created_at}
--- README.md ---
Existing worker notes app.
",
            None,
        )
        .expect("iteration synthesis");
        assert_eq!(iteration.model.entities[0].id, "note");
        for field in ["customer_phone", "priority"] {
            assert!(
                iteration.model.entities[0]
                    .fields
                    .contains(&field.to_owned()),
                "same-app iteration did not preserve/add field {field}"
            );
        }
        for action_id in ["create_note", "update_note", "delete_note"] {
            assert!(
                iteration
                    .model
                    .actions
                    .iter()
                    .any(|action| action.id == action_id),
                "same-app iteration missing action {action_id}"
            );
        }
        assert!(
            iteration
                .model
                .capabilities
                .contains(&"existing_entity_iteration".to_owned())
        );
        assert!(
            iteration
                .model
                .capabilities
                .contains(&"crud_record_workflow".to_owned())
        );
        let iteration_patches =
            builtin_authoring_patches(&iteration.model).expect("iteration patches");
        let feature = iteration_patches
            .iter()
            .find(|patch| patch.path.ends_with("data/features/starter.yml"))
            .map(|patch| patch.content.as_str())
            .expect("iteration feature contract");
        assert!(feature.contains("update_note:") && feature.contains("path: /items/update"));
        assert!(feature.contains("delete_note:") && feature.contains("path: /items/delete"));
        assert!(feature.contains("customer_phone: input.customer_phone"));
        let card = iteration_patches
            .iter()
            .find(|patch| patch.path.ends_with("templates/fragments/item_card.html"))
            .map(|patch| patch.content.as_str())
            .expect("iteration card fragment");
        assert!(card.contains(r#"pharos-action="update_note""#));
        assert!(card.contains(r#"pharos-action="delete_note""#));
        let field_crud_iteration = synthesize_builtin_app_model(
            "worker_notes",
            "Rename field customer_phone to phone, add field account tier, and remove field legacy_code from the existing generated notes app.

Existing generated app context for same output_app_id. Preserve existing app behavior unless the new request explicitly replaces it, and apply this request as an iteration on the existing app.
--- data/contracts/entities.yml ---
contract_version: \"1.0\"
entities:
- entity_id: note
  table: note
  identity_field: id
  fields:
  - {field_id: id}
  - {field_id: title}
  - {field_id: customer_phone}
  - {field_id: legacy_code}
  - {field_id: note}
  - {field_id: created_at}
--- README.md ---
Existing worker notes app.
",
            None,
        )
        .expect("field CRUD iteration synthesis");
        let field_ids = &field_crud_iteration.model.entities[0].fields;
        assert!(
            field_ids.contains(&"phone".to_owned()),
            "rename target missing: {field_ids:?}"
        );
        assert!(
            field_ids.contains(&"account_tier".to_owned()),
            "added field missing: {field_ids:?}"
        );
        assert!(
            !field_ids.contains(&"customer_phone".to_owned()),
            "renamed field was not removed: {field_ids:?}"
        );
        assert!(
            !field_ids.contains(&"legacy_code".to_owned()),
            "removed field survived: {field_ids:?}"
        );
        let field_crud_patches =
            builtin_authoring_patches(&field_crud_iteration.model).expect("field CRUD patches");
        let field_crud_entities = field_crud_patches
            .iter()
            .find(|patch| patch.path.ends_with("data/contracts/entities.yml"))
            .map(|patch| patch.content.as_str())
            .expect("field CRUD entities contract");
        assert!(field_crud_entities.contains("field_id: phone"));
        assert!(field_crud_entities.contains("field_id: account_tier"));
        assert!(!field_crud_entities.contains("field_id: customer_phone"));
        assert!(!field_crud_entities.contains("field_id: legacy_code"));
        let crm = synthesize_builtin_app_model(
            "crm_app",
            "Create a CRM webapp for leads, client contacts, deal value, and follow-up next steps",
            None,
        )
        .expect("crm synthesis");
        assert_eq!(crm.model.app_family_id, "crm_pipeline");
        assert_eq!(crm.model.entities[0].id, "lead");
        for field in ["company", "contact", "email", "next_step", "amount"] {
            assert!(crm.model.entities[0].fields.contains(&field.to_owned()));
        }
        assert!(
            crm.model
                .capabilities
                .contains(&"contact_management".to_owned())
        );
        assert!(crm.model.navigation.contains(&"Pipeline".to_owned()));
        assert!(crm.model.ui_archetypes.iter().any(|archetype| {
            archetype.archetype_id == "card.record_grid_with_empty_state.v1"
                && archetype.selection_rule == "lead cards with contact and next-step metadata"
        }));
        let crm_patches = builtin_authoring_patches(&crm.model).expect("crm patches");
        assert!(crm_patches.iter().any(|patch| {
            patch.path.ends_with("templates/home.body.html")
                && patch.content.contains("family-crm")
                && patch.content.contains("name=\"next_step\"")
        }));
        assert!(crm_patches.iter().any(|patch| {
            patch.path.ends_with("templates/fragments/item_card.html")
                && patch.content.contains("Company {company}")
                && patch.content.contains("Next Step {next_step}")
        }));
        let invoice = synthesize_builtin_app_model(
            "invoice_tracker",
            "Create an invoice tracker for customer billing with invoice number, amount, due date, and paid status",
            None,
        )
        .expect("invoice synthesis");
        for field in ["invoice_number", "customer", "amount", "due_date"] {
            assert!(
                invoice.model.entities[0].fields.contains(&field.to_owned()),
                "missing invoice field {field}"
            );
        }
        let invoice_patches = builtin_authoring_patches(&invoice.model).expect("invoice patches");
        let invoice_patch = |suffix: &str| {
            invoice_patches
                .iter()
                .find(|patch| patch.path.ends_with(suffix))
                .map(|patch| patch.content.as_str())
                .expect(suffix)
        };
        assert!(invoice_patch("templates/home.body.html").contains("name=\"invoice_number\""));
        assert!(invoice_patch("templates/home.body.html").contains("name=\"due_date\""));
        assert!(
            invoice_patch("templates/fragments/item_card.html")
                .contains("Invoice Number {invoice_number}")
        );
        let contract: pharos_runtime_database::contract::AppDataContract = serde_json::from_value(
            pharos_runtime_compiler::database_yaml::parse(invoice_patch(
                "data/contracts/database.yml",
            ))
            .unwrap(),
        )
        .expect("generated logical database contract");
        assert!(
            contract
                .schema
                .entities
                .iter()
                .any(|entity| entity.fields.iter().any(|field| {
                    field.name == "invoice_number"
                        && field.kind == pharos_runtime_database::operations::FieldType::Text
                        && !field.nullable
                        && field.default
                            == Some(pharos_runtime_database::operations::FieldDefault::Literal(
                                serde_json::json!(""),
                            ))
                }))
        );

        let support = synthesize_builtin_app_model(
            "support_queue",
            "Create a support ticket queue with requester, category, priority, assignee, and customer phone",
            None,
        )
        .expect("support synthesis");
        for field in [
            "requester",
            "priority",
            "category",
            "assignee",
            "customer",
            "phone",
        ] {
            assert!(
                support.model.entities[0].fields.contains(&field.to_owned()),
                "missing support field {field}"
            );
        }
        let support_patches = builtin_authoring_patches(&support.model).expect("support patches");
        let support_home = support_patches
            .iter()
            .find(|patch| patch.path.ends_with("templates/home.body.html"))
            .map(|patch| patch.content.as_str())
            .expect("support home template");
        assert!(support_home.contains("name=\"requester\""));
        assert!(support_home.contains("name=\"assignee\""));

        let ops = synthesize_builtin_app_model(
            "ops_ready_app",
            "Create an authenticated admin app with roles, permissions, webhook integration, email notifications, scheduled reminder jobs, backup restore policy, and production deployment target behavior",
            None,
        )
        .expect("operational synthesis");
        for capability in [
            "authenticated_routes",
            "role_policy_authoring",
            "permission_capabilities",
            "integration_webhook",
            "notification_email",
            "scheduled_jobs",
            "backup_restore_policy",
            "target_deployment_plan",
        ] {
            assert!(
                ops.model.capabilities.contains(&capability.to_owned()),
                "missing capability {capability}"
            );
        }
        assert!(
            ops.model
                .validation_expectations
                .iter()
                .any(|value| { value.contains("least-privilege roles") })
        );
        assert!(
            ops.model
                .validation_expectations
                .iter()
                .any(|value| { value.contains("env secret refs") })
        );
        assert!(
            ops.model
                .validation_expectations
                .iter()
                .any(|value| { value.contains("scheduled jobs") })
        );
        assert!(
            ops.model
                .validation_expectations
                .iter()
                .any(|value| { value.contains("backup restore policy excludes vault secrets") })
        );
        assert!(
            ops.model
                .validation_expectations
                .iter()
                .any(|value| { value.contains("target deployment plan is fail-closed") })
        );
        let ops_patches = builtin_authoring_patches(&ops.model).expect("operational patches");
        let patch = |suffix: &str| {
            ops_patches
                .iter()
                .find(|patch| patch.path.ends_with(suffix))
                .map(|patch| patch.content.as_str())
                .expect(suffix)
        };
        let routes = pharos_runtime_core::yaml::parse_yaml_text(patch("data/contracts/routes.yml"))
            .expect("authenticated route contract");
        let routes = routes["routes"].as_array().expect("executable routes");
        assert!(routes.iter().any(|route| route["action_id"] == "login"));
        assert!(routes.iter().any(|route| route["action_id"] == "logout"));
        assert!(patch("data/contracts/routes.yml").contains("planned_routes:"));
        assert!(patch("data/contracts/routes.yml").contains("kind: page"));
        assert!(patch("data/contracts/routes.yml").contains("request_hooks: [form_body_required]"));
        assert!(patch("data/contracts/actions.yml").contains("effect_policy:"));
        assert!(patch("data/contracts/actions.yml").contains("deny_undeclared: true"));
        assert!(patch("data/contracts/actions.yml").contains("planned_actions:"));
        assert!(patch("data/contracts/surfaces.yml").contains("surface_kind: html_page"));
        assert!(patch("data/contracts/surfaces.yml").contains("surface_kind: form"));
        assert!(
            patch("data/contracts/generated_surfaces.yml")
                .contains("surface_kind: generated_admin")
        );
        assert!(patch("data/contracts/generated_surfaces.yml").contains("review_required: true"));
        assert!(patch("data/contracts/policies.yml").contains("role: owner"));
        assert!(patch("data/contracts/policies.yml").contains("manage_settings"));
        assert!(patch("data/contracts/auth.yml").contains("session_backend: shared_pharos_auth"));
        assert!(patch("data/contracts/auth.yml").contains("mutation_policy: manage_records"));
        assert!(patch("data/features/starter.yml").contains("policy: authenticated"));
        assert!(patch("data/features/starter.yml").contains("policy: manage_records"));
        assert!(
            patch("templates/home.body.html").contains("Generated operational capability review")
        );
        assert!(patch("templates/home.body.html").contains("Auth, roles, and permissions"));
        assert!(patch("templates/home.body.html").contains("Webhook and email adapters"));
        assert!(patch("templates/home.body.html").contains("Local review job plan"));
        assert!(patch("templates/home.body.html").contains("Verified restore policy"));
        assert!(patch("templates/home.body.html").contains("Deployment gate"));
        assert!(patch("README.md").contains("docs/reference/proving-apps-and-validation.md"));
        assert!(
            patch("README.md").contains("Target and deployment behavior remains release-closed")
        );
        assert!(patch("/ACCEPTANCE.md").contains("Acceptance criteria for Ops Ready App"));
        assert!(patch("/ACCEPTANCE.md").contains("auth_policy_exercised"));
        assert!(patch("/ACCEPTANCE.md").contains("deployment_release_closed"));
        assert!(
            patch("BUILD-EVIDENCE.json")
                .contains("\"schema\": \"pharos.generated_app.build_evidence.v1\"")
        );
        assert!(patch("BUILD-EVIDENCE.json").contains("\"acceptance_criteria\""));
        assert!(patch("BUILD-EVIDENCE.json").contains("\"export_cleanliness\""));
        assert!(patch("data/contracts/integrations.yml").contains("adapter_kind: http_json"));
        assert!(
            patch("data/contracts/integrations.yml").contains("adapter_kind: notification_email")
        );
        assert!(
            patch("data/contracts/integrations.yml").contains("PHAROS_OPS_READY_APP_WEBHOOK_TOKEN")
        );
        assert!(!patch("data/contracts/integrations.yml").contains("api_key"));
        assert!(patch("data/contracts/jobs.yml").contains("job_kind: scheduled"));
        assert!(
            patch("data/contracts/backup_restore.yml")
                .contains("excludes: [vault, media_quarantine, secrets]")
        );
        assert!(patch("data/contracts/targets.yml").contains("release_allowed: false"));
        assert!(
            patch("data/contracts/targets.yml")
                .contains("production_requires_local_green_gate: true")
        );
        assert!(patch("MANUAL-ACCEPTANCE.md").contains("Auth, roles, and permissions"));
        assert!(patch("MANUAL-ACCEPTANCE.md").contains("Integrations and email"));
        assert!(patch("MANUAL-ACCEPTANCE.md").contains("Scheduled jobs"));
        assert!(patch("MANUAL-ACCEPTANCE.md").contains("Backup and restore"));
        assert!(patch("MANUAL-ACCEPTANCE.md").contains("Target and deployment behavior"));
        assert!(patch("MANUAL-ACCEPTANCE.md").contains("PHAROS_OPS_READY_APP_WEBHOOK_TOKEN"));
        let composition = synthesize_builtin_app_model(
            "capability_composition_app",
            "Create an authenticated admin dashboard with generated admin CRUD surfaces, a UI library design system, role permissions, webhook API integration, email notifications, scheduled reminder jobs, backup restore policy, and deployment target controls",
            None,
        )
        .expect("capability composition synthesis");
        assert_eq!(composition.model.app_family_id, "dashboard");
        for capability in [
            "authenticated_routes",
            "role_policy_authoring",
            "permission_capabilities",
            "integration_webhook",
            "notification_email",
            "scheduled_jobs",
            "backup_restore_policy",
            "target_deployment_plan",
            "generated_surface_contract",
            "ui_lib_surface",
        ] {
            assert!(
                composition
                    .model
                    .capabilities
                    .contains(&capability.to_owned()),
                "missing composition capability {capability}"
            );
        }
        let composition_patches =
            builtin_authoring_patches(&composition.model).expect("capability composition patches");
        let composition_patch = |suffix: &str| {
            composition_patches
                .iter()
                .find(|patch| patch.path.ends_with(suffix))
                .map(|patch| patch.content.as_str())
                .expect(suffix)
        };
        assert!(
            composition_patch("data/contracts/generated_surfaces.yml")
                .contains("surface_kind: generated_admin")
        );
        assert!(
            composition_patch("data/contracts/auth.yml")
                .contains("default_authenticated_role: viewer")
        );
        assert!(composition_patch("data/features/starter.yml").contains("policy: authenticated"));
        assert!(composition_patch("data/features/starter.yml").contains("policy: manage_records"));
        assert!(composition_patch("data/contracts/surfaces.yml").contains("surface_kind: ui_lib"));
        assert!(
            composition_patch("data/contracts/surfaces.yml")
                .contains("title: \"Capability Composition App UI library\"")
        );
        assert!(synthesis.app_model_digest.len() == 64);
        assert_eq!(
            app_model_digest(&synthesis.model).expect("digest"),
            synthesis.app_model_digest
        );
        let validation = &synthesis.model.validation_expectations;
        assert!(
            validation
                .iter()
                .any(|value| value.contains("authenticated navigation"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("runtime fragment placeholder"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("WCAG-readable"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("seeded local credentials"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("icon buttons"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("modern standards consumed"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("security controls consumed"))
        );
        assert!(synthesis.model.knowledge_sources.iter().any(|source| {
            source == "target/agent/app-model-reference.json#standards_references"
        }));
        assert!(
            validation
                .iter()
                .any(|value| value.contains("red disabled"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("reusable UI patterns applied")
                    && value.contains("htmx_targeted_actions")
                    && value.contains("icon_button_navigation")
                    && value.contains("card_grid_records"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("typed UI archetypes selected")
                    && value.contains("form.compact_labeled_control_row.v1"))
        );
        assert!(
            validation
                .iter()
                .any(|value| value.contains("reference docs consumed")
                    && value.contains("library-reference.md")
                    && value.contains("runtime-map.json#rustdoc"))
        );
        let mut dashboard_model = synthesize_builtin_app_model(
            "dashboard_crud",
            "Create a KPI dashboard app with metrics, category, metric type, target value, trend, and scheduled date",
            None,
        )
        .expect("dashboard crud synthesis")
        .model;
        let dashboard_entity_id = dashboard_model.entities[0].id.clone();
        dashboard_model.actions.push(AppActionModel {
            id: format!("update_{dashboard_entity_id}"),
            route_id: "home".to_owned(),
            intent: format!("update_{dashboard_entity_id}_record"),
        });
        dashboard_model.actions.push(AppActionModel {
            id: format!("delete_{dashboard_entity_id}"),
            route_id: "home".to_owned(),
            intent: format!("delete_{dashboard_entity_id}_record"),
        });
        let dashboard_patches =
            builtin_authoring_patches(&dashboard_model).expect("dashboard crud patches");
        let dashboard_feature = dashboard_patches
            .iter()
            .find(|patch| patch.path.ends_with("data/features/starter.yml"))
            .map(|patch| patch.content.as_str())
            .expect("dashboard feature contract");
        pharos_runtime_core::yaml::validate_unique_mapping_keys(dashboard_feature)
            .expect("generated CRUD feature YAML must not contain duplicate keys");
        assert!(dashboard_feature.contains(&format!("  update_{dashboard_entity_id}:")));
        assert!(dashboard_feature.contains(&format!("  delete_{dashboard_entity_id}:")));
        assert_eq!(
            dashboard_feature
                .matches("          title: input.title")
                .count(),
            2
        );
        assert_eq!(
            dashboard_feature
                .matches("          note: input.note")
                .count(),
            2
        );

        let starter_patches =
            builtin_authoring_patches(&synthesis.model).expect("starter authoring patches");
        let starter_patch = |suffix: &str| {
            starter_patches
                .iter()
                .find(|patch| patch.path.ends_with(suffix))
                .map(|patch| patch.content.as_str())
                .expect(suffix)
        };
        assert!(starter_patch("/ACCEPTANCE.md").contains("task_persists_after_refresh"));
        assert!(starter_patch("BUILD-EVIDENCE.json").contains("\"app_id\": \"starter_builder\""));
        assert_eq!(
            synthesize_builtin_app_model("bad/app", "Create a todo webapp", None).err(),
            Some(AgentErrorKind::InvalidIdentifier)
        );
        assert_eq!(
            synthesize_builtin_app_model("starter", "api_key=secret", None).err(),
            Some(AgentErrorKind::SecretRedacted)
        );
    }

    #[test]
    /// Proves product knowledge generation emits every required local reference without leaking host paths.
    fn product_knowledge_outputs_are_deterministic_and_portable() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let outputs = product_knowledge_outputs(&repo).expect("product knowledge");
        let names = outputs.iter().map(|(name, _)| *name).collect::<Vec<_>>();
        assert_eq!(
            names,
            vec![
                "pharos-agent-index.json",
                "app-model-reference.json",
                "archetype-inventory.json",
                "ui-catalog.json",
                "runtime-map.json",
                "cli-reference.json",
                "capability-ledger.json"
            ]
        );
        let serialized = serde_json::to_string(&outputs).expect("json");
        assert!(!serialized.contains(repo.to_string_lossy().as_ref()));
        assert!(!serialized.contains("/Users/"));
        assert!(!serialized.contains("sk-"));
        assert!(!serialized.contains("api_key="));
        assert!(!serialized.contains("token="));
        assert!(!serialized.contains("app.conf\""));

        let app_model = outputs
            .iter()
            .find(|(name, _)| *name == "app-model-reference.json")
            .map(|(_, value)| value)
            .expect("app model");
        assert_eq!(
            app_model
                .pointer("/operating_primer/contract_first_mandate")
                .and_then(Value::as_str)
                .map(|value| value.contains("Start every generated webapp from the app model")),
            Some(true)
        );
        let learned_rules = app_model
            .get("learned_generation_rules")
            .and_then(Value::as_object)
            .expect("learned rules");
        for (key, expected) in [
            ("auth_navigation", "Anonymous users must not see"),
            ("template_fragments", "Do not leave unresolved placeholders"),
            ("color_contrast", "readable text/background contrast"),
            ("local_credentials", "Seeded development credentials"),
            ("bootstrap_icons", "vendor Bootstrap Icons locally"),
            ("icon_navigation", "standard button size"),
            (
                "settings_switches",
                "inactive labels in readable black text",
            ),
            ("yaml_authoring", "YAML 1.2.2-compatible"),
            ("json_authoring", "RFC 8259 and ECMA-404"),
            ("html_authoring", "WHATWG Living Standard"),
            ("css_authoring", "W3C CSS snapshot"),
            ("htmx_authoring", "CSRF coverage"),
            ("sql_authoring", "ISO/IEC 9075:2023"),
            ("rust_authoring", "Rust Reference"),
            ("toml_authoring", "TOML v1.0.0"),
            ("markdown_authoring", "CommonMark-compatible"),
            ("svg_authoring", "SVG 2"),
            ("security_compliance", "SOC 2 and ISO/IEC 27001"),
        ] {
            assert_eq!(
                learned_rules
                    .get(key)
                    .and_then(Value::as_str)
                    .map(|value| value.contains(expected)),
                Some(true),
                "{key} should include {expected}"
            );
        }
        let standards_references = app_model
            .get("standards_references")
            .and_then(Value::as_array)
            .expect("standards references");
        for reference_id in [
            "yaml-1.2.2",
            "html-living-standard",
            "css-snapshot-2025",
            "htmx-security-basics-2024",
            "json-rfc-8259",
            "json-ecma-404",
            "sql-iso-iec-9075-2023",
            "rust-reference",
            "toml-1.0.0",
            "commonmark-0.31.2",
            "svg-2",
            "soc2-trust-services-criteria-2022",
            "iso-iec-27001-2022",
        ] {
            assert!(
                standards_references.iter().any(|reference| reference
                    .get("reference_id")
                    .and_then(Value::as_str)
                    == Some(reference_id)),
                "missing standards reference {reference_id}"
            );
        }
        assert!(standards_references.iter().any(|reference| {
            reference.get("source_url").and_then(Value::as_str)
                == Some("https://www.w3.org/TR/css-2025/")
                && reference
                    .get("builder_guidance")
                    .and_then(Value::as_str)
                    .is_some_and(|guidance| guidance.contains("modular app-owned CSS"))
        }));
        assert!(standards_references.iter().any(|reference| {
            reference.get("reference_id").and_then(Value::as_str)
                == Some("soc2-trust-services-criteria-2022")
                && reference
                    .get("generation_controls")
                    .and_then(Value::as_array)
                    .is_some_and(|controls| {
                        controls.iter().any(|control| {
                            control
                                .as_str()
                                .is_some_and(|text| text.contains("hardcoded secrets"))
                        })
                    })
        }));

        let runtime_map = outputs
            .iter()
            .find(|(name, _)| *name == "runtime-map.json")
            .map(|(_, value)| value)
            .expect("runtime map");
        assert_eq!(
            runtime_map
                .pointer("/builder_flow/template_owner")
                .and_then(Value::as_str)
                .map(|value| value.contains("templates/ owns page structure")),
            Some(true)
        );
        assert!(
            runtime_map
                .get("implemented_cli_surfaces")
                .and_then(Value::as_array)
                .expect("cli surfaces")
                .iter()
                .any(|value| value.get("verb").and_then(Value::as_str) == Some("build"))
        );
        assert_eq!(
            runtime_map
                .pointer("/execution_boundaries/wasi")
                .and_then(Value::as_str)
                .map(|value| value.contains("must not receive host filesystem")),
            Some(true)
        );
        assert!(
            runtime_map
                .get("operations_surfaces")
                .and_then(Value::as_array)
                .expect("ops surfaces")
                .iter()
                .any(|value| value.as_str() == Some("provenance"))
        );
        assert_eq!(
            runtime_map
                .pointer("/rustdoc_knowledge/usage")
                .and_then(Value::as_str)
                .map(|value| value.contains("runtime handlers")),
            Some(true)
        );
        let rustdoc_areas = runtime_map
            .pointer("/rustdoc_knowledge/knowledge_areas")
            .and_then(Value::as_array)
            .expect("rustdoc areas");
        for area_id in [
            "route_runtime",
            "action_runtime",
            "rendering_runtime",
            "storage_runtime",
        ] {
            assert!(
                rustdoc_areas.iter().any(|area| {
                    area.get("area_id").and_then(Value::as_str) == Some(area_id)
                        && area.get("status").and_then(Value::as_str) == Some("represented")
                        && area
                            .get("module_paths")
                            .and_then(Value::as_array)
                            .is_some_and(|paths| !paths.is_empty())
                }),
                "missing Rustdoc knowledge area {area_id}"
            );
        }
        assert!(
            app_model
                .pointer("/yaml_schema_catalog/contracts")
                .and_then(Value::as_array)
                .expect("contract schema")
                .iter()
                .any(|value| value.as_str() == Some("route_contract"))
        );
        assert!(
            app_model
                .get("required_outputs")
                .and_then(Value::as_array)
                .expect("required outputs")
                .iter()
                .any(|value| value.as_str() == Some("workflows"))
        );
        assert_eq!(
            app_model
                .pointer("/lifecycle_command_status/build_app")
                .and_then(Value::as_str),
            Some("implemented_generic_runtime_dispatch")
        );
        assert_eq!(
            app_model
                .pointer("/lifecycle_command_status/seed_app")
                .and_then(Value::as_str),
            Some("implemented_compatibility_alias")
        );
        assert!(
            app_model
                .pointer("/yaml_schema_catalog/assets")
                .and_then(Value::as_array)
                .expect("asset schema")
                .iter()
                .any(|value| value.as_str() == Some("runtime_media_dir"))
        );
        assert!(
            app_model
                .get("docs_as_contract")
                .and_then(Value::as_array)
                .expect("docs")
                .iter()
                .any(|value| value.get("path").and_then(Value::as_str)
                    == Some("docs/contracts/yaml-authoring.md"))
        );
        assert!(
            app_model
                .get("docs_as_contract")
                .and_then(Value::as_array)
                .expect("docs")
                .iter()
                .any(|value| value.get("path").and_then(Value::as_str)
                    == Some("docs/reference/library-reference.md"))
        );
        assert!(
            app_model
                .pointer("/operating_primer/knowledge_consumption_points")
                .and_then(Value::as_array)
                .expect("knowledge consumption")
                .iter()
                .any(|value| value.as_str() == Some("target/agent/runtime-map.json#rustdoc"))
        );
        let ui_catalog = outputs
            .iter()
            .find(|(name, _)| *name == "ui-catalog.json")
            .map(|(_, value)| value)
            .expect("ui catalog");
        assert!(
            ui_catalog
                .get("frontend_patterns")
                .and_then(Value::as_array)
                .expect("patterns")
                .iter()
                .any(|value| value.as_str() == Some("no_authored_html_in_rust"))
        );
        assert!(
            ui_catalog
                .get("source_app_count")
                .and_then(Value::as_u64)
                .is_some_and(|count| count >= 8)
        );
        assert!(
            ui_catalog
                .get("components")
                .and_then(Value::as_array)
                .expect("components")
                .iter()
                .any(|component| component.get("kind").and_then(Value::as_str) == Some("fragment"))
        );
        let typed_archetypes = ui_catalog
            .get("typed_archetypes")
            .and_then(Value::as_array)
            .expect("typed archetypes");
        for archetype_id in [
            "action.button_bar_semantic_colors.v1",
            "card.metric_stat_grid.v1",
            "card.product_media_purchase.v1",
            "card.record_grid_with_empty_state.v1",
            "console.task_status_timeline.v1",
            "empty_state.actionable_placeholder.v1",
            "form.compact_labeled_control_row.v1",
            "form.context_file_voice_input.v1",
            "form.editable_select_option_manager.v1",
            "hero.summary_action_panel.v1",
            "nav.icon_buttons_with_hover_labels.v1",
            "page.calendar_matrix.v1",
            "page.checkout_side_panel.v1",
            "page.documentation_shell.v1",
            "page.hero_grid_index.v1",
            "page.master_detail_workspace.v1",
            "page.settings_console.v1",
            "panel.tabbed_spa_content.v1",
            "settings.boolean_switch_fragment.v1",
            "shell.compact_app_frame.v1",
            "table.dense_admin_or_reference.v1",
        ] {
            assert!(
                typed_archetypes.iter().any(|archetype| {
                    archetype.get("archetype_id").and_then(Value::as_str) == Some(archetype_id)
                        && archetype
                            .get("structure")
                            .and_then(Value::as_array)
                            .is_some_and(|items| !items.is_empty())
                        && archetype
                            .get("css_tokens")
                            .and_then(Value::as_array)
                            .is_some_and(|items| !items.is_empty())
                        && archetype
                            .get("preferred_source_examples")
                            .and_then(Value::as_array)
                            .is_some_and(|items| !items.is_empty())
                        && archetype
                            .get("anti_patterns")
                            .and_then(Value::as_array)
                            .is_some_and(|items| !items.is_empty())
                        && archetype
                            .get("family_selection_rules")
                            .and_then(Value::as_object)
                            .is_some()
                }),
                "missing typed UI archetype {archetype_id}"
            );
        }
        assert!(typed_archetypes.iter().any(|archetype| {
            archetype.get("archetype_id").and_then(Value::as_str)
                == Some("form.compact_labeled_control_row.v1")
                && archetype
                    .get("anti_patterns")
                    .and_then(Value::as_array)
                    .is_some_and(|items| {
                        items.iter().any(|item| {
                            item.as_str()
                                .is_some_and(|text| text.contains("label-to-control gaps"))
                        })
                    })
        }));
        assert!(typed_archetypes.iter().any(|archetype| {
            archetype.get("archetype_id").and_then(Value::as_str)
                == Some("card.product_media_purchase.v1")
                && archetype
                    .pointer("/family_selection_rules/commerce_catalog")
                    .and_then(Value::as_str)
                    == Some("preferred")
        }));

        let reusable_patterns = ui_catalog
            .get("reusable_patterns")
            .and_then(Value::as_array)
            .expect("reusable patterns");
        for pattern_id in [
            "app_shell_layout",
            "htmx_targeted_actions",
            "icon_button_navigation",
            "button_rows",
            "card_grid_records",
            "compact_settings_forms",
            "editable_select_option_managers",
            "page_calendar_matrix",
            "page_checkout_side_panel",
            "page_documentation_shell",
            "page_hero_grid_index",
            "page_master_detail_workspace",
            "page_settings_console",
            "setting_switches",
        ] {
            assert!(
                reusable_patterns.iter().any(|pattern| {
                    pattern.get("pattern_id").and_then(Value::as_str) == Some(pattern_id)
                        && pattern
                            .get("source_examples")
                            .and_then(Value::as_array)
                            .is_some_and(|examples| !examples.is_empty())
                }),
                "missing reusable UI pattern {pattern_id}"
            );
        }
        let patterns_by_id = reusable_patterns
            .iter()
            .filter_map(|pattern| Some((pattern.get("pattern_id")?.as_str()?, pattern)))
            .collect::<BTreeMap<_, _>>();
        assert!(
            patterns_by_id["setting_switches"]
                .get("source_examples")
                .and_then(Value::as_array)
                .expect("switch examples")
                .iter()
                .any(|value| value
                    .as_str()
                    .is_some_and(|path| path.starts_with("apps/ucal")))
        );
        assert!(
            patterns_by_id["icon_button_navigation"]
                .get("source_examples")
                .and_then(Value::as_array)
                .expect("icon examples")
                .iter()
                .any(|value| value
                    .as_str()
                    .is_some_and(|path| path.starts_with("apps/dev_docs")))
        );
        assert!(
            patterns_by_id["card_grid_records"]
                .get("source_examples")
                .and_then(Value::as_array)
                .expect("card examples")
                .iter()
                .any(|value| value
                    .as_str()
                    .is_some_and(|path| path.starts_with("apps/commerce_spa")))
        );
        assert!(
            patterns_by_id["compact_settings_forms"]
                .get("source_examples")
                .and_then(Value::as_array)
                .expect("settings examples")
                .iter()
                .any(|value| value
                    .as_str()
                    .is_some_and(|path| path.starts_with("apps/architect")))
        );

        let archetypes = outputs
            .iter()
            .find(|(name, _)| *name == "archetype-inventory.json")
            .map(|(_, value)| value)
            .expect("archetypes");
        let ucal = archetypes
            .get("apps")
            .and_then(Value::as_array)
            .expect("apps")
            .iter()
            .find(|app| app.get("app_id").and_then(Value::as_str) == Some("ucal"))
            .expect("ucal");
        assert_eq!(ucal.get("base_path").and_then(Value::as_str), Some("/ucal"));
        assert!(
            ucal.get("contract_families")
                .and_then(Value::as_array)
                .expect("contract families")
                .iter()
                .any(|value| value.as_str() == Some("form_contract"))
        );

        let check_report =
            validate_product_knowledge_documents(&repo, &outputs).expect("check report");
        assert_eq!(
            check_report.get("status").and_then(Value::as_str),
            Some("verified")
        );
        assert_eq!(
            check_report
                .pointer("/maturity/schema")
                .and_then(Value::as_str),
            Some("pharos.agent.product_knowledge_maturity.v1")
        );
        assert_eq!(
            check_report
                .pointer("/maturity/status")
                .and_then(Value::as_str),
            Some("production_ready_local_knowledge_intake")
        );
        assert_eq!(
            check_report
                .pointer("/maturity/maturity_level")
                .and_then(Value::as_str),
            Some("deterministic_local_generation_prerequisite")
        );
        assert!(
            check_report
                .pointer("/maturity/source_app_count")
                .and_then(Value::as_u64)
                .is_some_and(|count| count >= 8)
        );
        assert!(
            check_report
                .pointer("/maturity/typed_archetype_count")
                .and_then(Value::as_u64)
                .is_some_and(|count| count >= 14)
        );
        assert!(
            check_report
                .pointer("/maturity/rustdoc_line_count")
                .and_then(Value::as_u64)
                .is_some_and(|count| count > 0)
        );
        assert!(
            check_report
                .pointer("/maturity/checks")
                .and_then(Value::as_array)
                .expect("maturity checks")
                .iter()
                .all(|check| check.get("status").and_then(Value::as_str) == Some("passed"))
        );

        let ledger = outputs
            .iter()
            .find(|(name, _)| *name == "capability-ledger.json")
            .map(|(_, value)| value)
            .expect("capability ledger");
        assert_eq!(
            ledger.get("unresolved_count").and_then(Value::as_u64),
            Some(0)
        );
        assert!(
            ledger
                .get("records")
                .and_then(Value::as_array)
                .expect("ledger records")
                .iter()
                .any(
                    |record| record.get("classification").and_then(Value::as_str)
                        == Some("ui_interface")
                )
        );

        let index = outputs
            .iter()
            .find(|(name, _)| *name == "pharos-agent-index.json")
            .map(|(_, value)| value)
            .expect("index");
        assert_eq!(
            index.get("schema").and_then(Value::as_str),
            Some("pharos.agent.index.v1")
        );
        assert!(
            index
                .get("apps")
                .and_then(Value::as_array)
                .expect("apps")
                .iter()
                .any(|app| app.get("app_id").and_then(Value::as_str) == Some("ucal"))
        );
    }

    #[test]
    /// Proves broken product-knowledge inputs produce diagnostic maturity failures.
    fn product_knowledge_maturity_reports_broken_inputs() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let outputs = product_knowledge_outputs(&repo).expect("product knowledge");

        let missing_library =
            mutated_product_outputs(&outputs, "app-model-reference.json", |value| {
                value
                    .get_mut("docs_as_contract")
                    .and_then(Value::as_array_mut)
                    .expect("docs")
                    .retain(|entry| {
                        entry.get("path").and_then(Value::as_str)
                            != Some("docs/reference/library-reference.md")
                    });
            });
        assert_maturity_failure(&repo, &missing_library, "library_reference_consumed");

        let missing_ui_guide =
            mutated_product_outputs(&outputs, "app-model-reference.json", |value| {
                value
                    .get_mut("docs_as_contract")
                    .and_then(Value::as_array_mut)
                    .expect("docs")
                    .retain(|entry| {
                        entry.get("path").and_then(Value::as_str)
                            != Some("docs/reference/ui-styling-guide.md")
                    });
            });
        assert_maturity_failure(&repo, &missing_ui_guide, "ui_styling_guide_consumed");

        let zero_rustdoc = mutated_product_outputs(&outputs, "runtime-map.json", |value| {
            for module in value
                .get_mut("modules")
                .and_then(Value::as_array_mut)
                .expect("modules")
            {
                module["rustdoc_line_count"] = serde_json::json!(0);
            }
            for area in value
                .pointer_mut("/rustdoc_knowledge/knowledge_areas")
                .and_then(Value::as_array_mut)
                .expect("areas")
            {
                area["status"] = serde_json::json!("missing");
                area["module_paths"] = serde_json::json!([]);
            }
        });
        assert_maturity_failure(&repo, &zero_rustdoc, "rustdoc_runtime_map_consumed");
        assert_maturity_failure(&repo, &zero_rustdoc, "rustdoc_runtime_areas_consumed");

        let malformed_archetype = mutated_product_outputs(&outputs, "ui-catalog.json", |value| {
            let first = value
                .get_mut("typed_archetypes")
                .and_then(Value::as_array_mut)
                .and_then(|items| items.first_mut())
                .expect("first archetype");
            first["structure"] = serde_json::json!([]);
        });
        assert_maturity_failure(&repo, &malformed_archetype, "typed_ui_archetypes_consumed");

        let unresolved_ledger =
            mutated_product_outputs(&outputs, "capability-ledger.json", |value| {
                value["unresolved_count"] = serde_json::json!(1);
            });
        assert_maturity_failure(&repo, &unresolved_ledger, "capability_ledger_resolved");

        let missing_standards =
            mutated_product_outputs(&outputs, "app-model-reference.json", |value| {
                value
                    .get_mut("standards_references")
                    .and_then(Value::as_array_mut)
                    .expect("standards")
                    .retain(|entry| {
                        entry.get("reference_id").and_then(Value::as_str)
                            != Some("iso-iec-27001-2022")
                    });
            });
        assert_maturity_failure(
            &repo,
            &missing_standards,
            "web_standards_references_consumed",
        );
        assert_maturity_failure(
            &repo,
            &missing_standards,
            "security_compliance_references_consumed",
        );

        let malformed_standards =
            mutated_product_outputs(&outputs, "app-model-reference.json", |value| {
                let first = value
                    .get_mut("standards_references")
                    .and_then(Value::as_array_mut)
                    .and_then(|items| items.first_mut())
                    .expect("first standard");
                first["source_url"] = serde_json::json!("http://example.invalid/not-authoritative");
            });
        assert_maturity_failure(
            &repo,
            &malformed_standards,
            "web_standards_references_consumed",
        );

        let missing_ui_archetypes =
            mutated_product_outputs(&outputs, "app-model-reference.json", |value| {
                value
                    .get_mut("required_outputs")
                    .and_then(Value::as_array_mut)
                    .expect("required outputs")
                    .retain(|entry| entry.as_str() != Some("ui_archetypes"));
            });
        assert_maturity_failure(
            &repo,
            &missing_ui_archetypes,
            "app_model_requires_ui_archetypes",
        );
    }

    #[test]
    /// Proves source app template/CSS edits change the product-knowledge fingerprint and stale artifacts fail.
    fn product_knowledge_detects_source_drift_and_stale_artifacts() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let source_files = knowledge_source_files(&repo);
        let current =
            pharos_runtime_architect::product_knowledge::source_fingerprint(&repo, &source_files)
                .expect("current fingerprint");
        let mut overrides = BTreeMap::new();
        overrides.insert(
            "apps/architect/templates/settings.body.html".to_owned(),
            b"<section>changed architect settings layout</section>".to_vec(),
        );
        let changed_template = source_fingerprint_with_overrides(&repo, &source_files, &overrides)
            .expect("template drift");
        assert_ne!(current, changed_template);
        overrides.clear();
        overrides.insert(
            "apps/architect/static/css/modules/architect/03-app.css".to_owned(),
            b".knowledge-readiness-card{border-color:#147a3d}".to_vec(),
        );
        let changed_css =
            source_fingerprint_with_overrides(&repo, &source_files, &overrides).expect("css drift");
        assert_ne!(current, changed_css);

        let output_dir = Path::new("target/agent-test-stale-knowledge");
        let _ = fs::remove_dir_all(repo.join(output_dir));
        write_product_knowledge(&repo, output_dir).expect("write knowledge");
        let catalog_path = repo.join(output_dir).join("ui-catalog.json");
        let mut catalog = read_json_file(&catalog_path).expect("catalog");
        catalog["source_fingerprint"] = serde_json::json!("stale-fingerprint");
        write_json_output(&catalog_path, &catalog).expect("stale catalog write");
        assert_eq!(check_written_product_knowledge(&repo, output_dir), Err(65));
        let _ = fs::remove_dir_all(repo.join(output_dir));
    }

    #[test]
    /// Proves sync enumerates real workflow files and emits typed requested-feature gaps.
    fn agent_sync_report_scans_workflows_and_records_requested_feature_gaps() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let report = agent_sync_report(
            &repo,
            Path::new("target/agent-test-sync"),
            true,
            &[
                "src/runtime/agent_bridge.rs".to_owned(),
                ".github/workflows/release.yml".to_owned(),
                "apps/ucal/pharos.app.yml".to_owned(),
                "apps/architect/pharos.app.yml".to_owned(),
                "containers/Dockerfile.runtime".to_owned(),
                "docs/reference/library-reference.md".to_owned(),
                "docs/reference/ui-styling-guide.md".to_owned(),
                "data/framework/agent/builtin-app/templates/home.body.html".to_owned(),
            ],
            &[
                "deploy app to configured target".to_owned(),
                "build app through existing lifecycle".to_owned(),
            ],
        )
        .expect("sync report");
        let value: Value = serde_json::from_str(&report).expect("sync json");
        assert_eq!(
            value
                .pointer("/workflow_scan/schema")
                .and_then(Value::as_str),
            Some("pharos.agent.workflow_scan.v1")
        );
        assert!(
            value
                .pointer("/workflow_scan/files")
                .and_then(Value::as_array)
                .expect("workflow files")
                .iter()
                .any(|file| file.get("path").and_then(Value::as_str)
                    == Some(".github/workflows/release.yml"))
        );
        assert_eq!(
            value
                .pointer("/workflow_scan/automatic_hosted_triggers_enabled")
                .and_then(Value::as_bool),
            Some(false)
        );
        assert!(
            value
                .pointer("/workflow_scan/commented_disabled_triggers")
                .and_then(Value::as_array)
                .expect("commented triggers")
                .iter()
                .any(|trigger| trigger.as_str() == Some("push"))
        );
        assert!(
            value
                .pointer("/workflow_scan/future_release_targets")
                .and_then(Value::as_array)
                .expect("future targets")
                .iter()
                .any(|target| target.as_str() == Some("wasm32-wasi"))
        );
        let affected_capabilities = value
            .get("affected_capabilities")
            .and_then(Value::as_array)
            .expect("affected capabilities");
        assert!(affected_capabilities.iter().any(|entry| {
            entry.get("path").and_then(Value::as_str) == Some("containers/Dockerfile.runtime")
                && entry.get("classification").and_then(Value::as_str)
                    == Some("deployment_persistence")
                && entry
                    .get("required_proof")
                    .and_then(Value::as_str)
                    .is_some_and(|proof| proof.contains("artifact identity"))
        }));
        assert!(affected_capabilities.iter().any(|entry| {
            entry.get("path").and_then(Value::as_str) == Some("apps/architect/pharos.app.yml")
                && entry.get("classification").and_then(Value::as_str)
                    == Some("deployment_persistence")
                && entry
                    .get("required_proof")
                    .and_then(Value::as_str)
                    .is_some_and(|proof| proof.contains("runtime media"))
        }));
        assert!(affected_capabilities.iter().any(|entry| {
            entry.get("path").and_then(Value::as_str) == Some("docs/reference/library-reference.md")
                && entry.get("classification").and_then(Value::as_str)
                    == Some("product_knowledge_reference")
                && entry
                    .pointer("/knowledge_intake/input_class")
                    .and_then(Value::as_str)
                    == Some("declarative_surface_reference")
                && entry
                    .pointer("/knowledge_intake/builder_impact")
                    .and_then(Value::as_str)
                    .is_some_and(|impact| impact.contains("Pharos logic"))
        }));
        assert!(affected_capabilities.iter().any(|entry| {
            entry.get("path").and_then(Value::as_str) == Some("docs/reference/ui-styling-guide.md")
                && entry
                    .pointer("/knowledge_intake/input_class")
                    .and_then(Value::as_str)
                    == Some("ui_styling_reference")
                && entry
                    .pointer("/knowledge_intake/affected_outputs")
                    .and_then(Value::as_array)
                    .expect("affected outputs")
                    .iter()
                    .any(|output| output.as_str() == Some("ui-catalog.json"))
        }));
        assert!(affected_capabilities.iter().any(|entry| {
            entry.get("path").and_then(Value::as_str)
                == Some("data/framework/agent/builtin-app/templates/home.body.html")
                && entry.get("classification").and_then(Value::as_str)
                    == Some("builder_generation_template")
                && entry
                    .pointer("/knowledge_intake/input_class")
                    .and_then(Value::as_str)
                    == Some("builtin_generation_template")
        }));
        assert!(
            affected_capabilities
                .iter()
                .find(|entry| {
                    entry.get("path").and_then(Value::as_str) == Some("src/runtime/agent_bridge.rs")
                })
                .and_then(|entry| entry.pointer("/knowledge_intake/input_class"))
                .and_then(Value::as_str)
                == Some("rustdoc_runtime_source")
        );
        assert_eq!(
            value
                .pointer("/knowledge_intake_loop/schema")
                .and_then(Value::as_str),
            Some("pharos.agent.knowledge_intake_loop.v1")
        );
        assert!(
            value
                .pointer("/knowledge_intake_loop/changed_input_count")
                .and_then(Value::as_u64)
                .is_some_and(|count| count >= 4)
        );
        assert!(
            value
                .pointer("/knowledge_intake_loop/required_synthesis_proof")
                .and_then(Value::as_str)
                .is_some_and(|proof| proof.contains("scripts/check.sh agent surface"))
        );
        let gaps = value
            .get("gap_records")
            .and_then(Value::as_array)
            .expect("gap records");
        assert_eq!(gaps.len(), 1);
        assert_eq!(
            gaps[0].get("schema").and_then(Value::as_str),
            Some("pharos.agent.requested_feature_gap.v1")
        );
        assert_eq!(
            gaps[0].get("nearest_owner").and_then(Value::as_str),
            Some("src/runtime/ops_bridge.rs")
        );
        assert_eq!(
            value.get("unresolved_count").and_then(Value::as_u64),
            Some(1)
        );
        assert_eq!(
            value
                .pointer("/explanatory_prose/schema")
                .and_then(Value::as_str),
            Some("pharos.agent.sync_explanatory_prose.v1")
        );
        assert!(
            value
                .pointer("/explanatory_prose/entries")
                .and_then(Value::as_array)
                .expect("prose entries")
                .iter()
                .any(|entry| entry.get("kind").and_then(Value::as_str)
                    == Some("requested_feature_gap"))
        );
    }

    #[test]
    /// Proves the product knowledge writer stays inside the repository and writes all required outputs.
    fn product_knowledge_writer_stays_repo_local() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let output_dir = Path::new("target/agent-test-product-knowledge");
        let report = write_product_knowledge(&repo, output_dir).expect("write knowledge");
        let report_value: Value = serde_json::from_str(&report).expect("report json");
        let outputs = report_value
            .get("outputs")
            .and_then(Value::as_array)
            .expect("outputs");
        assert_eq!(outputs.len(), 7);
        for output in outputs {
            let path = output.get("path").and_then(Value::as_str).expect("path");
            assert!(path.starts_with("target/agent-test-product-knowledge/"));
            assert!(repo.join(path).is_file());
        }
        let outside = std::env::temp_dir().join(format!(
            "pharos-agent-product-outside-{}",
            std::process::id()
        ));
        assert_eq!(write_product_knowledge(&repo, &outside), Err(64));
    }

    #[test]
    /// Proves baseline inventory reflects the current app roots and target registry.
    fn baseline_inventory_reflects_current_repo_surfaces() {
        let _bridge_test_guard = bridge_test_lock();
        let inventory = baseline_inventory_value(&repo_root()).expect("inventory");
        let apps = inventory
            .get("app_roots")
            .and_then(Value::as_array)
            .expect("apps");
        assert!(
            apps.iter()
                .any(|app| app.get("app_id").and_then(Value::as_str) == Some("ucal"))
        );
        assert!(
            apps.iter()
                .any(|app| app.get("app_id").and_then(Value::as_str) == Some("todo_list"))
        );

        let registry = inventory.get("target_registry").expect("registry");
        assert_eq!(
            registry
                .get("declared_target_count")
                .and_then(Value::as_u64),
            registry.get("actual_target_count").and_then(Value::as_u64)
        );
        let registry_file = read_target_registry(&repo_root()).expect("registry file");
        let registry_targets = registry_targets(&registry_file).expect("registry targets");
        assert_eq!(
            registry.get("actual_target_count").and_then(Value::as_u64),
            Some(registry_targets.len() as u64)
        );
    }

    #[cfg(all(feature = "sqlite", not(target_os = "wasi")))]
    #[test]
    /// Proves JSON-RPC backup and restore use logical records, not physical files.
    fn json_rpc_executes_backup_and_restore_native_surfaces() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-backup-restore");
        let app_root = root.join("apps/ops_app");
        fs::create_dir_all(app_root.join("data/contracts")).expect("contracts");
        fs::create_dir_all(root.join("tmp")).expect("data root");
        fs::write(
            app_root.join("pharos.app.yml"),
            "app_id: ops_app\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        )
        .expect("manifest");
        fs::write(
            app_root.join("app.conf"),
            format!(
                "db_backend=sqlite\ndb_path={}\nbackup_dir={}\n",
                root.join("tmp/ops.sqlite3").display(),
                root.join("tmp/backups").display()
            ),
        )
        .expect("app config");
        use pharos_runtime_database::operations::{
            Migration, Mutation, Predicate, Query, SchemaChange, Transaction, WriteValue,
        };
        let schema: pharos_runtime_database::operations::AppSchema =
            serde_json::from_value(serde_json::json!({"app_id":"ops_app", "entities":[{
                "name":"record", "identity":{"auto_integer":"id"}, "fields":[
                    {"name":"id","kind":"integer","nullable":false,"constraints":[]},
                    {"name":"title","kind":"text","nullable":false,"constraints":[]}
                ], "unique":[], "indexes":[], "conditional_indexes":[]
            }]}))
            .expect("logical schema");
        let changes: Vec<SchemaChange> = vec![
            SchemaChange::CreateEntity(schema.entities[0].clone()),
            SchemaChange::Seed {
                entity: "record".to_owned(),
                values: serde_json::json!({"id":1,"title":"original"})
                    .as_object()
                    .expect("record")
                    .clone(),
            },
        ];
        let contract = pharos_runtime_database::contract::AppDataContract {
            schema,
            migrations: vec![Migration {
                app_id: "ops_app".to_owned(),
                id: "records".to_owned(),
                checksum: pharos_runtime_database::contract::migration_checksum(
                    "ops_app", "records", &changes,
                )
                .expect("checksum"),
                changes,
            }],
            legacy_adoption: None,
        };
        fs::write(
            app_root.join("data/contracts/database.json"),
            serde_json::to_vec(&contract).expect("contract JSON"),
        )
        .expect("contract");
        let store = super::super::database::logical_app_store(&app_root, None, "ops_app")
            .expect("configured operation store");
        store
            .adapter
            .apply_contract(&store.config, &contract)
            .expect("logical seed");
        // This unrelated file proves backup no longer treats JSON as relational authority.
        fs::write(root.join("tmp/state.json"), r#"{"items":[]}"#).expect("unrelated file");
        let original_dir = std::env::current_dir().expect("cwd");
        std::env::set_current_dir(&root).expect("chdir");
        let backup = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"backup","method":"pharos.backup_app","params":{"app_id":"ops_app","app_dir":"apps/ops_app","output_dir":"tmp/backups"}}"#,
        );
        let backup_value: Value = serde_json::from_str(&backup).expect("backup JSON");
        let input_dir = backup_value
            .pointer("/result/data/backup_dir")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned);
        store
            .adapter
            .transact(
                &store.config,
                &store.schema,
                &Transaction {
                    steps: vec![Mutation::Update {
                        entity: "record".to_owned(),
                        filter: Predicate::Equal("id".to_owned(), Value::from(1)),
                        values: std::collections::BTreeMap::from([(
                            "title".to_owned(),
                            WriteValue::Literal(Value::String("changed".to_owned())),
                        )]),
                        expected_rows: Some(1),
                    }],
                    idempotency_key: None,
                },
            )
            .expect("logical mutation");
        let restore = input_dir.as_ref().map(|input_dir| execute_json_rpc(&serde_json::json!({"jsonrpc":"2.0","id":"restore","method":"pharos.restore_app","params":{"app_id":"ops_app","app_dir":"apps/ops_app","input_dir":input_dir}}).to_string()));
        std::env::set_current_dir(original_dir).expect("restore cwd");
        assert_eq!(
            backup_value
                .pointer("/result/data/status")
                .and_then(Value::as_str),
            Some("backed_up")
        );
        let restore_value: Value =
            serde_json::from_str(&restore.expect("restore result")).expect("restore JSON");
        assert_eq!(
            restore_value
                .pointer("/result/data/status")
                .and_then(Value::as_str),
            Some("restored")
        );
        let rows = store
            .adapter
            .query(
                &store.config,
                &store.schema,
                &Query {
                    entity: "record".to_owned(),
                    fields: vec!["title".to_owned()],
                    filter: Some(Predicate::Equal("id".to_owned(), Value::from(1))),
                    order: Vec::new(),
                    limit: 1,
                    offset: 0,
                },
            )
            .expect("restored query");
        assert_eq!(rows[0]["title"], "original");
        assert_eq!(
            fs::read_to_string(root.join("tmp/state.json")).expect("unrelated file"),
            r#"{"items":[]}"#
        );
    }

    #[test]
    /// Proves job and integration JSON-RPC methods mutate their local runtime state.
    fn json_rpc_executes_jobs_and_integration_native_surfaces() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-jobs-integrations");
        fs::create_dir_all(root.join("apps/ops_app/data/contracts")).expect("contracts");
        fs::create_dir_all(root.join("dist/apps/ops_app/data/contracts")).expect("integrations");
        fs::create_dir_all(root.join("tmp")).expect("tmp");
        fs::write(
            root.join("apps/ops_app/pharos.app.yml"),
            "app_id: ops_app\ndatabase:\n  migration_contract: data/contracts/database.json\n",
        )
        .expect("manifest");
        fs::write(
            root.join("apps/ops_app/app.conf"),
            format!(
                "db_backend=sqlite\ndb_path={}\n",
                root.join("tmp/jobs.sqlite3").display()
            ),
        )
        .expect("app config");
        let job_entity = serde_json::json!({
            "name": "job_execution", "identity": {"auto_integer": "id"},
            "fields": [
                {"name":"id","kind":"integer","nullable":false,"constraints":[]},
                {"name":"job_id","kind":"text","nullable":false,"max_length":128,"constraints":[]},
                {"name":"handler_id","kind":"text","nullable":false,"max_length":128,"constraints":[]},
                {"name":"queue_name","kind":"text","nullable":false,"max_length":128,"constraints":[]},
                {"name":"execution_status","kind":"text","nullable":false,"max_length":128,"constraints":[]},
                {"name":"attempt_count","kind":"integer","nullable":false,"constraints":[]},
                {"name":"completed_at","kind":"timestamp","nullable":true,"constraints":[]},
                {"name":"available_at","kind":"timestamp","nullable":false,"default":{"literal":"1970-01-01T00:00:00Z"},"constraints":[]},
                {"name":"max_attempts","kind":"integer","nullable":false,"default":{"literal":3},"constraints":[]},
                {"name":"workflow_execution_id","kind":"integer","nullable":true,"constraints":[]}
            ], "unique": [], "indexes": [], "conditional_indexes": []
        });
        let reference_contract = pharos_runtime_compiler::database::load_source(
            &Path::new(env!("CARGO_MANIFEST_DIR")).join("apps/ucal/data/contracts/database.yml"),
            "ucal",
        )
        .expect("shared integration operation declaration");
        let mut delivery = reference_contract
            .schema
            .entities
            .iter()
            .find(|entity| entity.name == "integration_delivery")
            .unwrap()
            .clone();
        // This focused tool test excludes unrelated business/identity records.
        for field in &mut delivery.fields {
            field.references = None;
            field.on_delete = None;
        }
        let delivery_entity = serde_json::to_value(&delivery).unwrap();
        let changes: Vec<pharos_runtime_database::operations::SchemaChange> =
            serde_json::from_value(serde_json::json!([{"create_entity":job_entity.clone()}, {"create_entity":delivery_entity.clone()}]))
                .expect("logical changes");
        let contract = pharos_runtime_database::contract::AppDataContract {
            schema: serde_json::from_value(serde_json::json!({
                "app_id":"ops_app", "entities":[job_entity, delivery_entity]
            }))
            .expect("logical schema"),
            migrations: vec![pharos_runtime_database::operations::Migration {
                app_id: "ops_app".to_owned(),
                id: "jobs".to_owned(),
                checksum: pharos_runtime_database::contract::migration_checksum(
                    "ops_app", "jobs", &changes,
                )
                .expect("logical checksum"),
                changes,
            }],
            legacy_adoption: None,
        };
        fs::write(
            root.join("apps/ops_app/data/contracts/database.json"),
            serde_json::to_vec(&contract).expect("encode logical contract"),
        )
        .expect("write logical contract");
        for relative in ["pharos.app.yml", "app.conf", "data/contracts/database.json"] {
            fs::copy(
                root.join("apps/ops_app").join(relative),
                root.join("dist/apps/ops_app").join(relative),
            )
            .expect("staged logical app inputs");
        }
        let database_config = pharos_runtime_database::DbBackendConfig {
            backend: "sqlite".to_owned(),
            sqlite_path: Some(root.join("tmp/jobs.sqlite3")),
            ..Default::default()
        };
        let adapter = super::super::database::operations::resolve(&database_config)
            .expect("configured jobs adapter");
        adapter
            .apply_contract(&database_config, &contract)
            .expect("apply logical jobs schema");
        adapter
            .transact(
                &database_config,
                &contract.schema,
                &pharos_runtime_database::operations::Transaction {
                    steps: vec![pharos_runtime_database::operations::Mutation::Insert {
                        entity: "job_execution".to_owned(),
                        values: BTreeMap::from([
                            (
                                "job_id".to_owned(),
                                pharos_runtime_database::operations::WriteValue::Literal(
                                    serde_json::json!("send-reminder"),
                                ),
                            ),
                            (
                                "handler_id".to_owned(),
                                pharos_runtime_database::operations::WriteValue::Literal(
                                    serde_json::json!("local_noop"),
                                ),
                            ),
                            (
                                "queue_name".to_owned(),
                                pharos_runtime_database::operations::WriteValue::Literal(
                                    serde_json::json!("default"),
                                ),
                            ),
                            (
                                "execution_status".to_owned(),
                                pharos_runtime_database::operations::WriteValue::Literal(
                                    serde_json::json!("queued"),
                                ),
                            ),
                            (
                                "attempt_count".to_owned(),
                                pharos_runtime_database::operations::WriteValue::Literal(
                                    serde_json::json!(0),
                                ),
                            ),
                        ]),
                    }],
                    idempotency_key: None,
                },
            )
            .expect("seed logical job");
        fs::write(root.join("tmp/state.json"), r#"{"integration_deliveries":[],"integration_delivery_attempts":[],"webhook_receipts":[]}"#).expect("state");
        fs::write(
            root.join("dist/apps/ops_app/data/contracts/integrations.json"),
            r#"{"adapters":[{"adapter_id":"local_webhook","adapter_kind":"webhook","target_url":"http://localhost:1/receive","content_type":"application/json","max_attempts":1,"timeout_seconds":1,"allow_plaintext_local":true}]}"#,
        )
        .expect("integrations");
        let original_dir = std::env::current_dir().expect("cwd");
        std::env::set_current_dir(&root).expect("chdir");
        let jobs = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"jobs","method":"pharos.run_jobs","params":{"app_id":"ops_app","app_dir":"apps/ops_app","db_path":"tmp/jobs.sqlite3","backend":"sqlite","case":"first_queued"}}"#,
        );
        let integration = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"integration","method":"pharos.deliver_integration","params":{"app_id":"ops_app","build_dir":"dist","state_path":"tmp/state.json","adapter_id":"local_webhook","event_kind":"ops_ready","resource_id":"task:1","payload_json":"{\"ok\":true}"}}"#,
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        let jobs_value: Value = serde_json::from_str(&jobs).expect("jobs json");
        assert_eq!(
            jobs_value
                .pointer("/result/data/status")
                .and_then(Value::as_str),
            Some("ok")
        );
        assert!(jobs_value.to_string().contains("succeeded"));
        let integration_value: Value =
            serde_json::from_str(&integration).expect("integration json");
        assert_eq!(
            integration_value
                .pointer("/result/data/report_id")
                .and_then(Value::as_str),
            Some("pharos-integrations-inspect-v1"),
            "integration response: {integration_value}"
        );
        assert_eq!(
            integration_value
                .pointer("/result/data/operation/queued_delivery_count")
                .and_then(Value::as_i64),
            Some(1)
        );
        let state = fs::read_to_string(root.join("tmp/state.json")).expect("state");
        assert_eq!(
            serde_json::from_str::<Value>(&state).unwrap(),
            serde_json::json!({"integration_deliveries":[],"integration_delivery_attempts":[],"webhook_receipts":[]})
        );
        let deliveries = pharos_runtime_database::integration::integration_rows(
            adapter.as_ref(),
            &database_config,
            &contract.schema,
            "integration_delivery",
            10,
        )
        .unwrap();
        assert_eq!(deliveries.len(), 1);
        assert_eq!(deliveries[0]["adapter_id"], "local_webhook");
        assert_eq!(deliveries[0]["event_kind"], "ops_ready");
    }

    #[test]
    /// Proves target and readiness JSON-RPC methods report current local prerequisites.
    fn json_rpc_exposes_target_and_readiness_surfaces() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("rpc-target-readiness");
        fs::create_dir_all(root.join("apps")).expect("apps");
        fs::create_dir_all(root.join("scripts")).expect("scripts");
        fs::create_dir_all(root.join("data/framework")).expect("framework");
        fs::write(
            root.join("data/framework/cross-platform-target-registry-v1.json"),
            r#"{"schema":"pharos.cross_platform_target_registry.v1","status":"declared","target_count":1,"targets":[{"target_id":"macos-x86_64","os":"macos","cpu":"x86_64","abi":"darwin","native_binary_status":"supported"}]}"#,
        )
        .expect("registry");
        let original_dir = std::env::current_dir().expect("cwd");
        std::env::set_current_dir(&root).expect("chdir");
        let targets = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"targets","method":"pharos.list_targets","params":{"format":"json"}}"#,
        );
        let readiness = execute_json_rpc(
            r#"{"jsonrpc":"2.0","id":"ready","method":"pharos.production_readiness","params":{"app_id":"architect"}}"#,
        );
        std::env::set_current_dir(original_dir).expect("restore dir");
        let targets_value: Value = serde_json::from_str(&targets).expect("targets json");
        assert_eq!(
            targets_value
                .pointer("/result/data/schema")
                .and_then(Value::as_str),
            Some("pharos.targets.v1")
        );
        let readiness_value: Value = serde_json::from_str(&readiness).expect("readiness json");
        assert_eq!(
            readiness_value
                .pointer("/result/data/schema")
                .and_then(Value::as_str),
            Some("pharos.agent.production_readiness.v1")
        );
        assert!(
            readiness_value
                .pointer("/result/data/checks")
                .and_then(Value::as_array)
                .expect("checks")
                .iter()
                .any(|check| check.get("capability_id").and_then(Value::as_str)
                    == Some("builtin_offline_speech_to_text")
                    && check.get("status").and_then(Value::as_str) == Some("blocked"))
        );
        assert_eq!(
            readiness_value
                .pointer("/result/data/local_detection/media_artifacts/rust_native_only")
                .and_then(Value::as_bool),
            Some(true)
        );
        assert_eq!(
            readiness_value
                .pointer(
                    "/result/data/local_detection/media_artifacts/capabilities/offline_rust_stt"
                )
                .and_then(Value::as_bool),
            Some(false)
        );
    }

    #[test]
    /// Proves target projection lists every target from the registry without fixed counts.
    fn target_registry_projection_matches_registry_targets() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let registry = read_target_registry(&repo).expect("registry");
        let registry_targets = registry_targets(&registry).expect("registry targets");
        let projection: Value =
            serde_json::from_str(&target_registry_projection(&repo).expect("projection"))
                .expect("projection json");
        assert_eq!(
            projection.get("schema").and_then(Value::as_str),
            Some("pharos.targets.v1")
        );
        assert_eq!(
            projection.get("target_count").and_then(Value::as_u64),
            Some(registry_targets.len() as u64)
        );
        assert_eq!(
            projection
                .get("targets")
                .and_then(Value::as_array)
                .expect("projected targets"),
            &registry_targets
        );
    }

    #[test]
    /// Proves host detection maps supported hosts and returns actionable unknown reports.
    fn host_detection_uses_registry_targets_and_unknown_advice() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let detected: Value =
            serde_json::from_str(&host_detection_report(&repo, "Darwin", "arm64").expect("host"))
                .expect("host json");
        assert_eq!(
            detected.get("status").and_then(Value::as_str),
            Some("detected")
        );
        assert_eq!(
            detected.get("host_build_target").and_then(Value::as_str),
            Some("macos-arm64")
        );
        assert_eq!(
            detected
                .get("release_target_candidate")
                .and_then(Value::as_str),
            Some("macos-arm64")
        );

        let unknown: Value =
            serde_json::from_str(&host_detection_report(&repo, "plan9", "mips").expect("unknown"))
                .expect("unknown json");
        assert_eq!(
            unknown.get("status").and_then(Value::as_str),
            Some("unknown")
        );
        assert_eq!(
            unknown.get("host_build_target").and_then(Value::as_str),
            Some("unknown")
        );
        assert!(
            unknown
                .get("advice")
                .and_then(Value::as_str)
                .expect("advice")
                .contains("Pass --target explicitly")
        );
    }

    #[test]
    /// Proves container runtime manifests and Debian packaging keep mutable state external.
    fn container_runtime_contracts_keep_package_and_state_boundaries() {
        let _bridge_test_guard = bridge_test_lock();
        let repo = repo_root();
        let control =
            fs::read_to_string(repo.join("cross/packaging/debian/control.in")).expect("control");
        assert!(control.contains("Depends: adduser, sqlite3\n"));
        assert!(
            !control
                .lines()
                .find(|line| line.starts_with("Depends:"))
                .expect("depends")
                .contains("systemd")
        );
        assert!(control.contains("Suggests: redis-server, systemd\n"));

        let postinst =
            fs::read_to_string(repo.join("cross/packaging/debian/postinst")).expect("postinst");
        assert!(postinst.contains("[ \"${PHAROS_CONTAINER:-0}\" != \"1\" ]"));
        assert!(postinst.contains("systemctl enable pharos.service pharos-ha.service"));
        assert!(postinst.contains("/usr/bin/pharos migrate apply app"));

        let prerm = fs::read_to_string(repo.join("cross/packaging/debian/prerm")).expect("prerm");
        assert!(prerm.contains("[ \"${PHAROS_CONTAINER:-0}\" = \"1\" ]"));
        assert!(prerm.contains("systemctl stop pharos-ha.service pharos.service"));

        let dockerfile =
            fs::read_to_string(repo.join("containers/Dockerfile.runtime")).expect("dockerfile");
        assert!(dockerfile.contains("FROM ubuntu:24.04@sha256:"));
        assert!(dockerfile.contains("ENV PHAROS_CONTAINER=1"));
        assert!(dockerfile.contains("apt-get install -y --no-install-recommends"));
        assert!(dockerfile.contains("USER pharos:pharos"));
        assert!(dockerfile.contains("HEALTHCHECK"));
        assert!(dockerfile.contains("\"/srv/pharos/apps\""));
        assert!(dockerfile.contains("\"/var/lib/pharos/media\""));
        assert!(!dockerfile.contains("systemctl"));
        assert!(!dockerfile.contains("cargo build"));
        assert!(dockerfile.contains("test ! -d /root/.cargo"));

        let compose = fs::read_to_string(repo.join("containers/compose/pharos-runtime.yml"))
            .expect("compose");
        for volume in [
            "pharos-apps:/srv/pharos/apps:ro",
            "pharos-data:/var/lib/pharos",
            "pharos-state:/var/state/pharos",
            "pharos-media:/var/lib/pharos/media",
            "pharos-architect-vault:/var/lib/pharos/architect/vault",
        ] {
            assert!(compose.contains(volume), "missing compose volume {volume}");
        }
        assert!(compose.contains("read_only: true"));
        assert!(compose.contains("PHAROS_ARCHITECT_ROOT_KEY"));

        let kube = fs::read_to_string(repo.join("containers/kubernetes/pharos-runtime.yml"))
            .expect("kubernetes");
        assert!(kube.contains("runAsNonRoot: true"));
        assert!(kube.contains("path: /ready"));
        assert!(kube.contains("path: /live"));
        assert!(kube.contains("mountPath: /srv/pharos/apps, readOnly: true"));
        assert!(kube.contains("mountPath: /run/secrets/pharos_architect_root_key, readOnly: true"));
        assert!(kube.contains("claimName: pharos-media"));
        assert!(kube.contains("claimName: pharos-architect-vault"));
    }

    #[test]
    /// Proves legacy app lifecycle verbs remain classified as active wrappers.
    fn legacy_app_lifecycle_verbs_remain_active() {
        let _bridge_test_guard = bridge_test_lock();
        let verbs = active_cli_verbs();
        for verb in ["build", "verify", "doctor", "migrate", "scaffold", "seed"] {
            let entry = verbs
                .iter()
                .find(|entry| entry.get("verb").and_then(Value::as_str) == Some(verb))
                .expect("verb entry");
            assert_eq!(entry.get("active").and_then(Value::as_bool), Some(true));
        }
        for verb in ["targets", "host"] {
            let entry = verbs
                .iter()
                .find(|entry| entry.get("verb").and_then(Value::as_str) == Some(verb))
                .expect("target verb entry");
            assert_eq!(
                entry.get("owner").and_then(Value::as_str),
                Some("target_registry")
            );
            assert_eq!(entry.get("active").and_then(Value::as_bool), Some(true));
        }
        assert_eq!(
            super::super::runtime_report_id_for_verb("build"),
            "pharos-local-app-build-v1"
        );
        assert_eq!(
            super::super::runtime_report_id_for_verb("verify"),
            "pharos-local-app-build-v1"
        );
        assert_eq!(
            super::super::runtime_report_id_for_verb("doctor"),
            "pharos-doctor-v1"
        );
    }

    #[test]
    /// Proves the baseline inventory writer refuses output outside the repository.
    fn baseline_inventory_rejects_external_output_root() {
        let _bridge_test_guard = bridge_test_lock();
        let outside =
            std::env::temp_dir().join(format!("pharos-agent-outside-{}", std::process::id()));
        assert_eq!(write_baseline_inventory(&repo_root(), &outside), Err(64));
        assert_eq!(
            write_baseline_inventory(&repo_root(), Path::new("../outside")),
            Err(64)
        );
    }

    #[test]
    /// Proves JSON-RPC parsing rejects malformed and oversized requests.
    fn json_rpc_rejects_malformed_and_oversized_requests() {
        let _bridge_test_guard = bridge_test_lock();
        assert_eq!(
            parse_json_rpc_request("{not-json"),
            Err(AgentErrorKind::InvalidJson)
        );
        let oversized = format!(
            r#"{{"jsonrpc":"2.0","id":"req","method":"pharos.query_index","params":{{"body":"{}"}}}}"#,
            "x".repeat(RPC_REQUEST_LIMIT_BYTES)
        );
        assert_eq!(
            parse_json_rpc_request(&oversized),
            Err(AgentErrorKind::CapacityExceeded)
        );
    }

    #[test]
    /// Proves JSON-RPC validation rejects unknown method shapes and invalid params.
    fn json_rpc_rejects_unknown_method_shape_and_invalid_params() {
        let _bridge_test_guard = bridge_test_lock();
        let unknown = r#"{"jsonrpc":"2.0","id":"req-1","method":"query_index","params":{}}"#;
        assert_eq!(
            parse_json_rpc_request(unknown),
            Err(AgentErrorKind::MethodNotFound)
        );
        let bad_params =
            r#"{"jsonrpc":"2.0","id":"req-1","method":"pharos.query_index","params":[]}"#;
        assert_eq!(
            parse_json_rpc_request(bad_params),
            Err(AgentErrorKind::InvalidEnvelope)
        );
        let valid = parse_json_rpc_request(
            r#"{"jsonrpc":"2.0","id":"req-1","method":"pharos.query_index","params":{"query":"routes"}}"#,
        )
        .expect("valid request");
        assert_eq!(valid.method, "pharos.query_index");
    }

    #[test]
    /// Proves app identifiers use the same bounded ASCII identifier surface.
    fn app_identifier_normalization_rejects_injection_shapes() {
        let _bridge_test_guard = bridge_test_lock();
        assert_eq!(normalize_app_id("todo_list").expect("app id"), "todo_list");
        assert_eq!(
            normalize_app_id("../todo"),
            Err(AgentErrorKind::InvalidIdentifier)
        );
        assert_eq!(
            normalize_app_id("todo list"),
            Err(AgentErrorKind::InvalidIdentifier)
        );
        assert_eq!(
            normalize_app_id(&"a".repeat(65)),
            Err(AgentErrorKind::InvalidIdentifier)
        );
    }

    #[test]
    /// Proves repository path classification rejects traversal and separates output classes.
    fn path_classification_rejects_traversal_and_classifies_outputs() {
        let _bridge_test_guard = bridge_test_lock();
        assert_eq!(
            classify_repo_path("apps/todo_list/pharos.app.yml").expect("source"),
            PathClassification::Source
        );
        assert_eq!(
            classify_repo_path("target/agent/baseline-inventory.json").expect("artifact"),
            PathClassification::Artifact
        );
        assert_eq!(
            classify_repo_path("tmp/pharos-agent/test").expect("temp"),
            PathClassification::Temp
        );
        assert_eq!(
            classify_repo_path("../apps/todo_list"),
            Err(AgentErrorKind::InvalidPath)
        );
    }

    #[test]
    /// Proves canonical repository path resolution rejects symlink escape.
    fn repo_path_resolution_rejects_symlink_escape() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("symlink");
        fs::create_dir_all(root.join("apps")).expect("apps");
        let outside = temp_root("outside");
        let link = root.join("apps/outside-link");
        #[cfg(unix)]
        std::os::unix::fs::symlink(&outside, &link).expect("symlink");
        #[cfg(windows)]
        std::os::windows::fs::symlink_dir(&outside, &link).expect("symlink");
        assert_eq!(
            resolve_existing_repo_path(&root, "apps/outside-link"),
            Err(AgentErrorKind::InvalidPath)
        );
    }

    #[test]
    /// Proves stale or malformed plan digests fail before authoring can proceed.
    fn stale_plan_digest_is_rejected() {
        let _bridge_test_guard = bridge_test_lock();
        let current = "a".repeat(64);
        assert_eq!(plan_digest_current(&current, &current), Ok(()));
        assert_eq!(
            plan_digest_current(&"b".repeat(64), &current),
            Err(AgentErrorKind::StalePlan)
        );
        assert_eq!(
            plan_digest_current("not-a-digest", &current),
            Err(AgentErrorKind::InvalidIdentifier)
        );
    }

    #[test]
    /// Proves secret-looking values are redacted from report text.
    fn secret_like_text_is_redacted() {
        let _bridge_test_guard = bridge_test_lock();
        let (text, changed) = redact_secret_like_text("api_key=abc123 visible token=xyz");
        assert!(changed);
        assert_eq!(text, "[REDACTED] visible [REDACTED]");
    }

    #[test]
    /// Proves write-capable operations cannot acquire two concurrent repo locks.
    fn operation_lock_rejects_concurrent_writers() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("lock");
        let first = acquire_operation_lock(&root).expect("first lock");
        assert_eq!(
            acquire_operation_lock(&root).err(),
            Some(AgentErrorKind::LockBusy)
        );
        drop(first);
        assert!(acquire_operation_lock(&root).is_ok());
    }

    #[test]
    /// Proves the encrypted fallback backend stores, rotates, lists, and unsets secrets safely.
    fn encrypted_credential_backend_round_trips_without_plaintext_reports() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("vault");
        let backend = EncryptedFileCredentialBackend::new(
            root.join("vault/agent.vault.enc"),
            b"01234567890123456789012345678901".to_vec(),
        )
        .expect("backend");
        let first = backend
            .put_secret("llm.mock.api_key", b"sk-test-secret")
            .expect("put secret");
        assert_eq!(first.ref_name, "llm.mock.api_key");
        assert!(first.present);
        assert_eq!(
            backend.get_secret("llm.mock.api_key").expect("read secret"),
            b"sk-test-secret"
        );
        let rotated = backend
            .put_secret("llm.mock.api_key", b"sk-rotated-secret")
            .expect("rotate secret");
        assert_eq!(rotated.revision, first.revision + 1);
        let listed = backend.list_secret_refs().expect("list refs");
        assert_eq!(listed.len(), 1);
        assert_eq!(listed[0].ref_name, "llm.mock.api_key");
        let vault_text = fs::read_to_string(root.join("vault/agent.vault.enc")).expect("vault");
        assert!(!vault_text.contains("sk-test-secret"));
        assert!(!vault_text.contains("sk-rotated-secret"));
        assert!(backend.unset_secret("llm.mock.api_key").expect("unset"));
        assert!(backend.list_secret_refs().expect("list empty").is_empty());
    }

    #[test]
    /// Proves the encrypted fallback backend fails closed on missing key authority and tampering.
    fn encrypted_credential_backend_fails_closed_for_missing_key_and_tamper() {
        let _bridge_test_guard = bridge_test_lock();
        let root = temp_root("vault-tamper");
        let vault_path = root.join("vault/agent.vault.enc");
        assert_eq!(
            EncryptedFileCredentialBackend::new(vault_path.clone(), b"short".to_vec()).err(),
            Some(AgentErrorKind::CredentialUnavailable)
        );
        let backend = EncryptedFileCredentialBackend::new(
            vault_path.clone(),
            b"01234567890123456789012345678901".to_vec(),
        )
        .expect("backend");
        backend
            .put_secret("llm.mock.api_key", b"sk-test-secret")
            .expect("put secret");
        fs::write(&vault_path, "{\"schema\":\"pharos.agent.encrypted_credential_vault.v1\",\"salt_hex\":\"00\",\"nonce_hex\":\"00\",\"ciphertext_hex\":\"00\"}\n")
            .expect("tamper");
        assert_eq!(
            backend.get_secret("llm.mock.api_key").err(),
            Some(AgentErrorKind::CredentialUnavailable)
        );
    }

    #[cfg(unix)]
    #[test]
    /// Proves the encrypted fallback backend uses restrictive filesystem permissions.
    fn encrypted_credential_backend_sets_restrictive_permissions() {
        let _bridge_test_guard = bridge_test_lock();
        use std::os::unix::fs::PermissionsExt;

        let root = temp_root("vault-perms");
        let vault_path = root.join("vault/agent.vault.enc");
        let backend = EncryptedFileCredentialBackend::new(
            vault_path.clone(),
            b"01234567890123456789012345678901".to_vec(),
        )
        .expect("backend");
        backend
            .put_secret("llm.mock.api_key", b"sk-test-secret")
            .expect("put secret");
        let dir_mode = fs::metadata(root.join("vault"))
            .expect("dir metadata")
            .permissions()
            .mode()
            & 0o777;
        let file_mode = fs::metadata(vault_path)
            .expect("file metadata")
            .permissions()
            .mode()
            & 0o777;
        assert_eq!(dir_mode, 0o700);
        assert_eq!(file_mode, 0o600);
    }

    #[test]
    /// Proves target profiles parse only non-secret policy-compatible settings.
    fn target_profile_parsing_enforces_policy() {
        let _bridge_test_guard = bridge_test_lock();
        let profile = parse_target_profile(
            r#"{"schema":"pharos.agent.target_profile.v1","target_id":"qa-1","environment":"qa","transport":"oci_registry","artifact_kind":"oci_service","allowed_app_ids":["todo_list"],"secret_refs":["deploy.targets.qa-1.registry_token"]}"#,
        )
        .expect("profile");
        assert_eq!(profile.target_id, "qa-1");

        assert_eq!(
            parse_target_profile(
                r#"{"schema":"pharos.agent.target_profile.v1","target_id":"qa-1","environment":"qa","transport":"oci_registry","artifact_kind":"native_package","allowed_app_ids":["todo_list"],"secret_refs":["deploy.targets.qa-1.registry_token"]}"#
            )
            .err(),
            Some(AgentErrorKind::PolicyViolation)
        );
        assert_eq!(
            parse_target_profile(
                r#"{"schema":"pharos.agent.target_profile.v1","target_id":"prod-1","environment":"production","transport":"ssh_debian","artifact_kind":"native_package","allowed_app_ids":["todo_list"],"secret_refs":[]}"#
            )
            .err(),
            Some(AgentErrorKind::PolicyViolation)
        );
        assert_eq!(
            parse_target_profile(
                r#"{"schema":"pharos.agent.target_profile.v1","target_id":"qa-1","environment":"qa","transport":"kubernetes","artifact_kind":"oci_service","allowed_app_ids":["../todo"],"secret_refs":["deploy.targets.qa-1.kubeconfig"]}"#
            )
            .err(),
            Some(AgentErrorKind::InvalidIdentifier)
        );
        assert_eq!(
            parse_target_profile(
                r#"{"schema":"pharos.agent.target_profile.v1","target_id":"qa-1","environment":"qa","transport":"kubernetes","artifact_kind":"oci_service","allowed_app_ids":["todo_list"],"secret_refs":["token=secret"]}"#
            )
            .err(),
            Some(AgentErrorKind::InvalidIdentifier)
        );
    }
}