pharos_runtime_core/

application_ir.rs

//! Canonical typed application contract consumed by the native runtime.

use std::collections::{BTreeMap, BTreeSet};
use std::fs;
use std::path::{Path, PathBuf};

use serde_json::Value;
use sha2::{Digest, Sha256};
/// Schema identifier emitted for compiled application IR documents.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::application_ir::APPLICATION_IR_VERSION;
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for the surrounding module surface.
pub const APPLICATION_IR_VERSION: &str = "pharos.application-ir.v1";
/// Declarative contract version accepted by this runtime.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::application_ir::CONTRACT_VERSION;
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for the surrounding module surface.
pub const CONTRACT_VERSION: &str = "1.0";

#[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd)]
/// Stable identifier used for routes, actions, policies, and other cross-linked declarations.
///
/// # Fields
///
/// - This type stores module-owned state for [`crate::application_ir::ContractId`].
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::ContractId>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct ContractId(String);

impl ContractId {
    /// Parses one validated contract identifier.
    ///
    /// # Parameters
    ///
    /// - `value`: Input consumed by [`crate::application_ir::parse`].
    ///
    /// # Returns
    ///
    /// Returns the successful value produced by [`crate::application_ir::parse`] or an error when the operation fails.
    ///
    /// # Errors
    ///
    /// Returns an error value when [`crate::application_ir::parse`] cannot complete successfully.
    ///
    /// # Performance
    ///
    /// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::application_ir::parse`].
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_core::application_ir::parse("value");
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::application_ir`] for adjacent helpers that share the same runtime surface.
    pub fn parse(value: &str) -> Result<Self, ApplicationIrError> {
        if value.is_empty()
            || value.len() > 128
            || !value
                .bytes()
                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
        {
            return Err(ApplicationIrError::InvalidId(value.to_owned()));
        }
        Ok(Self(value.to_owned()))
    }
    /// Returns the canonical identifier text.
    ///
    /// # Returns
    ///
    /// Returns the computed value produced by [`crate::application_ir::as_str`].
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_core::application_ir::as_str();
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::application_ir`] for adjacent helpers that share the same runtime surface.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Exact source location preserved for a compiled declaration.
///
/// # Fields
///
/// - `path`: Stored field on `SourceProvenance`.
/// - `pointer`: Stored field on `SourceProvenance`.
/// - `line`: Stored field on `SourceProvenance`.
/// - `column`: Stored field on `SourceProvenance`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::SourceProvenance>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct SourceProvenance {
    pub path: PathBuf,
    pub pointer: String,
    pub line: usize,
    pub column: usize,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Effective route security settings after contract compilation.
///
/// # Fields
///
/// - `csrf_mode`: Stored field on `RouteSecurityPosture`.
/// - `trusted_origin_policy`: Stored field on `RouteSecurityPosture`.
/// - `tenant_scope`: Stored field on `RouteSecurityPosture`.
/// - `rate_limit_policy`: Stored field on `RouteSecurityPosture`.
/// - `capability_policy`: Stored field on `RouteSecurityPosture`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::RouteSecurityPosture>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct RouteSecurityPosture {
    pub csrf_mode: String,
    pub trusted_origin_policy: String,
    pub tenant_scope: String,
    pub rate_limit_policy: String,
    pub capability_policy: String,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Bounded side effects declared for one action.
///
/// # Fields
///
/// - `reads`: Stored field on `ActionEffects`.
/// - `writes`: Stored field on `ActionEffects`.
/// - `emits`: Stored field on `ActionEffects`.
/// - `enqueues`: Stored field on `ActionEffects`.
/// - `external_calls`: Stored field on `ActionEffects`.
/// - `cross_tenant`: Stored field on `ActionEffects`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::ActionEffects>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct ActionEffects {
    pub reads: BTreeSet<String>,
    pub writes: BTreeSet<String>,
    pub emits: BTreeSet<String>,
    pub enqueues: BTreeSet<String>,
    pub external_calls: BTreeSet<String>,
    pub cross_tenant: bool,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Compiled action declaration with validated identifiers and effect boundaries.
///
/// # Fields
///
/// - `id`: Stored field on `ActionIr`.
/// - `entity_id`: Stored field on `ActionIr`.
/// - `policy_id`: Stored field on `ActionIr`.
/// - `effects`: Stored field on `ActionIr`.
/// - `source`: Stored field on `ActionIr`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::ActionIr>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct ActionIr {
    pub id: ContractId,
    pub entity_id: Option<ContractId>,
    pub policy_id: Option<ContractId>,
    pub effects: ActionEffects,
    pub source: SourceProvenance,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Compiled route declaration with validated target references and security posture.
///
/// # Fields
///
/// - `id`: Stored field on `RouteIr`.
/// - `path`: Stored field on `RouteIr`.
/// - `kind`: Stored field on `RouteIr`.
/// - `method`: Stored field on `RouteIr`.
/// - `action_id`: Stored field on `RouteIr`.
/// - `page_id`: Stored field on `RouteIr`.
/// - `policy_id`: Stored field on `RouteIr`.
/// - `auth_gate`: Stored field on `RouteIr`.
/// - `security`: Stored field on `RouteIr`.
/// - `source`: Stored field on `RouteIr`.
/// - `compatibility_view`: Stored field on `RouteIr`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::RouteIr>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct RouteIr {
    pub id: ContractId,
    pub path: String,
    pub kind: String,
    pub method: String,
    pub action_id: Option<ContractId>,
    pub page_id: Option<ContractId>,
    pub policy_id: Option<ContractId>,
    pub auth_gate: String,
    pub security: RouteSecurityPosture,
    pub source: SourceProvenance,
    pub compatibility_view: Value,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Canonical in-memory application contract consumed by the runtime.
///
/// # Fields
///
/// - `version`: Stored field on `ApplicationIr`.
/// - `contract_digest`: Stored field on `ApplicationIr`.
/// - `app_id`: Stored field on `ApplicationIr`.
/// - `routes`: Stored field on `ApplicationIr`.
/// - `route_buckets`: Stored field on `ApplicationIr`.
/// - `actions`: Stored field on `ApplicationIr`.
/// - `entities`: Stored field on `ApplicationIr`.
/// - `forms`: Stored field on `ApplicationIr`.
/// - `policies`: Stored field on `ApplicationIr`.
/// - `role_capability_edges`: Stored field on `ApplicationIr`.
/// - `workflows`: Stored field on `ApplicationIr`.
/// - `integrations`: Stored field on `ApplicationIr`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_core::application_ir::ApplicationIr>();
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub struct ApplicationIr {
    pub version: &'static str,
    pub contract_digest: String,
    pub app_id: ContractId,
    pub routes: BTreeMap<ContractId, RouteIr>,
    pub route_buckets: BTreeMap<(String, usize), Vec<ContractId>>,
    pub actions: BTreeMap<ContractId, ActionIr>,
    pub entities: BTreeSet<ContractId>,
    pub forms: BTreeSet<ContractId>,
    pub policies: BTreeSet<ContractId>,
    pub role_capability_edges: BTreeSet<(ContractId, ContractId)>,
    pub workflows: BTreeSet<ContractId>,
    pub integrations: BTreeSet<ContractId>,
}

/// Hashes the complete executable contract set in stable document order.
fn contract_digest(documents: &[(&str, &Value)]) -> Result<String, ApplicationIrError> {
    let mut digest = Sha256::new();
    for (name, document) in documents {
        digest.update(name.as_bytes());
        digest.update([0]);
        digest.update(
            serde_json::to_vec(document)
                .map_err(|_| ApplicationIrError::InvalidDocument((*name).to_owned()))?,
        );
        digest.update([0]);
    }
    Ok(digest
        .finalize()
        .iter()
        .map(|byte| format!("{byte:02x}"))
        .collect())
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Semantic failures that block contract compilation or loading.
///
/// # Variants
///
/// - `MissingDocument`: Supported `ApplicationIrError` variant.
/// - `InvalidDocument`: Supported `ApplicationIrError` variant.
/// - `InvalidId`: Supported `ApplicationIrError` variant.
/// - `DuplicateId`: Supported `ApplicationIrError` variant.
/// - `MissingDeclaration`: Supported `ApplicationIrError` variant.
/// - `UnsupportedVersion`: Supported `ApplicationIrError` variant.
/// - `MissingReference`: Supported `ApplicationIrError` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_core::application_ir::ApplicationIrError::MissingDocument;
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for constructors, helpers, and neighboring runtime types.
pub enum ApplicationIrError {
    MissingDocument(String),
    InvalidDocument(String),
    InvalidId(String),
    DuplicateId(String),
    MissingDeclaration(String),
    UnsupportedVersion(String),
    MissingReference { owner: String, target: String },
}

/// Validates the exact major/minor contract version supported by this runtime.
fn validate_contract_version(document: &Value, name: &str) -> Result<(), ApplicationIrError> {
    match document.get("contract_version").and_then(Value::as_str) {
        Some(CONTRACT_VERSION) => Ok(()),
        Some(version) => Err(ApplicationIrError::UnsupportedVersion(format!(
            "{name}:{version}"
        ))),
        None => Err(ApplicationIrError::MissingDeclaration(format!(
            "{name}.contract_version"
        ))),
    }
}

/// Validates a populated optional contract while allowing an absent empty compatibility view.
fn validate_optional_contract_version(
    document: &Value,
    array_key: &str,
    name: &str,
) -> Result<(), ApplicationIrError> {
    if document
        .get(array_key)
        .and_then(Value::as_array)
        .is_some_and(|rows| !rows.is_empty())
    {
        validate_contract_version(document, name)?;
    }
    Ok(())
}

/// Resolves and validates the route-level security defaults and overrides.
fn route_security_posture(
    route_doc: &Value,
    row: &Value,
    route_id: &str,
) -> Result<RouteSecurityPosture, ApplicationIrError> {
    let defaults = route_doc
        .get("security_defaults")
        .and_then(Value::as_object)
        .ok_or_else(|| {
            ApplicationIrError::MissingDeclaration("routes.security_defaults".to_owned())
        })?;
    let overrides = row.get("security").and_then(Value::as_object);
    let field = |name: &str| {
        overrides
            .and_then(|values| values.get(name))
            .or_else(|| defaults.get(name))
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .map(ToOwned::to_owned)
            .ok_or_else(|| {
                ApplicationIrError::MissingDeclaration(format!("routes.{route_id}.security.{name}"))
            })
    };
    let posture = RouteSecurityPosture {
        csrf_mode: field("csrf_mode")?,
        trusted_origin_policy: field("trusted_origin_policy")?,
        tenant_scope: field("tenant_scope")?,
        rate_limit_policy: field("rate_limit_policy")?,
        capability_policy: field("capability_policy")?,
    };
    if !matches!(
        posture.csrf_mode.as_str(),
        "mutation_required" | "required" | "disabled"
    ) || !matches!(
        posture.trusted_origin_policy.as_str(),
        "mutation_required" | "required" | "disabled"
    ) || !matches!(posture.tenant_scope.as_str(), "policy_bound" | "public")
        || posture.rate_limit_policy.len() > 128
        || !matches!(posture.capability_policy.as_str(), "policy_gate" | "public")
    {
        return Err(ApplicationIrError::InvalidDocument(format!(
            "routes.{route_id}.security"
        )));
    }
    Ok(posture)
}

/// Collects string values from one optional array without permitting empty effects.
fn effect_strings(value: Option<&Value>) -> Result<BTreeSet<String>, ApplicationIrError> {
    let mut values = BTreeSet::new();
    for item in value.and_then(Value::as_array).into_iter().flatten() {
        let text = item
            .as_str()
            .filter(|text| !text.is_empty() && text.len() <= 128)
            .ok_or_else(|| ApplicationIrError::InvalidDocument("action effects".to_owned()))?;
        values.insert(text.to_owned());
    }
    Ok(values)
}

/// Collects scheduled-job identifiers from string or bounded object declarations.
fn effect_job_strings(value: Option<&Value>) -> Result<BTreeSet<String>, ApplicationIrError> {
    let mut values = BTreeSet::new();
    for item in value.and_then(Value::as_array).into_iter().flatten() {
        let text = item
            .as_str()
            .or_else(|| item.get("job_id").and_then(Value::as_str))
            .filter(|text| !text.is_empty() && text.len() <= 128)
            .ok_or_else(|| ApplicationIrError::InvalidDocument("action effects".to_owned()))?;
        values.insert(text.to_owned());
    }
    Ok(values)
}

/// Compiles the existing action declaration into a closed typed effect set.
///
/// # Parameters
///
/// - `action`: Input consumed by [`crate::application_ir::compile_action_effects_for_runtime`].
/// - `transition`: Input consumed by [`crate::application_ir::compile_action_effects_for_runtime`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::application_ir::compile_action_effects_for_runtime`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::application_ir::compile_action_effects_for_runtime`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::application_ir::compile_action_effects_for_runtime`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::application_ir::compile_action_effects_for_runtime(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for adjacent helpers that share the same runtime surface.
pub fn compile_action_effects_for_runtime(
    action: &Value,
    transition: Option<&Value>,
) -> Result<ActionEffects, ApplicationIrError> {
    let mut reads = BTreeSet::new();
    let mut writes = BTreeSet::new();
    reads.extend(effect_strings(
        action
            .get("effect_contract")
            .and_then(|value| value.get("reads")),
    )?);
    writes.extend(effect_strings(
        action
            .get("effect_contract")
            .and_then(|value| value.get("writes")),
    )?);
    if let Some(entity) = action.get("entity_id").and_then(Value::as_str) {
        reads.insert(format!("entity:{entity}"));
        writes.insert(format!("entity:{entity}"));
    }
    for primitive in action
        .get("mutation_primitives")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        if let Some(collection) = primitive.get("collection").and_then(Value::as_str) {
            reads.insert(format!("state:{collection}"));
            writes.insert(format!("state:{collection}"));
        }
        if primitive.get("primitive_kind").and_then(Value::as_str) == Some("set_root_fields") {
            writes.insert("state:root".to_owned());
        }
    }
    let mut emits = BTreeSet::new();
    if let Some(event) = action.get("emits_event").and_then(Value::as_str) {
        emits.insert(event.to_owned());
    }
    if let Some(event) = transition
        .and_then(|value| value.get("emits_event"))
        .and_then(Value::as_str)
    {
        emits.insert(event.to_owned());
    }
    let hooks = action.get("effect_hooks");
    let mut enqueues = BTreeSet::new();
    for source in [
        action.get("scheduled_jobs"),
        hooks.and_then(|value| value.get("scheduled_jobs")),
        transition.and_then(|value| value.get("scheduled_jobs")),
    ] {
        enqueues.extend(effect_job_strings(source)?);
    }
    for notification in hooks
        .and_then(|value| value.get("notifications"))
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let adapter = notification
            .get("adapter_id")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .ok_or_else(|| ApplicationIrError::InvalidDocument("action effects".to_owned()))?;
        enqueues.insert(format!("notification:{adapter}"));
    }
    for audit in hooks
        .and_then(|value| value.get("audit_records"))
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let adapter = audit
            .get("adapter_id")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .ok_or_else(|| ApplicationIrError::InvalidDocument("action effects".to_owned()))?;
        writes.insert("state:audit_log".to_owned());
        writes.insert("state:action_reports".to_owned());
        reads.insert(format!("integration:{adapter}"));
    }
    let mut external_calls = effect_strings(hooks.and_then(|value| value.get("webhook_dispatch")))?;
    for file_record in hooks
        .and_then(|value| value.get("file_records"))
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let adapter = file_record
            .get("adapter_id")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .ok_or_else(|| ApplicationIrError::InvalidDocument("action effects".to_owned()))?;
        reads.insert(format!("integration:{adapter}"));
        external_calls.insert(format!("file:{adapter}"));
    }
    if !action
        .get("mutation_primitives")
        .and_then(Value::as_array)
        .is_none_or(Vec::is_empty)
    {
        for section in [
            "workflow_executions",
            "workflow_execution_events",
            "action_reports",
        ] {
            writes.insert(format!("state:{section}"));
        }
        writes.insert("state:root".to_owned());
    }
    Ok(ActionEffects {
        reads,
        writes,
        emits,
        enqueues,
        external_calls,
        cross_tenant: action
            .get("cross_tenant")
            .and_then(Value::as_bool)
            .unwrap_or(false),
    })
}

/// Returns the workflow transition executed by one action, rejecting ambiguous declarations.
fn action_transition<'a>(
    workflow_doc: &'a Value,
    action_id: &str,
) -> Result<Option<&'a Value>, ApplicationIrError> {
    let matches = workflow_doc
        .get("workflows")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .flat_map(|workflow| {
            workflow
                .get("transitions")
                .and_then(Value::as_array)
                .into_iter()
                .flatten()
        })
        .filter(|transition| transition.get("action_id").and_then(Value::as_str) == Some(action_id))
        .collect::<Vec<_>>();
    match matches.as_slice() {
        [] => Ok(None),
        [transition] => Ok(Some(*transition)),
        _ => Err(ApplicationIrError::InvalidDocument(format!(
            "ambiguous action transition: {action_id}"
        ))),
    }
}

/// Loads a JSON contract document from a packaged application artifact.
fn load_contract(artifact_root: &Path, name: &str) -> Result<(PathBuf, Value), ApplicationIrError> {
    let path = artifact_root.join(format!("data/contracts/{name}.json"));
    let text = fs::read_to_string(&path)
        .map_err(|_| ApplicationIrError::MissingDocument(name.to_owned()))?;
    let value = serde_json::from_str(&text)
        .map_err(|_| ApplicationIrError::InvalidDocument(name.to_owned()))?;
    Ok((path, value))
}

/// Loads an optional contract document as an empty typed collection when undeclared.
fn load_optional_contract(
    artifact_root: &Path,
    name: &str,
    array_key: &str,
) -> Result<(PathBuf, Value), ApplicationIrError> {
    match load_contract(artifact_root, name) {
        Ok(document) => Ok(document),
        Err(ApplicationIrError::MissingDocument(_)) => Ok((
            artifact_root.join(format!("data/contracts/{name}.json")),
            serde_json::json!({array_key: []}),
        )),
        Err(error) => Err(error),
    }
}

/// Collects a canonically ordered identifier set from one contract array.
fn collect_ids(
    document: &Value,
    array_key: &str,
    id_key: &str,
) -> Result<BTreeSet<ContractId>, ApplicationIrError> {
    let mut ids = BTreeSet::new();
    let rows = document
        .get(array_key)
        .and_then(Value::as_array)
        .ok_or_else(|| ApplicationIrError::InvalidDocument(array_key.to_owned()))?;
    for row in rows {
        let raw = row
            .get(id_key)
            .and_then(Value::as_str)
            .ok_or_else(|| ApplicationIrError::InvalidDocument(array_key.to_owned()))?;
        let id = ContractId::parse(raw)?;
        if !ids.insert(id) {
            return Err(ApplicationIrError::DuplicateId(raw.to_owned()));
        }
    }
    Ok(ids)
}

/// Collects a canonically ordered identifier set from a string array.
fn collect_string_ids(
    document: &Value,
    array_key: &str,
) -> Result<BTreeSet<ContractId>, ApplicationIrError> {
    let mut ids = BTreeSet::new();
    for value in document
        .get(array_key)
        .and_then(Value::as_array)
        .ok_or_else(|| ApplicationIrError::InvalidDocument(array_key.to_owned()))?
    {
        let raw = value
            .as_str()
            .ok_or_else(|| ApplicationIrError::InvalidDocument(array_key.to_owned()))?;
        let id = ContractId::parse(raw)?;
        if !ids.insert(id) {
            return Err(ApplicationIrError::DuplicateId(raw.to_owned()));
        }
    }
    Ok(ids)
}

/// Returns a source line for an identifier in a deterministic generated JSON document.
fn source_line(path: &Path, id_key: &str, id: &str) -> usize {
    let needle = format!("\"{id_key}\": \"{id}\"");
    fs::read_to_string(path)
        .ok()
        .and_then(|text| text.lines().position(|line| line.contains(&needle)))
        .map(|line| line + 1)
        .unwrap_or(1)
}

/// Resolves generator-retained YAML provenance with a JSON fallback for legacy artifacts.
fn source_provenance(
    document: &Value,
    generated_path: &Path,
    pointer: String,
    id_key: &str,
    id: &str,
) -> SourceProvenance {
    let source = document.get("__pharos_source");
    let location = source
        .and_then(|value| value.get("locations"))
        .and_then(|value| value.get(format!("{id_key}:{id}")));
    SourceProvenance {
        path: source
            .and_then(|value| value.get("path"))
            .and_then(Value::as_str)
            .map(PathBuf::from)
            .unwrap_or_else(|| generated_path.to_path_buf()),
        pointer,
        line: location
            .and_then(|value| value.get("line"))
            .and_then(Value::as_u64)
            .and_then(|line| usize::try_from(line).ok())
            .unwrap_or_else(|| source_line(generated_path, id_key, id)),
        column: location
            .and_then(|value| value.get("column"))
            .and_then(Value::as_u64)
            .and_then(|column| usize::try_from(column).ok())
            .unwrap_or(1),
    }
}

/// Validates one optional identifier reference against its typed target collection.
fn validate_reference(
    owner: &str,
    row: &Value,
    key: &str,
    targets: &BTreeSet<ContractId>,
) -> Result<(), ApplicationIrError> {
    let Some(raw) = row.get(key).and_then(Value::as_str) else {
        return Ok(());
    };
    let id = ContractId::parse(raw)?;
    if targets.contains(&id) {
        Ok(())
    } else {
        Err(ApplicationIrError::MissingReference {
            owner: owner.to_owned(),
            target: raw.to_owned(),
        })
    }
}

/// Compiles and semantically validates all executable application contracts.
///
/// # Parameters
///
/// - `artifact_root`: Input consumed by [`crate::application_ir::compile_application_ir`].
/// - `manifest`: Input consumed by [`crate::application_ir::compile_application_ir`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::application_ir::compile_application_ir`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::application_ir::compile_application_ir`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::application_ir::compile_application_ir`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_core::application_ir::compile_application_ir(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::application_ir`] for adjacent helpers that share the same runtime surface.
pub fn compile_application_ir(
    artifact_root: &Path,
    manifest: &Value,
) -> Result<ApplicationIr, ApplicationIrError> {
    let app_id = ContractId::parse(
        manifest
            .get("app_id")
            .and_then(Value::as_str)
            .ok_or_else(|| ApplicationIrError::InvalidDocument("manifest".to_owned()))?,
    )?;
    let (route_path, route_doc) = load_contract(artifact_root, "routes")?;
    let (action_path, action_doc) = load_optional_contract(artifact_root, "actions", "actions")?;
    let (_, entity_doc) = load_optional_contract(artifact_root, "entities", "entities")?;
    let (_, form_doc) = load_optional_contract(artifact_root, "forms", "forms")?;
    let (_, policy_doc) = load_optional_contract(artifact_root, "policies", "capabilities")?;
    let (_, workflow_doc) = load_optional_contract(artifact_root, "workflows", "workflows")?;
    let (_, integration_doc) = load_optional_contract(artifact_root, "integrations", "adapters")?;
    validate_contract_version(&route_doc, "routes")?;
    validate_optional_contract_version(&entity_doc, "entities", "entities")?;
    validate_optional_contract_version(&form_doc, "forms", "forms")?;
    validate_optional_contract_version(&policy_doc, "capabilities", "policies")?;
    validate_optional_contract_version(&workflow_doc, "workflows", "workflows")?;
    validate_optional_contract_version(&integration_doc, "adapters", "integrations")?;
    let action_rows = action_doc
        .get("actions")
        .and_then(Value::as_array)
        .ok_or_else(|| ApplicationIrError::InvalidDocument("actions".to_owned()))?;
    if !action_rows.is_empty() {
        validate_contract_version(&action_doc, "actions")?;
        if action_doc
            .get("effect_policy")
            .and_then(|value| value.get("deny_undeclared"))
            .and_then(Value::as_bool)
            != Some(true)
        {
            return Err(ApplicationIrError::MissingDeclaration(
                "actions.effect_policy.deny_undeclared".to_owned(),
            ));
        }
    }
    let mut actions = BTreeMap::new();
    for (index, action) in action_rows.iter().enumerate() {
        let raw_id = action
            .get("action_id")
            .and_then(Value::as_str)
            .ok_or_else(|| ApplicationIrError::InvalidDocument("actions".to_owned()))?;
        let id = ContractId::parse(raw_id)?;
        let entity_id = action
            .get("entity_id")
            .and_then(Value::as_str)
            .map(ContractId::parse)
            .transpose()?;
        let policy_id = action
            .get("policy_gate")
            .and_then(Value::as_str)
            .map(ContractId::parse)
            .transpose()?;
        let record = ActionIr {
            id: id.clone(),
            entity_id,
            policy_id,
            effects: compile_action_effects_for_runtime(
                action,
                action_transition(&workflow_doc, raw_id)?,
            )?,
            source: source_provenance(
                &action_doc,
                &action_path,
                format!("/actions/{index}"),
                "action_id",
                raw_id,
            ),
        };
        if actions.insert(id, record).is_some() {
            return Err(ApplicationIrError::DuplicateId(raw_id.to_owned()));
        }
    }
    for intrinsic in [
        "login",
        "login_account",
        "logout",
        "password_reset_request",
        "request_password_reset",
        "password_reset_complete",
        "complete_password_reset",
        "delete_appointment",
    ] {
        let id = ContractId::parse(intrinsic)?;
        actions.entry(id.clone()).or_insert_with(|| ActionIr {
            id,
            entity_id: None,
            policy_id: None,
            effects: ActionEffects {
                reads: BTreeSet::new(),
                writes: BTreeSet::new(),
                emits: BTreeSet::new(),
                enqueues: BTreeSet::new(),
                external_calls: BTreeSet::new(),
                cross_tenant: false,
            },
            source: SourceProvenance {
                path: action_path.clone(),
                pointer: "/intrinsic-actions".to_owned(),
                line: 1,
                column: 1,
            },
        });
    }
    let mut entities = collect_ids(&entity_doc, "entities", "entity_id")?;
    let forms = collect_ids(&form_doc, "forms", "form_id")?;
    let mut policies = collect_string_ids(&policy_doc, "capabilities")?;
    if policies.is_empty() {
        policies.insert(ContractId::parse("public")?);
    }
    let mut role_capability_edges = BTreeSet::new();
    for edge in policy_doc
        .get("role_capability_edges")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let role = ContractId::parse(
            edge.get("role")
                .and_then(Value::as_str)
                .ok_or_else(|| ApplicationIrError::InvalidDocument("policies".to_owned()))?,
        )?;
        let capability = ContractId::parse(
            edge.get("capability")
                .and_then(Value::as_str)
                .ok_or_else(|| ApplicationIrError::InvalidDocument("policies".to_owned()))?,
        )?;
        if !policies.contains(&capability) {
            return Err(ApplicationIrError::MissingReference {
                owner: role.as_str().to_owned(),
                target: capability.as_str().to_owned(),
            });
        }
        role_capability_edges.insert((role, capability));
    }
    let workflows = collect_ids(&workflow_doc, "workflows", "workflow_id")?;
    let integrations = collect_ids(&integration_doc, "adapters", "adapter_id")?;
    if entities.is_empty() {
        for action in action_doc
            .get("actions")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            if let Some(entity_id) = action.get("entity_id").and_then(Value::as_str) {
                entities.insert(ContractId::parse(entity_id)?);
            }
        }
    }
    for action in action_doc
        .get("actions")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let owner = action
            .get("action_id")
            .and_then(Value::as_str)
            .unwrap_or("action");
        validate_reference(owner, action, "entity_id", &entities)?;
        validate_reference(owner, action, "policy_gate", &policies)?;
    }
    for form in form_doc
        .get("forms")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let owner = form
            .get("form_id")
            .and_then(Value::as_str)
            .unwrap_or("form");
        validate_reference(owner, form, "entity_id", &entities)?;
        if let Some(action_id) = form.get("submits_action").and_then(Value::as_str) {
            let action_id = ContractId::parse(action_id)?;
            if !actions.contains_key(&action_id) {
                return Err(ApplicationIrError::MissingReference {
                    owner: owner.to_owned(),
                    target: action_id.as_str().to_owned(),
                });
            }
        }
    }
    for workflow in workflow_doc
        .get("workflows")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let owner = workflow
            .get("workflow_id")
            .and_then(Value::as_str)
            .unwrap_or("workflow");
        for transition in workflow
            .get("transitions")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            if let Some(action_id) = transition.get("action_id").and_then(Value::as_str) {
                let action_id = ContractId::parse(action_id)?;
                if !actions.contains_key(&action_id) {
                    return Err(ApplicationIrError::MissingReference {
                        owner: owner.to_owned(),
                        target: action_id.as_str().to_owned(),
                    });
                }
            }
            validate_reference(owner, transition, "policy_gate", &policies)?;
        }
    }
    let route_rows = route_doc
        .get("routes")
        .and_then(Value::as_array)
        .ok_or_else(|| ApplicationIrError::InvalidDocument("routes".to_owned()))?;
    let mut routes = BTreeMap::new();
    for (index, row) in route_rows.iter().enumerate() {
        let raw_id = row.get("route_id").and_then(Value::as_str).ok_or_else(|| {
            ApplicationIrError::InvalidDocument(format!("routes/{index}/route_id"))
        })?;
        let id = ContractId::parse(raw_id)?;
        let action_id = row
            .get("action_id")
            .and_then(Value::as_str)
            .map(ContractId::parse)
            .transpose()?;
        if let Some(action_id) = action_id.as_ref()
            && !actions.contains_key(action_id)
        {
            return Err(ApplicationIrError::MissingReference {
                owner: raw_id.to_owned(),
                target: action_id.as_str().to_owned(),
            });
        }
        let policy_id = row
            .get("policy_gate")
            .and_then(Value::as_str)
            .map(ContractId::parse)
            .transpose()?;
        if let Some(policy_id) = policy_id.as_ref()
            && !policies.contains(policy_id)
        {
            return Err(ApplicationIrError::MissingReference {
                owner: raw_id.to_owned(),
                target: policy_id.as_str().to_owned(),
            });
        }
        let route = RouteIr {
            id: id.clone(),
            path: row
                .get("path")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .to_owned(),
            kind: row
                .get("kind")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .to_owned(),
            method: row
                .get("method")
                .and_then(Value::as_str)
                .unwrap_or(if row.get("kind").and_then(Value::as_str) == Some("page") {
                    "GET"
                } else {
                    "POST"
                })
                .to_ascii_uppercase(),
            action_id,
            page_id: row
                .get("page_id")
                .and_then(Value::as_str)
                .map(ContractId::parse)
                .transpose()?,
            policy_id,
            auth_gate: row
                .get("auth_gate")
                .and_then(Value::as_str)
                .unwrap_or_default()
                .to_owned(),
            security: route_security_posture(&route_doc, row, raw_id)?,
            source: source_provenance(
                &route_doc,
                &route_path,
                format!("/routes/{index}"),
                "route_id",
                raw_id,
            ),
            compatibility_view: row.clone(),
        };
        if routes.insert(id, route).is_some() {
            return Err(ApplicationIrError::DuplicateId(raw_id.to_owned()));
        }
    }
    let mut route_buckets: BTreeMap<(String, usize), Vec<ContractId>> = BTreeMap::new();
    for route in routes.values() {
        let segment_count = route
            .path
            .trim_matches('/')
            .split('/')
            .filter(|segment| !segment.is_empty())
            .count();
        route_buckets
            .entry((route.kind.clone(), segment_count))
            .or_default()
            .push(route.id.clone());
    }
    Ok(ApplicationIr {
        version: APPLICATION_IR_VERSION,
        contract_digest: contract_digest(&[
            ("routes", &route_doc),
            ("actions", &action_doc),
            ("entities", &entity_doc),
            ("forms", &form_doc),
            ("policies", &policy_doc),
            ("workflows", &workflow_doc),
            ("integrations", &integration_doc),
        ])?,
        app_id,
        routes,
        route_buckets,
        actions,
        entities,
        forms,
        policies,
        role_capability_edges,
        workflows,
        integrations,
    })
}

#[cfg(test)]
mod tests {
    use super::compile_action_effects_for_runtime;

    #[test]
    /// Performs executable effects include runtime owned workflow and delivery writes.
    fn executable_effects_include_runtime_owned_workflow_and_delivery_writes() {
        let action = serde_json::json!({
            "entity_id": "task",
            "mutation_primitives": [
                {"primitive_kind": "append_record", "collection": "items"},
                {"primitive_kind": "set_root_fields"}
            ],
            "effect_hooks": {
                "notifications": [{"adapter_id": "local-mail"}],
                "webhook_dispatch": ["audit-webhook"]
            }
        });
        let transition = serde_json::json!({
            "emits_event": "task_created",
            "scheduled_jobs": ["notify-task-created"]
        });
        let effects = compile_action_effects_for_runtime(&action, Some(&transition))
            .expect("compile executable effects");
        assert!(effects.writes.contains("state:items"));
        assert!(effects.writes.contains("state:workflow_executions"));
        assert!(effects.writes.contains("state:workflow_execution_events"));
        assert!(effects.writes.contains("state:action_reports"));
        assert!(effects.writes.contains("state:root"));
        assert!(effects.emits.contains("task_created"));
        assert!(effects.enqueues.contains("notify-task-created"));
        assert!(effects.enqueues.contains("notification:local-mail"));
        assert!(effects.external_calls.contains("audit-webhook"));
    }
}