pharos_runtime_compiler/

features.rs

//! Compilation and lookup for coherent declarative application features.

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

use pharos_runtime_core::application_ir::{CONTRACT_VERSION, ContractId};
use serde_json::{Map, Value};
use sha2::{Digest, Sha256};

const MAX_FEATURE_FILES: usize = 128;
const MAX_TEMPLATE_FILES: usize = 4_096;
const MAX_TEMPLATE_DEPTH: usize = 32;
const INTERACTION_CLIENT: &str = include_str!("../assets/interaction-v1.js");

#[derive(Debug, Clone, Eq, PartialEq)]
/// A bounded feature compilation failure that prevents an ambiguous artifact.
///
/// # Variants
///
/// - `InvalidDocument`: Supported `FeatureCompileError` variant.
/// - `DuplicateId`: Supported `FeatureCompileError` variant.
/// - `MissingReference`: Supported `FeatureCompileError` variant.
/// - `UnsafePath`: Supported `FeatureCompileError` variant.
/// - `Io`: Supported `FeatureCompileError` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_runtime_compiler::features::FeatureCompileError::InvalidDocument;
/// ```
///
/// # Related
///
/// - [`crate::features`] for constructors, helpers, and neighboring runtime types.
pub enum FeatureCompileError {
    InvalidDocument(String),
    DuplicateId(String),
    MissingReference(String),
    UnsafePath(String),
    Io(String),
}

/// Returns a validated portable declaration identifier.
fn declaration_id(value: &str) -> Result<String, FeatureCompileError> {
    ContractId::parse(value)
        .map(|id| id.as_str().to_owned())
        .map_err(|_| FeatureCompileError::InvalidDocument(value.to_owned()))
}

/// Returns a safe absolute artifact path for one declared relative path.
fn safe_artifact_path(root: &Path, relative: &str) -> Result<PathBuf, FeatureCompileError> {
    let path = Path::new(relative);
    if relative.is_empty()
        || path.is_absolute()
        || path
            .components()
            .any(|component| !matches!(component, std::path::Component::Normal(_)))
    {
        return Err(FeatureCompileError::UnsafePath(relative.to_owned()));
    }
    Ok(root.join(path))
}

/// Resolves an app-owned feature template without permitting boundary escape.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::features::safe_feature_template_path`].
/// - `relative`: Input consumed by [`crate::features::safe_feature_template_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::features::safe_feature_template_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::features::safe_feature_template_path(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::features`] for adjacent helpers that share the same runtime surface.
pub fn safe_feature_template_path(root: &Path, relative: &str) -> Option<PathBuf> {
    let path = safe_artifact_path(root, relative).ok()?;
    (relative.starts_with("templates/") && path.is_file()).then_some(path)
}

/// Loads a required JSON object from an artifact-local file.
fn load_json_object(path: &Path) -> Result<Value, FeatureCompileError> {
    let text = fs::read_to_string(path)
        .map_err(|_| FeatureCompileError::Io(path.to_string_lossy().into_owned()))?;
    let value: Value = serde_json::from_str(&text)
        .map_err(|_| FeatureCompileError::InvalidDocument(path.to_string_lossy().into_owned()))?;
    if !value.is_object() {
        return Err(FeatureCompileError::InvalidDocument(
            path.to_string_lossy().into_owned(),
        ));
    }
    Ok(value)
}

/// Loads an existing lower-level contract or creates its empty canonical shape.
fn load_contract_or_empty(
    artifact_root: &Path,
    name: &str,
    array_key: &str,
) -> Result<Value, FeatureCompileError> {
    let path = artifact_root.join(format!("data/contracts/{name}.json"));
    if path.is_file() {
        return load_json_object(&path);
    }
    Ok(serde_json::json!({
        "contract_version": CONTRACT_VERSION,
        array_key: [],
    }))
}

/// Writes one generated JSON document inside the artifact boundary.
fn write_json(
    artifact_root: &Path,
    relative: &str,
    value: &Value,
) -> Result<(), FeatureCompileError> {
    let path = safe_artifact_path(artifact_root, relative)?;
    let parent = path
        .parent()
        .ok_or_else(|| FeatureCompileError::UnsafePath(relative.to_owned()))?;
    fs::create_dir_all(parent)
        .map_err(|_| FeatureCompileError::Io(parent.to_string_lossy().into_owned()))?;
    let encoded = serde_json::to_string_pretty(value)
        .map_err(|_| FeatureCompileError::InvalidDocument(relative.to_owned()))?;
    pharos_runtime_core::fs::write_file_within(artifact_root, &path, encoded.as_bytes(), 0o644)
        .map_err(|_| FeatureCompileError::Io(relative.to_owned()))
}

/// Collects sorted, non-symlinked feature source documents.
fn feature_paths(artifact_root: &Path) -> Result<Vec<PathBuf>, FeatureCompileError> {
    let directory = artifact_root.join("data/features");
    let mut paths = Vec::new();
    if directory.is_dir() {
        for entry in fs::read_dir(&directory)
            .map_err(|_| FeatureCompileError::Io(directory.to_string_lossy().into_owned()))?
        {
            let entry = entry
                .map_err(|_| FeatureCompileError::Io(directory.to_string_lossy().into_owned()))?;
            let path = entry.path();
            let metadata = fs::symlink_metadata(&path)
                .map_err(|_| FeatureCompileError::Io(path.to_string_lossy().into_owned()))?;
            if metadata.file_type().is_symlink() || metadata.is_dir() {
                return Err(FeatureCompileError::UnsafePath(
                    path.to_string_lossy().into_owned(),
                ));
            }
            if metadata.is_file()
                && path.extension().and_then(|value| value.to_str()) == Some("json")
            {
                paths.push(path);
            }
            if paths.len() > MAX_FEATURE_FILES {
                return Err(FeatureCompileError::InvalidDocument(
                    "too many feature files".to_owned(),
                ));
            }
        }
    }
    if paths.is_empty() {
        let contract_path = artifact_root.join("data/contracts/features.json");
        if contract_path.is_file() {
            let metadata = fs::symlink_metadata(&contract_path).map_err(|_| {
                FeatureCompileError::Io(contract_path.to_string_lossy().into_owned())
            })?;
            if metadata.file_type().is_symlink() || !metadata.is_file() {
                return Err(FeatureCompileError::UnsafePath(
                    contract_path.to_string_lossy().into_owned(),
                ));
            }
            paths.push(contract_path);
        }
    }
    paths.sort();
    Ok(paths)
}

fn feature_source_documents(
    path: &Path,
    document: Value,
) -> Result<Vec<Value>, FeatureCompileError> {
    if document.get("feature_id").and_then(Value::as_str).is_some() {
        return Ok(vec![document]);
    }
    if let Some(features) = document.get("features").and_then(Value::as_array) {
        if features.len() > MAX_FEATURE_FILES {
            return Err(FeatureCompileError::InvalidDocument(
                path.to_string_lossy().into_owned(),
            ));
        }
        return Ok(features.clone());
    }
    Err(FeatureCompileError::InvalidDocument(
        path.to_string_lossy().into_owned(),
    ))
}

/// Validates an HTTP route path without permitting queries, fragments, or controls.
fn route_path(value: &str) -> Result<String, FeatureCompileError> {
    if !value.starts_with('/')
        || value.len() > 512
        || value.contains(['?', '#', '\r', '\n', '\0'])
        || value.split('/').any(|segment| segment == "..")
    {
        return Err(FeatureCompileError::UnsafePath(value.to_owned()));
    }
    Ok(value.to_owned())
}

/// Resolves a bounded map from one optional declaration section.
fn declaration_map<'a>(
    feature: &'a Value,
    key: &str,
) -> Result<&'a Map<String, Value>, FeatureCompileError> {
    match feature.get(key) {
        None => {
            static EMPTY: std::sync::OnceLock<Map<String, Value>> = std::sync::OnceLock::new();
            Ok(EMPTY.get_or_init(Map::new))
        }
        Some(value) => value
            .as_object()
            .ok_or_else(|| FeatureCompileError::InvalidDocument(key.to_owned())),
    }
}

/// Returns one optional top-level bundle declaration map.
fn bundle_map(feature: &Value) -> Result<&Map<String, Value>, FeatureCompileError> {
    declaration_map(feature, "bundles")
}

/// Returns one required bundle object.
fn bundle_object<'a>(
    bundle_id: &str,
    bundle: &'a Value,
) -> Result<&'a Map<String, Value>, FeatureCompileError> {
    bundle
        .as_object()
        .ok_or_else(|| FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}")))
}

/// Returns one required nested declaration object within a bundle.
fn bundle_section<'a>(
    bundle_id: &str,
    bundle: &'a Map<String, Value>,
    section: &str,
) -> Result<&'a Map<String, Value>, FeatureCompileError> {
    bundle
        .get(section)
        .and_then(Value::as_object)
        .ok_or_else(|| {
            FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}.{section}"))
        })
}

/// Inserts one default scalar or array field when the declaration omitted it.
fn insert_default_field(object: &mut Map<String, Value>, key: &str, value: Option<Value>) {
    if !object.contains_key(key)
        && let Some(value) = value
    {
        object.insert(key.to_owned(), value);
    }
}

/// Inserts one default response field inside a declaration-owned response object.
fn insert_default_response_field(object: &mut Map<String, Value>, key: &str, value: Option<Value>) {
    if value.is_none() {
        return;
    }
    if !object.contains_key("response") {
        object.insert("response".to_owned(), Value::Object(Map::new()));
    }
    if let Some(response) = object.get_mut("response").and_then(Value::as_object_mut)
        && !response.contains_key(key)
        && let Some(value) = value
    {
        response.insert(key.to_owned(), value);
    }
}

/// Expands one bundle page declaration into an ordinary feature page contract.
fn expand_bundle_page(
    bundle_id: &str,
    role: &str,
    bundle: &Map<String, Value>,
) -> Result<(String, Value, Value), FeatureCompileError> {
    let mut page = bundle_section(bundle_id, bundle, role)?.clone();
    let page_id = declaration_id(
        page.get("page_id")
            .and_then(Value::as_str)
            .unwrap_or(&format!("{bundle_id}_{role}")),
    )?;
    insert_default_field(&mut page, "layout", bundle.get("layout").cloned());
    insert_default_field(&mut page, "policy", bundle.get("policy").cloned());
    insert_default_field(&mut page, "auth", bundle.get("auth").cloned());
    let page_queries = page
        .get("queries")
        .cloned()
        .or_else(|| Some(Value::Array(Vec::new())));
    insert_default_response_field(&mut page, "target", bundle.get("target").cloned());
    insert_default_response_field(&mut page, "history", bundle.get("history").cloned());
    insert_default_response_field(&mut page, "queries", page_queries);
    let summary = serde_json::json!({
        "role": role,
        "page_id": page_id,
        "route_id": page.get("route_id").and_then(Value::as_str).map(ToOwned::to_owned),
        "path": page.get("path").and_then(Value::as_str).map(ToOwned::to_owned),
        "target": page.get("response").and_then(|value| value.get("target")).and_then(Value::as_str).map(ToOwned::to_owned),
        "queries": page.get("response").and_then(|value| value.get("queries")).cloned().unwrap_or_else(|| Value::Array(Vec::new())),
    });
    Ok((page_id, Value::Object(page), summary))
}

/// Compiles one shorthand fragment response into the ordinary action response contract.
fn expand_bundle_action_response(
    bundle_id: &str,
    role: &str,
    bundle: &Map<String, Value>,
    action: &Map<String, Value>,
) -> Result<Value, FeatureCompileError> {
    if let Some(response) = action.get("response") {
        let mut response = response
            .as_object()
            .ok_or_else(|| {
                FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}.{role}.response"))
            })?
            .clone();
        insert_default_field(&mut response, "target", bundle.get("target").cloned());
        insert_default_field(
            &mut response,
            "fallback",
            bundle
                .get("fallback_redirect")
                .cloned()
                .map(|redirect| serde_json::json!({"redirect": redirect})),
        );
        return Ok(Value::Object(response));
    }
    let render = declaration_id(action.get("render").and_then(Value::as_str).ok_or_else(
        || FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}.{role}.render")),
    )?)?;
    let target = declaration_id(
        action
            .get("target")
            .and_then(Value::as_str)
            .or_else(|| bundle.get("target").and_then(Value::as_str))
            .ok_or_else(|| {
                FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}.{role}.target"))
            })?,
    )?;
    let fallback = route_path(
        action
            .get("fallback")
            .and_then(Value::as_str)
            .or_else(|| bundle.get("fallback_redirect").and_then(Value::as_str))
            .ok_or_else(|| {
                FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}.{role}.fallback"))
            })?,
    )?;
    let status = action
        .get("status")
        .cloned()
        .unwrap_or_else(|| Value::from(200));
    Ok(serde_json::json!({
        "render": render,
        "target": target,
        "queries": action.get("queries").cloned().unwrap_or_else(|| Value::Array(Vec::new())),
        "fallback": {"redirect": fallback},
        "status": status,
    }))
}

/// Expands one bundle action declaration into an ordinary feature action contract.
fn expand_bundle_action(
    bundle_id: &str,
    role: &str,
    bundle: &Map<String, Value>,
) -> Result<(String, Value, Value), FeatureCompileError> {
    let section = bundle_section(bundle_id, bundle, role)?;
    let mut action = section.clone();
    let action_id = declaration_id(
        action
            .get("action_id")
            .and_then(Value::as_str)
            .unwrap_or(&format!("{bundle_id}_{role}")),
    )?;
    insert_default_field(
        &mut action,
        "method",
        Some(Value::String("POST".to_owned())),
    );
    insert_default_field(&mut action, "policy", bundle.get("policy").cloned());
    if !action.contains_key("response") {
        action.insert(
            "response".to_owned(),
            expand_bundle_action_response(bundle_id, role, bundle, section)?,
        );
    } else if let Some(response) = action.get_mut("response").and_then(Value::as_object_mut) {
        insert_default_field(response, "target", bundle.get("target").cloned());
        insert_default_field(
            response,
            "fallback",
            bundle
                .get("fallback_redirect")
                .cloned()
                .map(|redirect| serde_json::json!({"redirect": redirect})),
        );
    }
    let summary = serde_json::json!({
        "role": role,
        "action_id": action_id,
        "route_id": action.get("route_id").and_then(Value::as_str).map(ToOwned::to_owned),
        "path": action.get("path").and_then(Value::as_str).map(ToOwned::to_owned),
        "method": action.get("method").and_then(Value::as_str).map(ToOwned::to_owned),
        "target": action.get("response").and_then(|value| value.get("target")).and_then(Value::as_str).map(ToOwned::to_owned),
        "queries": action.get("response").and_then(|value| value.get("queries")).cloned().unwrap_or_else(|| Value::Array(Vec::new())),
        "render": action.get("response").and_then(|value| value.get("render")).and_then(Value::as_str).map(ToOwned::to_owned),
        "fallback": action.get("response").and_then(|value| value.get("fallback")).and_then(|value| value.get("redirect")).and_then(Value::as_str).map(ToOwned::to_owned),
    });
    Ok((action_id, Value::Object(action), summary))
}

/// Expands one bundle family into ordinary pages and actions plus an inspectable summary.
type ExpandedFeatureBundles = (Map<String, Value>, Map<String, Value>, Vec<Value>);

/// Fully expanded pages/actions plus bundle provenance, shared by compilation and planning.
pub type ExpandedFeatureDeclarations = (Map<String, Value>, Map<String, Value>, Vec<Value>);

/// Resolves explicit declarations and bundles once, rejecting collisions in either namespace.
pub fn feature_pages_and_actions(
    feature_id: &str,
    feature: &Value,
) -> Result<ExpandedFeatureDeclarations, FeatureCompileError> {
    declaration_id(feature_id)?;
    let (bundle_pages, bundle_actions, summaries) = expand_feature_bundles(feature_id, feature)?;
    let mut pages = declaration_map(feature, "pages")?.clone();
    let mut actions = declaration_map(feature, "actions")?.clone();
    for (id, page) in bundle_pages {
        if pages.insert(id, page).is_some() {
            return Err(FeatureCompileError::DuplicateId(format!(
                "{feature_id}.pages"
            )));
        }
    }
    for (id, action) in bundle_actions {
        if actions.insert(id, action).is_some() {
            return Err(FeatureCompileError::DuplicateId(format!(
                "{feature_id}.actions"
            )));
        }
    }
    Ok((pages, actions, summaries))
}

/// Expands feature bundles.
fn expand_feature_bundles(
    feature_id: &str,
    feature: &Value,
) -> Result<ExpandedFeatureBundles, FeatureCompileError> {
    let mut pages = Map::new();
    let mut actions = Map::new();
    let mut bundles = Vec::new();
    for (bundle_id, bundle_value) in bundle_map(feature)? {
        let bundle_id = declaration_id(bundle_id)?;
        let bundle = bundle_object(&bundle_id, bundle_value)?;
        let kind = bundle.get("kind").and_then(Value::as_str).ok_or_else(|| {
            FeatureCompileError::InvalidDocument(format!("bundles.{bundle_id}.kind"))
        })?;
        let (page_roles, action_roles): (&[&str], &[&str]) = match kind {
            "list_detail" => (&["list", "detail"], &[]),
            "list_create" => (&["list"], &["create"]),
            "detail_edit" => (&["detail", "edit"], &["update"]),
            "crud" => (&["list", "detail", "edit"], &["create", "update"]),
            _ => {
                return Err(FeatureCompileError::InvalidDocument(format!(
                    "bundles.{bundle_id}.kind"
                )));
            }
        };
        let mut bundle_pages = Vec::new();
        let mut bundle_actions = Vec::new();
        for role in page_roles {
            let (page_id, page, summary) = expand_bundle_page(&bundle_id, role, bundle)?;
            if pages.insert(page_id.clone(), page).is_some() {
                return Err(FeatureCompileError::DuplicateId(page_id));
            }
            bundle_pages.push(summary);
        }
        for role in action_roles {
            let (action_id, action, summary) = expand_bundle_action(&bundle_id, role, bundle)?;
            if actions.insert(action_id.clone(), action).is_some() {
                return Err(FeatureCompileError::DuplicateId(action_id));
            }
            bundle_actions.push(summary);
        }
        bundles.push(serde_json::json!({
            "feature_id": feature_id,
            "bundle_id": bundle_id,
            "bundle_kind": kind,
            "target": bundle.get("target"),
            "history": bundle.get("history"),
            "fallback_redirect": bundle.get("fallback_redirect"),
            "pages": bundle_pages,
            "actions": bundle_actions,
        }));
    }
    Ok((pages, actions, bundles))
}

/// Validates that response query names exist in the owning feature.
fn validate_response_queries(
    feature_id: &str,
    queries: &Map<String, Value>,
    response: &Value,
) -> Result<(), FeatureCompileError> {
    if let Some(variants) = response.get("variants").and_then(Value::as_object) {
        if variants.is_empty() || variants.len() > 16 {
            return Err(FeatureCompileError::InvalidDocument(format!(
                "{feature_id}.response.variants"
            )));
        }
        for (variant_id, variant) in variants {
            declaration_id(variant_id)?;
            validate_response_queries(feature_id, queries, variant)?;
        }
        return Ok(());
    }
    for query in response
        .get("queries")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let query_id = query
            .as_str()
            .ok_or_else(|| FeatureCompileError::InvalidDocument(feature_id.to_owned()))?;
        declaration_id(query_id)?;
        if !queries.contains_key(query_id) {
            return Err(FeatureCompileError::MissingReference(format!(
                "{feature_id}:{query_id}"
            )));
        }
    }
    Ok(())
}

/// Finds a unique app-owned HTML template by its file stem.
fn find_template_by_stem(artifact_root: &Path, stem: &str) -> Result<PathBuf, FeatureCompileError> {
    declaration_id(stem)?;
    let templates = artifact_root.join("templates");
    let mut pending = vec![(templates, 0usize)];
    let mut visited = 0usize;
    let mut found = None;
    while let Some((directory, depth)) = pending.pop() {
        if depth > MAX_TEMPLATE_DEPTH {
            return Err(FeatureCompileError::InvalidDocument(
                "template depth exceeded".to_owned(),
            ));
        }
        let mut entries = fs::read_dir(&directory)
            .map_err(|_| FeatureCompileError::Io(directory.to_string_lossy().into_owned()))?
            .collect::<Result<Vec<_>, _>>()
            .map_err(|_| FeatureCompileError::Io(directory.to_string_lossy().into_owned()))?;
        entries.sort_by_key(|entry| entry.file_name());
        for entry in entries {
            let path = entry.path();
            let metadata = fs::symlink_metadata(&path)
                .map_err(|_| FeatureCompileError::Io(path.to_string_lossy().into_owned()))?;
            if metadata.file_type().is_symlink() {
                return Err(FeatureCompileError::UnsafePath(
                    path.to_string_lossy().into_owned(),
                ));
            }
            if metadata.is_dir() {
                pending.push((path, depth + 1));
                continue;
            }
            if !metadata.is_file() {
                continue;
            }
            visited += 1;
            if visited > MAX_TEMPLATE_FILES {
                return Err(FeatureCompileError::InvalidDocument(
                    "too many template files".to_owned(),
                ));
            }
            if path.extension().and_then(|value| value.to_str()) == Some("html")
                && path.file_stem().and_then(|value| value.to_str()) == Some(stem)
                && found.replace(path).is_some()
            {
                return Err(FeatureCompileError::DuplicateId(stem.to_owned()));
            }
        }
    }
    found.ok_or_else(|| FeatureCompileError::MissingReference(stem.to_owned()))
}

/// Adds one operation's closed entity effects to the owning transaction sets.
fn collect_transaction_effect(
    operation: &str,
    value: &Value,
    reads: &mut BTreeSet<String>,
    writes: &mut BTreeSet<String>,
) -> Result<(), FeatureCompileError> {
    let entity = value
        .get("entity")
        .and_then(Value::as_str)
        .map(declaration_id)
        .transpose()?;
    match operation {
        "require" | "select" | "bind_inserted" => {
            if let Some(entity) = entity {
                reads.insert(format!("entity:{entity}"));
            } else if value.get("query").and_then(Value::as_str).is_none() {
                return Err(FeatureCompileError::InvalidDocument(operation.to_owned()));
            }
        }
        "insert" | "insert_from" | "update" | "delete" | "upsert" | "allocate_sequence"
        | "reserve" | "confirm" | "release" => {
            let entity =
                entity.ok_or_else(|| FeatureCompileError::InvalidDocument(operation.to_owned()))?;
            reads.insert(format!("entity:{entity}"));
            writes.insert(format!("entity:{entity}"));
            if operation == "allocate_sequence" {
                let counter = value
                    .get("counter")
                    .and_then(Value::as_object)
                    .ok_or_else(|| {
                        FeatureCompileError::InvalidDocument("allocate_sequence.counter".to_owned())
                    })?;
                let counter_entity =
                    counter
                        .get("entity")
                        .and_then(Value::as_str)
                        .ok_or_else(|| {
                            FeatureCompileError::InvalidDocument("counter.entity".to_owned())
                        })?;
                let counter_entity = declaration_id(counter_entity)?;
                reads.insert(format!("entity:{counter_entity}"));
                writes.insert(format!("entity:{counter_entity}"));
                if let Some(seed) = counter.get("seed") {
                    let seed_entity =
                        seed.get("entity").and_then(Value::as_str).ok_or_else(|| {
                            FeatureCompileError::InvalidDocument("counter.seed.entity".to_owned())
                        })?;
                    reads.insert(format!("entity:{}", declaration_id(seed_entity)?));
                }
            }
        }
        "assert" | "values" | "idempotency" => {}
        _ => {
            return Err(FeatureCompileError::InvalidDocument(format!(
                "transaction.{operation}"
            )));
        }
    }
    Ok(())
}

/// Collects the statically declared read and write entity sets for one transaction.
fn transaction_effects(transaction: &Value) -> Result<Value, FeatureCompileError> {
    if let Some(variants) = transaction.get("variants").and_then(Value::as_object) {
        let selector = transaction
            .get("select")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureCompileError::InvalidDocument("transaction.select".to_owned()))?;
        let selector_field = selector
            .strip_prefix("input.")
            .ok_or_else(|| FeatureCompileError::InvalidDocument("transaction.select".to_owned()))?;
        declaration_id(selector_field)?;
        if variants.is_empty() || variants.len() > 16 {
            return Err(FeatureCompileError::InvalidDocument(
                "transaction.variants".to_owned(),
            ));
        }
        let mut reads = BTreeSet::new();
        let mut writes = BTreeSet::new();
        for (variant_id, variant) in variants {
            declaration_id(variant_id)?;
            let effects = transaction_effects(variant)?;
            for (key, output) in [("reads", &mut reads), ("writes", &mut writes)] {
                for effect in effects
                    .get(key)
                    .and_then(Value::as_array)
                    .into_iter()
                    .flatten()
                {
                    output.insert(
                        effect
                            .as_str()
                            .ok_or_else(|| {
                                FeatureCompileError::InvalidDocument(
                                    "transaction.effects".to_owned(),
                                )
                            })?
                            .to_owned(),
                    );
                }
            }
        }
        return Ok(serde_json::json!({"reads": reads, "writes": writes}));
    }
    let mut reads = BTreeSet::new();
    let mut writes = BTreeSet::new();
    let object = transaction
        .as_object()
        .ok_or_else(|| FeatureCompileError::InvalidDocument("transaction".to_owned()))?;
    if let Some(steps) = object.get("steps").and_then(Value::as_array) {
        if steps.is_empty() || steps.len() > 64 {
            return Err(FeatureCompileError::InvalidDocument(
                "transaction.steps".to_owned(),
            ));
        }
        for step in steps {
            let step = step.as_object().ok_or_else(|| {
                FeatureCompileError::InvalidDocument("transaction.step".to_owned())
            })?;
            if step.len() != 1 {
                return Err(FeatureCompileError::InvalidDocument(
                    "transaction.step".to_owned(),
                ));
            }
            let (operation, value) = step.iter().next().expect("one transaction step");
            collect_transaction_effect(operation, value, &mut reads, &mut writes)?;
        }
    } else {
        for (operation, value) in object {
            collect_transaction_effect(operation, value, &mut reads, &mut writes)?;
        }
    }
    Ok(serde_json::json!({
        "reads": reads,
        "writes": writes,
    }))
}

/// Compiles one concrete action response into its fragment contract.
fn compile_response_variant(
    artifact_root: &Path,
    feature_id: &str,
    action_id: &str,
    response: &Value,
    queries: &Map<String, Value>,
    inherited_target: Option<&str>,
) -> Result<Value, FeatureCompileError> {
    validate_response_queries(feature_id, queries, response)?;
    let status = response
        .get("status")
        .and_then(Value::as_u64)
        .unwrap_or(200);
    if !(200..=599).contains(&status) {
        return Err(FeatureCompileError::InvalidDocument(format!(
            "{action_id}.response.status"
        )));
    }
    if response.get("response_kind").and_then(Value::as_str) == Some("redirect") {
        let redirect = route_path(
            response
                .get("fallback")
                .and_then(|value| value.get("redirect"))
                .and_then(Value::as_str)
                .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.to_owned()))?,
        )?;
        return Ok(serde_json::json!({
            "response_kind": "redirect",
            "fallback": {"redirect": redirect},
            "status": status,
        }));
    }
    if response.get("response_kind").and_then(Value::as_str) == Some("json") {
        let surface = declaration_id(
            response
                .get("surface")
                .and_then(Value::as_str)
                .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.to_owned()))?,
        )?;
        let payload_query = declaration_id(
            response
                .get("payload_query")
                .and_then(Value::as_str)
                .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.to_owned()))?,
        )?;
        if !queries.contains_key(&payload_query) {
            return Err(FeatureCompileError::MissingReference(format!(
                "{feature_id}:{payload_query}"
            )));
        }
        let mut compiled = serde_json::json!({
            "response_kind": "json",
            "surface": surface,
            "payload_query": payload_query,
            "status": status,
        });
        if let Some(payload_query_before) =
            response.get("payload_query_before").and_then(Value::as_str)
        {
            let payload_query_before = declaration_id(payload_query_before)?;
            if !queries.contains_key(&payload_query_before) {
                return Err(FeatureCompileError::MissingReference(format!(
                    "{feature_id}:{payload_query_before}"
                )));
            }
            compiled["payload_query_before"] = Value::String(payload_query_before);
        }
        return Ok(compiled);
    }
    let render = declaration_id(
        response
            .get("render")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.to_owned()))?,
    )?;
    let fragment_path = find_template_by_stem(artifact_root, &render)?;
    let fragment_relative = fragment_path
        .strip_prefix(artifact_root)
        .map_err(|_| FeatureCompileError::UnsafePath(render.clone()))?
        .to_string_lossy()
        .into_owned();
    let target = declaration_id(
        response
            .get("target")
            .and_then(Value::as_str)
            .or(inherited_target)
            .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.to_owned()))?,
    )?;
    let fallback = route_path(
        response
            .get("fallback")
            .and_then(|value| value.get("redirect"))
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.to_owned()))?,
    )?;
    Ok(serde_json::json!({
        "response_kind": "fragment",
        "render": render,
        "template": fragment_relative,
        "target": target,
        "queries": response.get("queries").cloned().unwrap_or_else(|| Value::Array(Vec::new())),
        "fallback": {"redirect": fallback},
        "status": status,
    }))
}

/// Compiles a direct or validated-input-selected action response contract.
fn compile_action_response(
    artifact_root: &Path,
    feature_id: &str,
    action_id: &str,
    response: &Value,
    queries: &Map<String, Value>,
) -> Result<Value, FeatureCompileError> {
    let Some(variants) = response.get("variants").and_then(Value::as_object) else {
        return compile_response_variant(
            artifact_root,
            feature_id,
            action_id,
            response,
            queries,
            None,
        );
    };
    let selector = response
        .get("select")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureCompileError::InvalidDocument(format!("{action_id}.response")))?;
    let selector_field = selector
        .strip_prefix("input.")
        .ok_or_else(|| FeatureCompileError::InvalidDocument(format!("{action_id}.response")))?;
    declaration_id(selector_field)?;
    let target = declaration_id(
        response
            .get("target")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureCompileError::InvalidDocument(format!("{action_id}.response")))?,
    )?;
    if variants.is_empty() || variants.len() > 16 {
        return Err(FeatureCompileError::InvalidDocument(format!(
            "{action_id}.response.variants"
        )));
    }
    let mut compiled = Map::new();
    for (variant_id, variant) in variants {
        declaration_id(variant_id)?;
        compiled.insert(
            variant_id.clone(),
            compile_response_variant(
                artifact_root,
                feature_id,
                action_id,
                variant,
                queries,
                Some(&target),
            )?,
        );
    }
    Ok(serde_json::json!({
        "select": selector,
        "target": target,
        "variants": compiled,
    }))
}

/// Ensures every selected contract variant is reachable from one validated enum input.
fn validate_action_variants(
    action_id: &str,
    action: &Value,
    contract: &Value,
) -> Result<(), FeatureCompileError> {
    let Some(variants) = contract.get("variants").and_then(Value::as_object) else {
        return Ok(());
    };
    let selector = contract
        .get("select")
        .and_then(Value::as_str)
        .and_then(|value| value.strip_prefix("input."))
        .ok_or_else(|| FeatureCompileError::InvalidDocument(format!("{action_id}.select")))?;
    declaration_id(selector)?;
    let rules = action
        .get("input")
        .and_then(Value::as_object)
        .and_then(|fields| fields.get(selector))
        .ok_or_else(|| FeatureCompileError::MissingReference(format!("{action_id}:{selector}")))?;
    if rules.get("type").and_then(Value::as_str) != Some("enum") {
        return Err(FeatureCompileError::InvalidDocument(format!(
            "{action_id}.{selector}"
        )));
    }
    let values = rules
        .get("values")
        .and_then(Value::as_array)
        .ok_or_else(|| FeatureCompileError::InvalidDocument(format!("{action_id}.{selector}")))?;
    let declared = values
        .iter()
        .map(|value| {
            value
                .as_str()
                .ok_or_else(|| {
                    FeatureCompileError::InvalidDocument(format!("{action_id}.{selector}"))
                })
                .and_then(declaration_id)
        })
        .collect::<Result<BTreeSet<_>, _>>()?;
    let variant_ids = variants.keys().cloned().collect::<BTreeSet<_>>();
    if declared != variant_ids {
        return Err(FeatureCompileError::InvalidDocument(format!(
            "{action_id}.{selector}.variants"
        )));
    }
    Ok(())
}

/// Compiles one page declaration into a route and generated page specification.
fn compile_page(
    artifact_root: &Path,
    feature_id: &str,
    page_id: &str,
    page: &Value,
    queries: &Map<String, Value>,
) -> Result<(Value, Value), FeatureCompileError> {
    let page_id = declaration_id(page_id)?;
    let path = route_path(
        page.get("path")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureCompileError::InvalidDocument(page_id.clone()))?,
    )?;
    let template = page
        .get("template")
        .and_then(Value::as_str)
        .ok_or_else(|| FeatureCompileError::InvalidDocument(page_id.clone()))?;
    let template_path = safe_artifact_path(artifact_root, template)?;
    if !template.starts_with("templates/") || !template_path.is_file() {
        return Err(FeatureCompileError::MissingReference(template.to_owned()));
    }
    let policy = declaration_id(
        page.get("policy")
            .and_then(Value::as_str)
            .unwrap_or("public"),
    )?;
    let auth = page
        .get("auth")
        .and_then(Value::as_str)
        .unwrap_or(if policy == "public" {
            "anonymous_or_session"
        } else {
            "session_required"
        });
    let response = page
        .get("response")
        .cloned()
        .unwrap_or_else(|| serde_json::json!({}));
    validate_response_queries(feature_id, queries, &response)?;
    if let Some(target) = response.get("target").and_then(Value::as_str) {
        declaration_id(target)?;
    }
    let default_route_id = format!("{feature_id}_{page_id}");
    let route_id = declaration_id(
        page.get("route_id")
            .and_then(Value::as_str)
            .unwrap_or(&default_route_id),
    )?;
    let page_spec = serde_json::json!({
        "page_id": page_id,
        "title": page.get("title").and_then(Value::as_str).unwrap_or(&page_id),
        "layout_id": page.get("layout").and_then(Value::as_str).unwrap_or("default_shell"),
        "template_file": template,
        "template_role": "page_body",
        "feature_id": feature_id,
    });
    let route = serde_json::json!({
        "route_id": route_id,
        "path": path,
        "kind": "page",
        "method": "GET",
        "page_id": page_id,
        "layout_id": page_spec.get("layout_id").cloned().unwrap_or(Value::Null),
        "auth_gate": auth,
        "policy_gate": policy,
        "feature_id": feature_id,
        "feature_page": page_id,
        "queries": page.get("queries").cloned().unwrap_or_else(|| Value::Array(Vec::new())),
        "response_contract": response,
    });
    Ok((route, page_spec))
}

/// Compiles one action declaration into a route and lower-level action contract.
fn compile_action(
    artifact_root: &Path,
    feature_id: &str,
    action_id: &str,
    action: &Value,
    queries: &Map<String, Value>,
) -> Result<(Value, Value), FeatureCompileError> {
    let action_id = declaration_id(action_id)?;
    let path = route_path(
        action
            .get("path")
            .and_then(Value::as_str)
            .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.clone()))?,
    )?;
    let method = action
        .get("method")
        .and_then(Value::as_str)
        .unwrap_or("POST")
        .to_ascii_uppercase();
    if !matches!(method.as_str(), "POST" | "PUT" | "PATCH" | "DELETE") {
        return Err(FeatureCompileError::InvalidDocument(method));
    }
    let policy = declaration_id(
        action
            .get("policy")
            .and_then(Value::as_str)
            .unwrap_or("public"),
    )?;
    let response = action
        .get("response")
        .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.clone()))?;
    let transaction = action
        .get("transaction")
        .ok_or_else(|| FeatureCompileError::InvalidDocument(action_id.clone()))?;
    validate_action_variants(&action_id, action, transaction)?;
    validate_action_variants(&action_id, action, response)?;
    let compiled_response =
        compile_action_response(artifact_root, feature_id, &action_id, response, queries)?;
    let effects = transaction_effects(transaction)?;
    let default_route_id = format!("{feature_id}_{action_id}");
    let route_id = declaration_id(
        action
            .get("route_id")
            .and_then(Value::as_str)
            .unwrap_or(&default_route_id),
    )?;
    let route = serde_json::json!({
        "route_id": route_id,
        "path": path,
        "kind": "action",
        "method": method,
        "action_id": action_id,
        "auth_gate": if policy == "public" { "anonymous_or_session" } else { "session_required" },
        "policy_gate": policy,
        "feature_id": feature_id,
        "request_hooks": action
            .get("request_hooks")
            .cloned()
            .unwrap_or_else(|| Value::Array(Vec::new())),
    });
    let contract = serde_json::json!({
        "action_id": action_id,
        "policy_gate": policy,
        "feature_id": feature_id,
        "input_contract": {
            "inline_fields": action.get("input").cloned().unwrap_or_else(|| serde_json::json!({})),
            "reject_unknown": true,
        },
        "transaction_contract": transaction,
        "response_contract": compiled_response,
        "effect_contract": effects,
        "guard_contract": {
            "guards": action
                .get("guards")
                .cloned()
                .unwrap_or_else(|| Value::Array(Vec::new()))
        },
        "hook_contract": action
            .get("hook_contract")
            .cloned()
            .unwrap_or_else(|| serde_json::json!({})),
    });
    Ok((route, contract))
}

/// Rewrites stable Pharos form attributes into progressive native/HTMX attributes.
fn compile_form_attributes(
    html: &str,
    actions: &BTreeMap<String, (String, String, String)>,
    base_path: &str,
) -> Result<String, FeatureCompileError> {
    let mut output = html.to_owned();
    for (action_id, (method, path, _target)) in actions {
        let action_attribute = format!(" pharos-action=\"{action_id}\"");
        let method_lower = method.to_ascii_lowercase();
        let scoped_path = if base_path.is_empty() || base_path == "/" {
            path.clone()
        } else {
            format!("{}{}", base_path.trim_end_matches('/'), path)
        };
        let replacement = format!(
            " method=\"{method_lower}\" action=\"{scoped_path}\" data-pharos-action=\"{scoped_path}\""
        );
        output = output.replace(&action_attribute, &replacement);
    }
    output = compile_form_target_attributes(&output)?;
    if output.contains(" pharos-action=") || output.contains(" pharos-target=") {
        return Err(FeatureCompileError::MissingReference(
            "unresolved Pharos form attribute".to_owned(),
        ));
    }
    Ok(output)
}

/// Rewrites declared Pharos form targets after validating their target IDs.
fn compile_form_target_attributes(html: &str) -> Result<String, FeatureCompileError> {
    const MARKER: &str = " pharos-target=\"";
    let mut remaining = html;
    let mut output = String::with_capacity(html.len());
    while let Some(position) = remaining.find(MARKER) {
        output.push_str(&remaining[..position]);
        remaining = &remaining[position + MARKER.len()..];
        let Some(end) = remaining.find('"') else {
            return Err(FeatureCompileError::MissingReference(
                "unresolved Pharos form attribute".to_owned(),
            ));
        };
        let target = &remaining[..end];
        let target_id = declaration_id(target)?;
        output.push_str(" data-pharos-target=\"");
        output.push_str(&target_id);
        output.push('"');
        remaining = &remaining[end + 1..];
    }
    output.push_str(remaining);
    Ok(output)
}

/// Rewrites stable Pharos navigation attributes into framework client hooks.
fn compile_navigation_attributes(html: &str) -> Result<String, FeatureCompileError> {
    let mut output = html.to_owned();
    for (source, compiled) in [
        (" pharos-nav=\"", " data-pharos-nav=\""),
        (" pharos-get=\"", " data-pharos-get=\""),
    ] {
        output = output.replace(source, compiled);
    }
    for marker in ["data-pharos-nav=\"", "data-pharos-get=\""] {
        for suffix in output.split(marker).skip(1) {
            let target = suffix.split('"').next().unwrap_or_default();
            declaration_id(target)?;
        }
    }
    Ok(output)
}

/// Compiles Pharos form attributes in all app-owned artifact templates.
fn compile_template_tree(
    artifact_root: &Path,
    actions: &BTreeMap<String, (String, String, String)>,
) -> Result<(), FeatureCompileError> {
    let base_path = pharos_runtime_core::config::app_local_conf_path(artifact_root)
        .and_then(|path| pharos_runtime_core::config::dynamic_config_lookup_raw(&path, "base_path"))
        .filter(|value| value.starts_with('/') && !value.contains(['\r', '\n']))
        .unwrap_or_default();
    write_json_asset(
        artifact_root,
        "static/pharos/interaction-v1.js",
        INTERACTION_CLIENT.as_bytes(),
    )?;
    let interaction_version = Sha256::digest(INTERACTION_CLIENT.as_bytes())
        .iter()
        .take(8)
        .map(|byte| format!("{byte:02x}"))
        .collect::<String>();
    let templates = artifact_root.join("templates");
    let mut pending = vec![(templates, 0usize)];
    let mut visited = 0usize;
    while let Some((directory, depth)) = pending.pop() {
        if depth > MAX_TEMPLATE_DEPTH {
            return Err(FeatureCompileError::InvalidDocument(
                "template depth exceeded".to_owned(),
            ));
        }
        for entry in fs::read_dir(&directory)
            .map_err(|_| FeatureCompileError::Io(directory.to_string_lossy().into_owned()))?
        {
            let entry = entry
                .map_err(|_| FeatureCompileError::Io(directory.to_string_lossy().into_owned()))?;
            let path = entry.path();
            let metadata = fs::symlink_metadata(&path)
                .map_err(|_| FeatureCompileError::Io(path.to_string_lossy().into_owned()))?;
            if metadata.file_type().is_symlink() {
                return Err(FeatureCompileError::UnsafePath(
                    path.to_string_lossy().into_owned(),
                ));
            }
            if metadata.is_dir() {
                pending.push((path, depth + 1));
                continue;
            }
            if !metadata.is_file()
                || path.extension().and_then(|value| value.to_str()) != Some("html")
            {
                continue;
            }
            visited += 1;
            if visited > MAX_TEMPLATE_FILES {
                return Err(FeatureCompileError::InvalidDocument(
                    "too many template files".to_owned(),
                ));
            }
            let source = fs::read_to_string(&path)
                .map_err(|_| FeatureCompileError::Io(path.to_string_lossy().into_owned()))?;
            let mut compiled = compile_form_attributes(&source, actions, &base_path)?;
            compiled = compile_navigation_attributes(&compiled)?;
            if path
                .components()
                .any(|component| component.as_os_str() == "layout")
                && !compiled.contains("/static/pharos/interaction-v1.js")
                && let Some(position) = compiled.rfind("</body>")
            {
                let source = format!(
                    "{}/static/pharos/interaction-v1.js?v={interaction_version}",
                    base_path.trim_end_matches('/'),
                );
                compiled.insert_str(
                    position,
                    &format!("  <script src=\"{source}\" defer></script>\n"),
                );
            }
            if compiled != source {
                pharos_runtime_core::fs::write_file_within(
                    artifact_root,
                    &path,
                    compiled.as_bytes(),
                    0o644,
                )
                .map_err(|_| FeatureCompileError::Io(path.to_string_lossy().into_owned()))?;
            }
        }
    }
    Ok(())
}

/// Writes one framework-owned browser asset inside the built artifact.
fn write_json_asset(
    artifact_root: &Path,
    relative: &str,
    bytes: &[u8],
) -> Result<(), FeatureCompileError> {
    let path = safe_artifact_path(artifact_root, relative)?;
    let parent = path
        .parent()
        .ok_or_else(|| FeatureCompileError::UnsafePath(relative.to_owned()))?;
    fs::create_dir_all(parent)
        .map_err(|_| FeatureCompileError::Io(parent.to_string_lossy().into_owned()))?;
    pharos_runtime_core::fs::write_file_within(artifact_root, &path, bytes, 0o644)
        .map_err(|_| FeatureCompileError::Io(relative.to_owned()))
}

/// Compiles coherent feature sources into validated runtime contracts.
///
/// # Parameters
///
/// - `artifact_root`: Input consumed by [`crate::features::compile_feature_sources`].
///
/// # Returns
///
/// Returns the successful value produced by [`crate::features::compile_feature_sources`] or an error when the operation fails.
///
/// # Errors
///
/// Returns an error value when [`crate::features::compile_feature_sources`] cannot complete successfully.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::features::compile_feature_sources`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::features::compile_feature_sources(todo!());
/// ```
///
/// # Related
///
/// - [`crate::features`] for adjacent helpers that share the same runtime surface.
pub fn compile_feature_sources(artifact_root: &Path) -> Result<usize, FeatureCompileError> {
    let paths = feature_paths(artifact_root)?;
    write_json_asset(
        artifact_root,
        "static/pharos/editable-grouping-v1.css",
        include_bytes!("../assets/editable-grouping-v1.css"),
    )?;
    if paths.is_empty() {
        return Ok(0);
    }
    let mut routes = load_contract_or_empty(artifact_root, "routes", "routes")?;
    let mut actions = load_contract_or_empty(artifact_root, "actions", "actions")?;
    let route_rows = routes
        .get_mut("routes")
        .and_then(Value::as_array_mut)
        .ok_or_else(|| FeatureCompileError::InvalidDocument("routes".to_owned()))?;
    let action_rows = actions
        .get_mut("actions")
        .and_then(Value::as_array_mut)
        .ok_or_else(|| FeatureCompileError::InvalidDocument("actions".to_owned()))?;
    let mut route_ids = route_rows
        .iter()
        .filter_map(|row| row.get("route_id").and_then(Value::as_str))
        .map(ToOwned::to_owned)
        .collect::<BTreeSet<_>>();
    let mut action_ids = action_rows
        .iter()
        .filter_map(|row| row.get("action_id").and_then(Value::as_str))
        .map(ToOwned::to_owned)
        .collect::<BTreeSet<_>>();
    let mut feature_ids = BTreeSet::new();
    let mut compiled_features = Vec::new();
    let mut compiled_bundles = Vec::new();
    let mut form_actions = BTreeMap::new();
    let mut protected_assets = Vec::new();

    for route in route_rows.iter() {
        let Some(action_id) = route.get("action_id").and_then(Value::as_str) else {
            continue;
        };
        let method = route
            .get("method")
            .and_then(Value::as_str)
            .unwrap_or("POST")
            .to_owned();
        let path = route
            .get("path")
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_owned();
        form_actions.insert(action_id.to_owned(), (method, path, String::new()));
    }

    for path in paths {
        let feature_documents = feature_source_documents(&path, load_json_object(&path)?)?;
        for feature in feature_documents {
            if feature.get("contract_version").and_then(Value::as_str) != Some(CONTRACT_VERSION) {
                return Err(FeatureCompileError::InvalidDocument(
                    path.to_string_lossy().into_owned(),
                ));
            }
            let feature_id = declaration_id(
                feature
                    .get("feature_id")
                    .and_then(Value::as_str)
                    .ok_or_else(|| {
                        FeatureCompileError::InvalidDocument(path.to_string_lossy().into_owned())
                    })?,
            )?;
            if !feature_ids.insert(feature_id.clone()) {
                return Err(FeatureCompileError::DuplicateId(feature_id));
            }
            let queries = declaration_map(&feature, "queries")?;
            for query_id in queries.keys() {
                declaration_id(query_id)?;
            }
            let (pages, feature_actions, bundle_summaries) =
                feature_pages_and_actions(&feature_id, &feature)?;
            compiled_bundles.extend(bundle_summaries);
            for (page_id, page) in &pages {
                let (route, page_spec) =
                    compile_page(artifact_root, &feature_id, page_id, page, queries)?;
                let route_id = route
                    .get("route_id")
                    .and_then(Value::as_str)
                    .unwrap_or_default();
                if !route_ids.insert(route_id.to_owned()) {
                    return Err(FeatureCompileError::DuplicateId(route_id.to_owned()));
                }
                let page_id = page_spec
                    .get("page_id")
                    .and_then(Value::as_str)
                    .unwrap_or_default();
                write_json(
                    artifact_root,
                    &format!("templates/.pharos-generated/{page_id}.page.json"),
                    &page_spec,
                )?;
                route_rows.push(route);
            }
            for (action_id, action) in &feature_actions {
                let (route, contract) =
                    compile_action(artifact_root, &feature_id, action_id, action, queries)?;
                if !action_ids.insert(action_id.to_owned()) {
                    return Err(FeatureCompileError::DuplicateId(action_id.to_owned()));
                }
                let route_enabled = action.get("route").and_then(Value::as_bool).unwrap_or(true);
                if route_enabled {
                    let route_id = route
                        .get("route_id")
                        .and_then(Value::as_str)
                        .unwrap_or_default();
                    if !route_ids.insert(route_id.to_owned()) {
                        return Err(FeatureCompileError::DuplicateId(route_id.to_owned()));
                    }
                    let method = route
                        .get("method")
                        .and_then(Value::as_str)
                        .unwrap_or("POST")
                        .to_owned();
                    let path = route
                        .get("path")
                        .and_then(Value::as_str)
                        .unwrap_or_default()
                        .to_owned();
                    let target = contract
                        .get("response_contract")
                        .and_then(|value| value.get("target"))
                        .and_then(Value::as_str)
                        .unwrap_or_default()
                        .to_owned();
                    form_actions.insert(action_id.to_owned(), (method, path, target));
                    route_rows.push(route);
                }
                action_rows.push(contract);
            }
            for (asset_id, declaration) in declaration_map(&feature, "protected_assets")? {
                let asset_id = declaration_id(asset_id)?;
                let path = route_path(
                    declaration
                        .get("path")
                        .and_then(Value::as_str)
                        .ok_or_else(|| FeatureCompileError::InvalidDocument(asset_id.clone()))?,
                )?;
                for field in ["entity", "key_field", "owner_field", "asset_field"] {
                    declaration_id(
                        declaration
                            .get(field)
                            .and_then(Value::as_str)
                            .ok_or_else(|| {
                                FeatureCompileError::InvalidDocument(asset_id.clone())
                            })?,
                    )?;
                }
                let root = declaration
                    .get("root")
                    .and_then(Value::as_str)
                    .ok_or_else(|| FeatureCompileError::InvalidDocument(asset_id.clone()))?;
                let root_path = safe_artifact_path(artifact_root, root)?;
                if !root.starts_with("private/") || !root_path.is_dir() {
                    return Err(FeatureCompileError::UnsafePath(root.to_owned()));
                }
                if let Some(on_authorized) = declaration.get("on_authorized") {
                    transaction_effects(on_authorized)?;
                }
                protected_assets.push(serde_json::json!({
                    "asset_id": asset_id,
                    "feature_id": feature_id,
                    "path": path,
                    "entity": declaration.get("entity"),
                    "key_field": declaration.get("key_field"),
                    "owner_field": declaration.get("owner_field"),
                    "asset_field": declaration.get("asset_field"),
                    "root": root,
                    "on_authorized": declaration.get("on_authorized"),
                }));
            }
            compiled_features.push(feature);
        }
    }

    if !action_rows.is_empty() {
        actions["effect_policy"] = serde_json::json!({"deny_undeclared": true});
    }
    write_json(artifact_root, "data/contracts/routes.json", &routes)?;
    write_json(artifact_root, "data/contracts/actions.json", &actions)?;
    write_json(
        artifact_root,
        "data/contracts/features.json",
        &serde_json::json!({
            "contract_version": CONTRACT_VERSION,
            "features": compiled_features,
        }),
    )?;
    if !compiled_bundles.is_empty() {
        write_json(
            artifact_root,
            "data/contracts/feature-bundles.json",
            &serde_json::json!({
                "contract_version": CONTRACT_VERSION,
                "bundles": compiled_bundles,
            }),
        )?;
    }
    if !protected_assets.is_empty() {
        write_json(
            artifact_root,
            "data/contracts/protected-assets.json",
            &serde_json::json!({
                "contract_version": CONTRACT_VERSION,
                "assets": protected_assets,
            }),
        )?;
    }
    compile_template_tree(artifact_root, &form_actions)?;
    Ok(compiled_features.len())
}

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

    use super::{compile_feature_sources, compile_form_attributes};

    /// Creates one unique test root without introducing another test dependency.
    fn test_root(label: &str) -> std::path::PathBuf {
        let nonce = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        std::env::temp_dir().join(format!(
            "pharos-feature-{label}-{}-{nonce}",
            std::process::id()
        ))
    }

    /// Writes one fixture file and all required parent directories.
    fn write(root: &std::path::Path, relative: &str, content: &str) {
        let path = root.join(relative);
        std::fs::create_dir_all(path.parent().expect("parent")).expect("directories");
        std::fs::write(path, content).expect("fixture");
    }

    #[test]
    /// Performs compiles one feature into routes actions pages and forms.
    fn compiles_one_feature_into_routes_actions_pages_and_forms() {
        let root = test_root("compile");
        write(
            &root,
            "data/contracts/routes.json",
            r#"{"contract_version":"1.0","security_defaults":{"csrf_mode":"mutation_required","trusted_origin_policy":"mutation_required","tenant_scope":"policy_bound","rate_limit_policy":"runtime_default","capability_policy":"policy_gate"},"routes":[{"route_id":"account_login_submit","path":"/accounts/login/","kind":"action","method":"POST","action_id":"login","auth_gate":"anonymous_or_session","policy_gate":"account_login"}]}"#,
        );
        write(
            &root,
            "data/contracts/actions.json",
            r#"{"contract_version":"1.0","actions":[{"action_id":"login","policy_gate":"account_login"}]}"#,
        );
        write(
            &root,
            "templates/storefront.body.html",
            r#"<a href="/cart" pharos-nav="app-main">Cart</a><form method="get" action="/" pharos-get="app-main"><button>Filter</button></form><form pharos-action="login"><button>Log in</button></form><form pharos-action="add_item" pharos-target="cart-panel"><button>Add</button></form>"#,
        );
        write(
            &root,
            "templates/fragments/cart_summary.html",
            r#"<aside id="cart-panel">{cart_total}</aside>"#,
        );
        write(
            &root,
            "data/features/cart.json",
            r#"{
              "contract_version":"1.0",
              "feature_id":"cart",
              "queries":{"current_cart":{"entity":"shopping_cart","result":"one"}},
              "bundles":{
                "cart_flow":{
                  "kind":"list_create",
                  "policy":"buy",
                  "target":"cart-panel",
                  "fallback_redirect":"/",
                  "list":{
                    "page_id":"storefront",
                    "path":"/",
                    "template":"templates/storefront.body.html",
                    "title":"Store",
                    "queries":["current_cart"],
                    "response":{"target":"app-main","history":"push","queries":["current_cart"]}
                  },
                  "create":{
                    "action_id":"add_item",
                    "path":"/cart/items",
                    "method":"POST",
                    "input":{"product_id":{"type":"integer","required":true}},
                    "transaction":{"upsert":{"entity":"shopping_cart_item","unique_by":["cart_id","product_id"],"values":{"product_id":"input.product_id"}}},
                    "render":"cart_summary",
                    "queries":["current_cart"]
                  }
                }
              }
            }"#,
        );

        assert_eq!(compile_feature_sources(&root), Ok(1));
        let routes =
            std::fs::read_to_string(root.join("data/contracts/routes.json")).expect("routes");
        let actions =
            std::fs::read_to_string(root.join("data/contracts/actions.json")).expect("actions");
        let bundles = std::fs::read_to_string(root.join("data/contracts/feature-bundles.json"))
            .expect("bundle ledger");
        let template =
            std::fs::read_to_string(root.join("templates/storefront.body.html")).expect("template");
        assert!(routes.contains("cart_add_item"));
        assert!(actions.contains("transaction_contract"));
        assert!(bundles.contains("\"bundle_id\": \"cart_flow\""));
        assert!(bundles.contains("\"action_id\": \"add_item\""));
        assert!(bundles.contains("\"target\": \"cart-panel\""));
        assert!(template.contains("action=\"/accounts/login/\""));
        assert!(template.contains("data-pharos-action=\"/cart/items\""));
        assert!(template.contains("data-pharos-target=\"cart-panel\""));
        assert!(template.contains("data-pharos-nav=\"app-main\""));
        assert!(template.contains("data-pharos-get=\"app-main\""));
        let interaction_client =
            std::fs::read_to_string(root.join("static/pharos/interaction-v1.js"))
                .expect("interaction client");
        assert!(interaction_client.contains("response.headers.get(\"HX-Redirect\")"));
        assert!(interaction_client.contains("location.assign(hxRedirect)"));
        assert!(
            root.join("templates/.pharos-generated/storefront.page.json")
                .is_file()
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Performs rewrites safe form targets even when the route map lacks target metadata.
    fn rewrites_safe_form_targets_independently_from_action_targets() {
        let mut actions = std::collections::BTreeMap::new();
        actions.insert(
            "add_item".to_owned(),
            ("POST".to_owned(), "/items".to_owned(), String::new()),
        );
        let template = compile_form_attributes(
            r#"<form pharos-action="add_item" pharos-target="item-panel"><button>Add</button></form>"#,
            &actions,
            "",
        )
        .expect("compiled form");

        assert!(template.contains(r#"data-pharos-action="/items""#));
        assert!(template.contains(r#"data-pharos-target="item-panel""#));
        assert!(!template.contains(" pharos-target="));
    }

    #[test]
    /// Performs rejects unresolved fragment targets.
    fn rejects_unresolved_fragment_targets() {
        let root = test_root("missing-fragment");
        write(
            &root,
            "data/contracts/routes.json",
            r#"{"contract_version":"1.0","routes":[]}"#,
        );
        write(&root, "templates/storefront.body.html", "<main></main>");
        write(
            &root,
            "data/features/cart.json",
            r#"{"contract_version":"1.0","feature_id":"cart","queries":{},"actions":{"add_item":{"path":"/cart/items","method":"POST","transaction":{"insert":{"entity":"item","values":{}}},"response":{"render":"missing","target":"cart","queries":[],"fallback":{"redirect":"/"}}}}}"#,
        );
        assert!(compile_feature_sources(&root).is_err());
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Accepts a declared redirect for a mutation that has no fragment response.
    fn compiles_redirect_action_response() {
        let compiled = super::compile_action_response(
            std::path::Path::new("."),
            "business",
            "create_service",
            &serde_json::json!({
                "response_kind": "redirect",
                "fallback": {"redirect": "/businesses/"}
            }),
            &serde_json::Map::new(),
        )
        .expect("compile app-owned redirect");
        assert_eq!(compiled["response_kind"], "redirect");
        assert_eq!(compiled["fallback"]["redirect"], "/businesses/");
    }

    #[test]
    /// Performs expands crud bundle with deterministic ids and overrides.
    fn expands_crud_bundle_with_deterministic_ids_and_overrides() {
        let root = test_root("crud-bundle");
        write(
            &root,
            "data/contracts/routes.json",
            r#"{"contract_version":"1.0","routes":[]}"#,
        );
        write(&root, "templates/tasks.body.html", "<main></main>");
        write(&root, "templates/task.body.html", "<main></main>");
        write(&root, "templates/task-edit.body.html", "<main></main>");
        write(
            &root,
            "templates/fragments/task_list.html",
            r#"<section id="task-panel"></section>"#,
        );
        write(
            &root,
            "data/features/tasks.json",
            r#"{
              "contract_version":"1.0",
              "feature_id":"tasks",
              "queries":{"task_list":{"entity":"task","result":"many"}},
              "bundles":{
                "task_flow":{
                  "kind":"crud",
                  "layout":"default_shell",
                  "policy":"public",
                  "target":"task-panel",
                  "fallback_redirect":"/tasks",
                  "list":{"path":"/tasks","template":"templates/tasks.body.html","title":"Tasks","queries":["task_list"]},
                  "detail":{"path":"/tasks/:task_id","template":"templates/task.body.html","title":"Task detail"},
                  "edit":{"path":"/tasks/:task_id/edit","template":"templates/task-edit.body.html","title":"Edit task"},
                  "create":{
                    "path":"/tasks",
                    "input":{"title":{"type":"string","required":true}},
                    "transaction":{"insert":{"entity":"task","values":{"title":"input.title"}}},
                    "render":"task_list",
                    "queries":["task_list"]
                  },
                  "update":{
                    "action_id":"save_task",
                    "path":"/tasks/:task_id",
                    "method":"PATCH",
                    "input":{"title":{"type":"string","required":true}},
                    "transaction":{"update":{"entity":"task","filters":{"id":"path.task_id"},"values":{"title":"input.title"}}},
                    "response":{"render":"task_list","target":"task-panel","queries":["task_list"],"fallback":{"redirect":"/tasks"}}
                  }
                }
              }
            }"#,
        );
        assert_eq!(compile_feature_sources(&root), Ok(1));
        let routes =
            std::fs::read_to_string(root.join("data/contracts/routes.json")).expect("routes");
        let actions =
            std::fs::read_to_string(root.join("data/contracts/actions.json")).expect("actions");
        let bundles = std::fs::read_to_string(root.join("data/contracts/feature-bundles.json"))
            .expect("bundles");
        assert!(routes.contains("\"route_id\": \"tasks_task_flow_list\""));
        assert!(routes.contains("\"route_id\": \"tasks_task_flow_detail\""));
        assert!(routes.contains("\"route_id\": \"tasks_task_flow_edit\""));
        assert!(routes.contains("\"route_id\": \"tasks_save_task\""));
        assert!(actions.contains("\"action_id\": \"task_flow_create\""));
        assert!(actions.contains("\"action_id\": \"save_task\""));
        assert!(bundles.contains("\"bundle_kind\": \"crud\""));
        assert!(bundles.contains("\"page_id\": \"task_flow_list\""));
        assert!(bundles.contains("\"action_id\": \"save_task\""));
        std::fs::remove_dir_all(root).expect("cleanup");
    }
}