nah_core.h

Go to the documentation of this file.

/*
 * NAH Core - Header-Only Library
 * SPDX-License-Identifier: MIT
 *
 * ============================================================================
 * WHAT IS NAH?
 * ============================================================================
 *
 * NAH answers a simple question: "How should I launch this application?"
 *
 * When you install an app that needs Python 3.11, or Node 20, or Lua 5.4,
 * something has to figure out: which binary to run, what environment variables
 * to set, which library paths to include, and what permissions are required.
 *
 * NAH takes four inputs and produces one output:
 *
 *   +-------------------+
 *   |  AppDeclaration   |---+   What the app says it needs
 *   +-------------------+   |
 *   +-------------------+   |
 *   |  HostEnvironment  |---+--> nah_compose() --> LaunchContract
 *   +-------------------+   |                      (everything needed to run)
 *   +-------------------+   |
 *   |   InstallRecord   |---+   Where the app is installed
 *   +-------------------+   |
 *   +-------------------+   |
 *   | RuntimeInventory  |---+   Available runtimes (Python, Node, etc.)
 *   +-------------------+
 *
 * The result is a LaunchContract: a complete, self-contained specification
 * that tells you exactly how to run the application.
 *
 * ============================================================================
 * QUICK START
 * ============================================================================
 *
 * 1. Include the header (no linking required):
 *
 *      #include "nah/nah_core.h"
 *      using namespace nah::core;
 *
 * 2. Prepare your inputs:
 *
 *      AppDeclaration app;
 *      app.id = "com.example.myapp";
 *      app.version = "1.0.0";
 *      app.entrypoint_path = "main.lua";
 *      app.nak_id = "lua";
 *      app.nak_version_req = ">=5.4.0";
 *
 *      InstallRecord install;
 *      install.install.instance_id = "abc123";
 *      install.paths.install_root = "/apps/myapp";
 *      install.nak.record_ref = "lua@5.4.6.json";
 *
 *      HostEnvironment host_env;  // Empty = no host overrides
 *      RuntimeInventory inventory;
 *      inventory.runtimes["lua@5.4.6.json"] = your_lua_runtime;
 *
 * 3. Compose and use the contract:
 *
 *      CompositionResult result = nah_compose(app, host_env, install, inventory);
 *      if (result.ok) {
 *          // result.contract.execution.binary  -> "/runtimes/lua/bin/lua"
 *          // result.contract.execution.arguments -> ["/apps/myapp/main.lua"]
 *          // result.contract.environment -> {"LUA_PATH": "...", ...}
 *          exec(result.contract);  // Your execution logic
 *      }
 *
 * For file-based usage with JSON parsing, see nah.h which adds nah_json.h,
 * nah_fs.h, and nah_exec.h on top of this pure core.
 *
 * ============================================================================
 * KEY TYPES
 * ============================================================================
 *
 * Inputs:
 *   AppDeclaration   - What the app needs (id, version, entrypoint, runtime)
 *   HostEnvironment  - Host-provided environment variables
 *   InstallRecord    - Where the app lives and which runtime version to use
 *   RuntimeInventory - Available runtimes on this host
 *
 * Output:
 *   LaunchContract   - Complete exec specification (binary, args, env, cwd)
 *
 * Each type has inline documentation with usage examples.
 */
 
#ifndef NAH_CORE_H
#define NAH_CORE_H
 
#ifdef __cplusplus
 
#include <algorithm>
#include <cstdint>
#include <optional>
#include <sstream>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace nah {
namespace core {
 
// ============================================================================
// VERSION AND CONSTANTS
// ============================================================================
 
constexpr const char* NAH_CORE_VERSION = "2.0.0";
constexpr int NAH_CORE_VERSION_MAJOR = 2;
constexpr int NAH_CORE_VERSION_MINOR = 0;
constexpr int NAH_CORE_VERSION_PATCH = 0;
 
constexpr const char* NAH_CONTRACT_SCHEMA = "nah.launch.contract.v2";
 
constexpr size_t MAX_EXPANDED_SIZE = 64 * 1024;
 
constexpr size_t MAX_PLACEHOLDERS = 128;
 
constexpr size_t MAX_ENV_VARS = 1024;
 
constexpr size_t MAX_LIBRARY_PATHS = 256;
 
constexpr size_t MAX_ARGUMENTS = 1024;
 
// ============================================================================
// ENVIRONMENT OPERATIONS
// ============================================================================
 
enum class EnvOp {
    Set,      
    Prepend,  
    Append,   
    Unset     
};
 
inline const char* env_op_to_string(EnvOp op) {
    switch (op) {
        case EnvOp::Set: return "set";
        case EnvOp::Prepend: return "prepend";
        case EnvOp::Append: return "append";
        case EnvOp::Unset: return "unset";
    }
    return "set";
}
 
inline std::optional<EnvOp> parse_env_op(const std::string& s) {
    if (s == "set") return EnvOp::Set;
    if (s == "prepend") return EnvOp::Prepend;
    if (s == "append") return EnvOp::Append;
    if (s == "unset") return EnvOp::Unset;
    return std::nullopt;
}
 
struct EnvValue {
    EnvOp op = EnvOp::Set;
    std::string value;
    std::string separator = ":";
 
    EnvValue() = default;
    EnvValue(const char* v) : op(EnvOp::Set), value(v) {}
    EnvValue(const std::string& v) : op(EnvOp::Set), value(v) {}
    EnvValue(EnvOp o, const std::string& v, const std::string& sep = ":")
        : op(o), value(v), separator(sep) {}
 
    bool is_simple() const { return op == EnvOp::Set; }
 
    // Comparison operators
    bool operator==(const std::string& other) const { return value == other; }
    bool operator==(const char* other) const { return value == other; }
    bool operator==(const EnvValue& other) const {
        return op == other.op && value == other.value && separator == other.separator;
    }
    bool operator!=(const EnvValue& other) const { return !(*this == other); }
};
 
using EnvMap = std::unordered_map<std::string, EnvValue>;
 
// ============================================================================
// TRUST STATE
// ============================================================================
 
enum class TrustState {
    Verified,
    Unverified,
    Failed,
    Unknown
};
 
inline const char* trust_state_to_string(TrustState s) {
    switch (s) {
        case TrustState::Verified: return "verified";
        case TrustState::Unverified: return "unverified";
        case TrustState::Failed: return "failed";
        case TrustState::Unknown: return "unknown";
    }
    return "unknown";
}
 
inline std::optional<TrustState> parse_trust_state(const std::string& s) {
    if (s == "verified") return TrustState::Verified;
    if (s == "unverified") return TrustState::Unverified;
    if (s == "failed") return TrustState::Failed;
    if (s == "unknown") return TrustState::Unknown;
    return std::nullopt;
}
 
struct TrustInfo {
    TrustState state = TrustState::Unknown;
    std::string source;          
    std::string evaluated_at;    
    std::string expires_at;      
    std::string inputs_hash;     
    std::unordered_map<std::string, std::string> details;  
};
 
// ============================================================================
// WARNING SYSTEM
// ============================================================================
 
enum class Warning {
    trust_state_unknown,
    trust_state_unverified,
    trust_state_failed,
    trust_state_stale,
};
 
inline const char* warning_to_string(Warning w) {
    switch (w) {
        case Warning::trust_state_unknown: return "trust_state_unknown";
        case Warning::trust_state_unverified: return "trust_state_unverified";
        case Warning::trust_state_failed: return "trust_state_failed";
        case Warning::trust_state_stale: return "trust_state_stale";
    }
    return "unknown";
}
 
struct WarningObject {
    std::string key;     
    std::unordered_map<std::string, std::string> fields;  
 
    bool operator==(const WarningObject& other) const {
        return key == other.key && fields == other.fields;
    }
};
 
// ============================================================================
// CRITICAL ERRORS
// ============================================================================
 
enum class CriticalError {
    MANIFEST_MISSING,        
    ENTRYPOINT_NOT_FOUND,    
    PATH_TRAVERSAL,          
    EXPANSION_FAILED,        
    HOST_CONFIG_INVALID,     
    INSTALL_RECORD_INVALID,  
    NAK_NOT_FOUND,           
    NAK_LOADER_INVALID,      
};
 
inline const char* critical_error_to_string(CriticalError e) {
    switch (e) {
        case CriticalError::MANIFEST_MISSING: return "MANIFEST_MISSING";
        case CriticalError::ENTRYPOINT_NOT_FOUND: return "ENTRYPOINT_NOT_FOUND";
        case CriticalError::PATH_TRAVERSAL: return "PATH_TRAVERSAL";
        case CriticalError::EXPANSION_FAILED: return "EXPANSION_FAILED";
        case CriticalError::HOST_CONFIG_INVALID: return "HOST_CONFIG_INVALID";
        case CriticalError::INSTALL_RECORD_INVALID: return "INSTALL_RECORD_INVALID";
        case CriticalError::NAK_NOT_FOUND: return "NAK_NOT_FOUND";
        case CriticalError::NAK_LOADER_INVALID: return "NAK_LOADER_INVALID";
    }
    return "UNKNOWN";
}
 
inline std::optional<CriticalError> parse_critical_error(const std::string& s) {
    if (s == "MANIFEST_MISSING") return CriticalError::MANIFEST_MISSING;
    if (s == "ENTRYPOINT_NOT_FOUND") return CriticalError::ENTRYPOINT_NOT_FOUND;
    if (s == "PATH_TRAVERSAL") return CriticalError::PATH_TRAVERSAL;
    if (s == "EXPANSION_FAILED") return CriticalError::EXPANSION_FAILED;
    if (s == "HOST_CONFIG_INVALID") return CriticalError::HOST_CONFIG_INVALID;
    if (s == "INSTALL_RECORD_INVALID") return CriticalError::INSTALL_RECORD_INVALID;
    if (s == "NAK_NOT_FOUND") return CriticalError::NAK_NOT_FOUND;
    if (s == "NAK_LOADER_INVALID") return CriticalError::NAK_LOADER_INVALID;
    return std::nullopt;
}
 
// ============================================================================
// TRACE SYSTEM
// ============================================================================
 
namespace trace_source {
    constexpr const char* HOST = "host";
    constexpr const char* NAK_RECORD = "nak_record";
    constexpr const char* MANIFEST = "manifest";
    constexpr const char* INSTALL_RECORD = "install_record";
    constexpr const char* NAH_STANDARD = "nah_standard";
}
 
struct TraceContribution {
    std::string value;           
    std::string source_kind;     
    std::string source_path;     
    int precedence_rank = 0;     
    EnvOp operation = EnvOp::Set;
    bool accepted = false;       
};
 
struct TraceEntry {
    std::string value;           
    std::string source_kind;     
    std::string source_path;     
    int precedence_rank = 0;     
    std::vector<TraceContribution> history;  
};
 
struct CompositionTrace {
    std::unordered_map<std::string, TraceEntry> environment;
    std::unordered_map<std::string, TraceEntry> library_paths;
    std::unordered_map<std::string, TraceEntry> arguments;
    std::vector<std::string> decisions;  
};
 
// ============================================================================
// APP DECLARATION
// ============================================================================
 
// An asset the app exposes for other apps or the host to use.
struct AssetExportDecl {
    std::string id;    
    std::string path;  
    std::string type;  
};
 
// What the app declares it needs to run.
//
// This is typically parsed from nap.json
// but can be constructed directly. All paths are relative to where the app
// will be installed.
//
// Example - a Lua app:
//
//     AppDeclaration app;
//     app.id = "com.example.game";
//     app.version = "2.1.0";
//     app.entrypoint_path = "main.lua";
//     app.nak_id = "lua";
//     app.nak_version_req = ">=5.4.0";
//     app.lib_dirs = {"lib", "vendor"};
//     app.environment["GAME_DATA"] = "./data";
//
// Example - a standalone binary (no runtime):
//
//     AppDeclaration app;
//     app.id = "org.tool.converter";
//     app.version = "1.0.0";
//     app.entrypoint_path = "bin/converter";
//     // nak_id left empty - no runtime needed
//
struct AppDeclaration {
    // Required: App identity
    std::string id;       
    std::string version;  
 
    // Required: What to run
    std::string entrypoint_path;  
 
    // Optional: Runtime requirements (leave nak_id empty for standalone binaries)
    std::string nak_id;          
    std::string nak_version_req; 
    std::string nak_loader;      
 
    // Optional: Arguments passed after the entrypoint
    std::vector<std::string> entrypoint_args;
 
    // Optional: Environment operations.
    EnvMap environment;
 
    // Optional: Library search paths (relative to app root)
    std::vector<std::string> lib_dirs;
 
    // Optional: Asset directories and exports
    std::vector<std::string> asset_dirs;
    std::vector<AssetExportDecl> asset_exports;
 
    // Optional: Permission requests
    std::vector<std::string> permissions_filesystem;  
    std::vector<std::string> permissions_network;     
 
    // Optional: Metadata (informational only, does not affect composition)
    std::string description;
    std::string author;
    std::string license;
    std::string homepage;
 
};
 
// ============================================================================
// HOST ENVIRONMENT
// ============================================================================
 
// Host configuration loaded from host.json.
//
// This replaces the old "profiles" concept with a single host configuration.
// It contains environment variables and library paths.
//
// Example:
//
//     HostEnvironment host_env;
//     host_env.vars["NAH_ENV"] = EnvValue(EnvOp::Set, "production");
//     host_env.vars["LOG_LEVEL"] = EnvValue(EnvOp::Set, "warn");
//     host_env.paths.library_prepend = {"/opt/libs"};
//
// Host environment takes precedence over app-declared environment variables.
//
struct HostEnvironment {
    EnvMap vars;  
 
    struct {
        std::vector<std::string> library_prepend;  
        std::vector<std::string> library_append;   
    } paths;
 
    std::string source_path;  
};
 
// ============================================================================
// LOADER CONFIGURATION
// ============================================================================
 
// How a runtime executes app entrypoints.
//
// For example, Lua's loader might be:
//     exec_path: "/runtimes/lua/bin/lua"
//     args_template: ["{NAH_APP_ENTRY}"]
//
// The args_template supports {VAR} placeholders that are expanded from the
// environment before execution.
struct LoaderConfig {
    std::string exec_path;                   
    std::vector<std::string> args_template;  
};
 
// ============================================================================
// RUNTIME DESCRIPTOR
// ============================================================================
 
// Describes an installed runtime (NAK - Native Application Kit).
//
// A NAK is a runtime like Lua, Node, or Python that apps can depend on.
// The RuntimeDescriptor tells NAH where the runtime is installed and how
// to use it.
//
// Example - Lua 5.4.6:
//
//     RuntimeDescriptor lua;
//     lua.nak.id = "lua";
//     lua.nak.version = "5.4.6";
//     lua.paths.root = "/runtimes/lua/5.4.6";
//     lua.paths.lib_dirs = {"/runtimes/lua/5.4.6/lib"};
//     lua.environment["LUA_PATH"] = EnvValue(EnvOp::Prepend, "./?.lua", ";");
//     lua.loaders["default"] = {"/runtimes/lua/5.4.6/bin/lua", {"{NAH_APP_ENTRY}"}};
//
// NAKs without loaders (libs-only) just provide libraries and environment.
//
struct RuntimeDescriptor {
    struct {
        std::string id;       
        std::string version;  
    } nak;
 
    struct {
        std::string root;           
        std::string resource_root;  
        std::vector<std::string> lib_dirs;  
    } paths;
 
    // Environment variables provided by this runtime
    EnvMap environment;
 
    // Loaders - how this runtime executes apps. Empty for libs-only NAKs.
    // Key is loader name (use "default" for the primary loader).
    std::unordered_map<std::string, LoaderConfig> loaders;
 
    bool has_loaders() const { return !loaders.empty(); }
 
    struct {
        bool present = false;
        std::string cwd;  
    } execution;
 
    struct {
        std::string package_hash;   
        std::string installed_at;   
        std::string installed_by;   
        std::string source;         
    } provenance;
 
    TrustInfo trust;  
 
    std::string source_path;  
};
 
// ============================================================================
// INSTALL RECORD
// ============================================================================
 
// Records where an app is installed and which runtime version to use.
//
// Created at install time, this captures:
// - Where the app lives on disk (paths.install_root)
// - Which specific runtime version to use (nak.record_ref)
// - Trust/verification state
// - Per-install overrides
//
// Example - minimal install record:
//
//     InstallRecord install;
//     install.install.instance_id = "550e8400-e29b-41d4-a716-446655440000";
//     install.paths.install_root = "/apps/myapp";
//     install.nak.record_ref = "lua@5.4.6.json";  // Key into RuntimeInventory
//
// Example - with environment override:
//
//     InstallRecord install;
//     install.install.instance_id = "...";
//     install.paths.install_root = "/apps/myapp";
//     install.nak.record_ref = "lua@5.4.6.json";
//     install.overrides.environment["DEBUG"] = "1";
//
struct InstallRecord {
    // Unique identifier for this installation
    struct {
        std::string instance_id;  
    } install;
 
    // Snapshot of app info at install time (audit only, does not affect composition)
    struct {
        std::string id;
        std::string version;
        std::string nak_id;
        std::string nak_version_req;
    } app;
 
    // Which runtime to use - resolved and pinned at install time
    struct {
        std::string id;               
        std::string version;          
        std::string record_ref;       
        std::string loader;           
        std::string selection_reason; 
    } nak;
 
    struct {
        std::string install_root;  
    } paths;
 
    struct {
        std::string package_hash;   
        std::string installed_at;   
        std::string installed_by;   
        std::string source;         
    } provenance;
 
    TrustInfo trust;
 
    // Per-install host-owned overrides
    struct {
        EnvMap environment;  
        struct {
            std::vector<std::string> prepend;  
            std::vector<std::string> append;   
        } arguments;
        struct {
            std::vector<std::string> library_prepend;  
            std::vector<std::string> library_append;   
        } paths;
    } overrides;
 
    std::string source_path;  
};
 
// ============================================================================
// RUNTIME INVENTORY
// ============================================================================
 
// Collection of available runtimes on the host.
//
// Maps record_ref (e.g., "lua@5.4.6.json") to RuntimeDescriptor.
// The InstallRecord's nak.record_ref is used as the key to look up the runtime.
//
// Example:
//
//     RuntimeInventory inventory;
//     inventory.runtimes["lua@5.4.6.json"] = lua_descriptor;
//     inventory.runtimes["node@20.0.0.json"] = node_descriptor;
//
struct RuntimeInventory {
    std::unordered_map<std::string, RuntimeDescriptor> runtimes;
};
 
// ============================================================================
// ASSET EXPORT
// ============================================================================
 
// An exported asset in the contract (paths resolved to absolute).
struct AssetExport {
    std::string id;    
    std::string path;  
    std::string type;  
};
 
// ============================================================================
// LAUNCH CONTRACT
// ============================================================================
 
// The output of nah_compose() - everything needed to launch an application.
//
// The contract is self-contained: no additional lookups are needed to execute
// the app. All paths are absolute, all environment variables are resolved,
// and the exact binary and arguments are specified.
//
// To execute a contract:
//
//     if (result.ok) {
//         const auto& c = result.contract;
//
//         // Set environment
//         for (const auto& [key, value] : c.environment) {
//             setenv(key.c_str(), value.c_str(), 1);
//         }
//
//         // Set library path
//         std::string lib_path;
//         for (const auto& p : c.execution.library_paths) {
//             if (!lib_path.empty()) lib_path += ":";
//             lib_path += p;
//         }
//         setenv(c.execution.library_path_env_key.c_str(), lib_path.c_str(), 1);
//
//         // Change to working directory
//         chdir(c.execution.cwd.c_str());
//
//         // Build argv: [binary, ...arguments]
//         std::vector<char*> argv;
//         argv.push_back(const_cast<char*>(c.execution.binary.c_str()));
//         for (const auto& arg : c.execution.arguments) {
//             argv.push_back(const_cast<char*>(arg.c_str()));
//         }
//         argv.push_back(nullptr);
//
//         // Execute
//         execv(c.execution.binary.c_str(), argv.data());
//     }
//
struct LaunchContract {
    // App identity and paths (all absolute)
    struct {
        std::string id;          
        std::string version;     
        std::string root;        
        std::string entrypoint;  
        std::string package_hash; 
    } app;
 
    // Runtime info (empty if standalone app)
    struct {
        std::string id;            
        std::string version;       
        std::string root;          
        std::string resource_root; 
        std::string record_ref;    
        std::string package_hash;  
    } nak;
 
    // How to execute the app
    struct {
        std::string binary;        
        std::vector<std::string> arguments;  
        std::string cwd;           
        std::string library_path_env_key;    
        std::vector<std::string> library_paths;  
    } execution;
 
    // Complete environment map (ready to pass to exec)
    std::unordered_map<std::string, std::string> environment;
 
    // Permission requests for a host launcher to interpret and enforce
    struct {
        std::vector<std::string> filesystem;
        std::vector<std::string> network;
    } permissions;
 
    // Aggregate trust for every executable artifact in this contract
    TrustInfo trust;
 
    // Exported assets (id -> absolute path)
    std::unordered_map<std::string, AssetExport> exports;
 
};
 
// ============================================================================
// COMPOSITION OPTIONS
// ============================================================================
 
// Options passed to nah_compose().
struct CompositionOptions {
    bool enable_trace = false;       
    std::string now;                 
    std::string loader_override;     
};
 
// ============================================================================
// COMPOSITION RESULT
// ============================================================================
 
// The result of calling nah_compose().
//
// Check result.ok to see if composition succeeded. If true, result.contract
// contains the launch specification. If false, check critical_error and
// critical_error_context for what went wrong.
//
// Warnings are always populated (even on success) for non-fatal issues.
//
// Example:
//
//     CompositionResult result = nah_compose(app, host_env, install, inventory);
//     if (!result.ok) {
//         std::cerr << "Composition failed: " << result.critical_error_context << "\n";
//         return 1;
//     }
//     for (const auto& w : result.warnings) {
//         std::cerr << "Warning: " << w.key << "\n";
//     }
//     // Use result.contract...
//
struct CompositionResult {
    bool ok = false;                              
    std::optional<CriticalError> critical_error;  
    std::string critical_error_context;           
    LaunchContract contract;                      
    std::vector<WarningObject> warnings;          
    std::optional<CompositionTrace> trace;        
};
 
// ============================================================================
// PURE FUNCTIONS - Path Utilities
// ============================================================================
 
inline bool is_absolute_path(const std::string& path) {
    if (path.empty()) return false;
#ifdef _WIN32
    if (path.size() >= 2) {
        if (path[1] == ':') return true;
        if (path[0] == '\\' && path[1] == '\\') return true;
    }
#endif
    return path[0] == '/';
}
 
inline std::string normalize_separators(const std::string& path) {
    std::string result = path;
    for (char& c : result) {
        if (c == '\\') c = '/';
    }
    return result;
}
 
inline bool path_escapes_root(const std::string& root, const std::string& path) {
    std::string norm_root = normalize_separators(root);
    std::string norm_path = normalize_separators(path);
 
    while (!norm_root.empty() && norm_root.back() == '/') {
        norm_root.pop_back();
    }
 
    // Path must start with root
    if (norm_path.find(norm_root) != 0) {
        return true;
    }
 
    // Path must either be exactly root, or have a / after the root prefix
    // This prevents /app matching /application
    std::string rel = norm_path.substr(norm_root.size());
    if (!rel.empty() && rel[0] != '/') {
        return true;  // e.g., /application doesn't have / after /app
    }
    if (!rel.empty() && rel[0] == '/') {
        rel = rel.substr(1);
    }
 
    int depth = 0;
    size_t pos = 0;
    while (pos < rel.size()) {
        size_t next = rel.find('/', pos);
        std::string component = (next == std::string::npos)
            ? rel.substr(pos)
            : rel.substr(pos, next - pos);
 
        if (component == "..") {
            depth--;
            if (depth < 0) return true;
        } else if (!component.empty() && component != ".") {
            depth++;
        }
 
        if (next == std::string::npos) break;
        pos = next + 1;
    }
 
    return false;
}
 
inline std::string join_path(const std::string& base, const std::string& rel) {
    if (base.empty()) return rel;
    if (rel.empty()) return base;
 
    std::string result = base;
    if (result.back() != '/' && result.back() != '\\') {
        result += '/';
    }
 
    size_t start = 0;
    while (start < rel.size() && (rel[start] == '/' || rel[start] == '\\')) {
        start++;
    }
 
    result += rel.substr(start);
    return normalize_separators(result);
}
 
inline std::string get_library_path_env_key() {
#if defined(__APPLE__)
    return "DYLD_LIBRARY_PATH";
#elif defined(_WIN32)
    return "PATH";
#else
    return "LD_LIBRARY_PATH";
#endif
}
 
inline char get_path_separator() {
#ifdef _WIN32
    return ';';
#else
    return ':';
#endif
}
 
// ============================================================================
// PURE FUNCTIONS - Validation
// ============================================================================
 
struct ValidationResult {
    bool ok = true;
    std::vector<std::string> errors;
    std::vector<std::string> warnings;
};
 
inline ValidationResult validate_declaration(const AppDeclaration& decl) {
    ValidationResult result;
 
    if (decl.id.empty()) {
        result.ok = false;
        result.errors.push_back("app.id is required");
    }
 
    if (decl.version.empty()) {
        result.ok = false;
        result.errors.push_back("app.version is required");
    }
 
    if (decl.entrypoint_path.empty()) {
        result.ok = false;
        result.errors.push_back("entrypoint_path is required");
    }
 
    if (!decl.entrypoint_path.empty() && is_absolute_path(decl.entrypoint_path)) {
        result.ok = false;
        result.errors.push_back("entrypoint_path must be relative");
    }
 
    for (const auto& lib_dir : decl.lib_dirs) {
        if (is_absolute_path(lib_dir)) {
            result.ok = false;
            result.errors.push_back("lib_dir must be relative: " + lib_dir);
        }
    }
 
    for (const auto& exp : decl.asset_exports) {
        if (is_absolute_path(exp.path)) {
            result.ok = false;
            result.errors.push_back("asset_export path must be relative: " + exp.path);
        }
    }
 
    if (!decl.nak_id.empty() && decl.nak_version_req.empty()) {
        result.warnings.push_back("nak_id specified but nak_version_req is empty");
    }
 
    return result;
}
 
inline ValidationResult validate_install_record(const InstallRecord& record) {
    ValidationResult result;
 
    if (record.install.instance_id.empty()) {
        result.ok = false;
        result.errors.push_back("install.instance_id is required");
    }
 
    if (record.paths.install_root.empty()) {
        result.ok = false;
        result.errors.push_back("paths.install_root is required");
    }
 
    if (!record.paths.install_root.empty() && !is_absolute_path(record.paths.install_root)) {
        result.ok = false;
        result.errors.push_back("paths.install_root must be absolute");
    }
 
    return result;
}
 
inline ValidationResult validate_runtime(const RuntimeDescriptor& runtime) {
    ValidationResult result;
 
    if (runtime.nak.id.empty()) {
        result.ok = false;
        result.errors.push_back("nak.id is required");
    }
 
    if (runtime.nak.version.empty()) {
        result.ok = false;
        result.errors.push_back("nak.version is required");
    }
 
    if (runtime.paths.root.empty()) {
        result.ok = false;
        result.errors.push_back("paths.root is required");
    }
 
    if (!runtime.paths.root.empty() && !is_absolute_path(runtime.paths.root)) {
        result.ok = false;
        result.errors.push_back("paths.root must be absolute");
    }
 
    if (!runtime.paths.resource_root.empty() &&
        (!is_absolute_path(runtime.paths.resource_root) ||
         path_escapes_root(runtime.paths.root, runtime.paths.resource_root))) {
        result.ok = false;
        result.errors.push_back("paths.resource_root must be within paths.root");
    }
 
    for (const auto& lib_dir : runtime.paths.lib_dirs) {
        if (!is_absolute_path(lib_dir) || path_escapes_root(runtime.paths.root, lib_dir)) {
            result.ok = false;
            result.errors.push_back("lib_dir must be within paths.root: " + lib_dir);
        }
    }
 
    for (const auto& [name, loader] : runtime.loaders) {
        if (loader.exec_path.empty() || !is_absolute_path(loader.exec_path) ||
            path_escapes_root(runtime.paths.root, loader.exec_path)) {
            result.ok = false;
            result.errors.push_back("loader exec_path must be within paths.root: " + name);
        }
    }
 
    return result;
}
 
 
 
// ============================================================================
// PURE FUNCTIONS - Environment
// ============================================================================
 
inline std::optional<std::string> apply_env_op(
    const std::string& key,
    const EnvValue& env_val,
    const std::unordered_map<std::string, std::string>& current_env)
{
    switch (env_val.op) {
        case EnvOp::Set:
            return env_val.value;
 
        case EnvOp::Prepend: {
            auto it = current_env.find(key);
            if (it != current_env.end() && !it->second.empty()) {
                return env_val.value + env_val.separator + it->second;
            }
            return env_val.value;
        }
 
        case EnvOp::Append: {
            auto it = current_env.find(key);
            if (it != current_env.end() && !it->second.empty()) {
                return it->second + env_val.separator + env_val.value;
            }
            return env_val.value;
        }
 
        case EnvOp::Unset:
            return std::nullopt;
    }
 
    return env_val.value;
}
 
// ============================================================================
// PURE FUNCTIONS - Placeholder Expansion
// ============================================================================
 
struct ExpansionResult {
    bool ok = true;
    std::string value;
    std::string error;
};
 
inline ExpansionResult expand_placeholders(
    const std::string& input,
    const std::unordered_map<std::string, std::string>& env)
{
    ExpansionResult result;
    result.value.reserve(input.size());
 
    size_t placeholder_count = 0;
    size_t i = 0;
 
    while (i < input.size()) {
        if (input[i] == '{') {
            size_t end = input.find('}', i + 1);
            if (end != std::string::npos) {
                std::string var_name = input.substr(i + 1, end - i - 1);
 
                placeholder_count++;
                if (placeholder_count > MAX_PLACEHOLDERS) {
                    result.ok = false;
                    result.error = "placeholder_limit";
                    return result;
                }
 
                auto it = env.find(var_name);
                if (it == env.end()) {
                    result.ok = false;
                    result.error = "missing_placeholder:" + var_name;
                    return result;
                }
                result.value += it->second;
 
                if (result.value.size() > MAX_EXPANDED_SIZE) {
                    result.ok = false;
                    result.error = "expansion_overflow";
                    return result;
                }
 
                i = end + 1;
                continue;
            }
        }
 
        result.value += input[i];
        i++;
 
        if (result.value.size() > MAX_EXPANDED_SIZE) {
            result.ok = false;
            result.error = "expansion_overflow";
            return result;
        }
    }
 
    return result;
}
 
struct ExpansionListResult {
    bool ok = true;
    std::vector<std::string> values;
    std::string error;
};
 
inline ExpansionListResult expand_string_vector(
    const std::vector<std::string>& inputs,
    const std::unordered_map<std::string, std::string>& env)
{
    ExpansionListResult result;
    result.values.reserve(inputs.size());
 
    for (const auto& input : inputs) {
        auto expanded = expand_placeholders(input, env);
        if (!expanded.ok) {
            result.ok = false;
            result.error = expanded.error;
            return result;
        }
        result.values.push_back(std::move(expanded.value));
    }
 
    return result;
}
 
// ============================================================================
// PURE FUNCTIONS - Runtime Resolution
// ============================================================================
 
struct RuntimeResolutionResult {
    bool resolved = false;
    std::string record_ref;
    RuntimeDescriptor runtime;
    std::string selection_reason;
    std::vector<std::string> warnings;
};
 
inline RuntimeResolutionResult resolve_runtime(
    const AppDeclaration& app,
    const InstallRecord& install,
    const RuntimeInventory& inventory)
{
    RuntimeResolutionResult result;
 
    // Standalone apps don't need runtime resolution
    if (app.nak_id.empty()) {
        result.resolved = true;
        result.selection_reason = "standalone_app";
        return result;
    }
 
    // Get record_ref from install record
    std::string record_ref = install.nak.record_ref;
 
    if (record_ref.empty()) {
        result.warnings.push_back("nak.record_ref is empty in install record");
        return result;
    }
 
    auto it = inventory.runtimes.find(record_ref);
    if (it == inventory.runtimes.end()) {
        result.warnings.push_back("NAK not found in inventory: " + record_ref);
        return result;
    }
 
    if (it->second.nak.id != app.nak_id ||
        (!install.nak.id.empty() && install.nak.id != it->second.nak.id) ||
        (!install.nak.version.empty() && install.nak.version != it->second.nak.version)) {
        result.warnings.push_back("pinned NAK identity does not match app or install record");
        return result;
    }
 
    result.resolved = true;
    result.record_ref = record_ref;
    result.runtime = it->second;
    result.selection_reason = "pinned_from_install_record";
 
    return result;
}
 
// ============================================================================
// PURE FUNCTIONS - Path Binding
// ============================================================================
 
struct PathBindingResult {
    bool ok = true;
    std::string entrypoint;
    std::vector<std::string> library_paths;
    std::unordered_map<std::string, AssetExport> exports;
    std::vector<std::string> errors;
};
 
inline PathBindingResult bind_paths(
    const AppDeclaration& decl,
    const InstallRecord& install,
    const RuntimeDescriptor* runtime,
    const HostEnvironment& host_env)
{
    PathBindingResult result;
    const std::string& app_root = install.paths.install_root;
 
    // Entrypoint
    std::string entrypoint = join_path(app_root, decl.entrypoint_path);
    if (path_escapes_root(app_root, entrypoint)) {
        result.ok = false;
        result.errors.push_back("entrypoint escapes app root");
        return result;
    }
    result.entrypoint = entrypoint;
 
    // Library paths in order: host prepend, install overrides, NAK, app, host append
    for (const auto& path : host_env.paths.library_prepend) {
        if (is_absolute_path(path)) {
            result.library_paths.push_back(path);
        }
    }
 
    for (const auto& path : install.overrides.paths.library_prepend) {
        if (is_absolute_path(path)) {
            result.library_paths.push_back(path);
        }
    }
 
    if (runtime) {
        for (const auto& lib_dir : runtime->paths.lib_dirs) {
            result.library_paths.push_back(lib_dir);
        }
    }
 
    for (const auto& lib_dir : decl.lib_dirs) {
        std::string abs_lib = join_path(app_root, lib_dir);
        if (path_escapes_root(app_root, abs_lib)) {
            result.ok = false;
            result.errors.push_back("lib_dir escapes app root: " + lib_dir);
            return result;
        }
        result.library_paths.push_back(abs_lib);
    }
 
    for (const auto& path : host_env.paths.library_append) {
        if (is_absolute_path(path)) {
            result.library_paths.push_back(path);
        }
    }
 
    for (const auto& path : install.overrides.paths.library_append) {
        if (is_absolute_path(path)) {
            result.library_paths.push_back(path);
        }
    }
 
    // Asset exports
    for (const auto& exp : decl.asset_exports) {
        std::string abs_path = join_path(app_root, exp.path);
        if (path_escapes_root(app_root, abs_path)) {
            result.ok = false;
            result.errors.push_back("asset export escapes app root: " + exp.id);
            return result;
        }
        result.exports[exp.id] = {exp.id, abs_path, exp.type};
    }
 
    return result;
}
 
// ============================================================================
// PURE FUNCTIONS - Environment Composition
// ============================================================================
 
inline std::unordered_map<std::string, std::string> compose_environment(
    const AppDeclaration& decl,
    const InstallRecord& install,
    const RuntimeDescriptor* runtime,
    const HostEnvironment& host_env,
    const LaunchContract& contract,
    CompositionTrace* trace = nullptr)
{
    std::unordered_map<std::string, std::string> env;
 
    auto record = [&](const std::string& key, const std::string& value,
                      const std::string& kind, const std::string& path,
                      int rank, EnvOp op, bool accepted) {
        if (trace) {
            TraceContribution contrib;
            contrib.value = value;
            contrib.source_kind = kind;
            contrib.source_path = path;
            contrib.precedence_rank = rank;
            contrib.operation = op;
            contrib.accepted = accepted;
            trace->environment[key].history.push_back(contrib);
        }
    };
 
    // Layer 1: App environment (rank 5).
    for (const auto& [key, val] : decl.environment) {
        auto result = apply_env_op(key, val, env);
        if (result.has_value()) {
            env[key] = *result;
            record(key, *result, trace_source::MANIFEST, "manifest", 5, val.op, true);
        } else {
            env.erase(key);
            record(key, "", trace_source::MANIFEST, "manifest", 5, val.op, true);
        }
    }
 
    // Layer 2: NAK environment (rank 4).
    if (runtime) {
        for (const auto& [key, val] : runtime->environment) {
            auto result = apply_env_op(key, val, env);
            if (result.has_value()) {
                env[key] = *result;
                record(key, *result, trace_source::NAK_RECORD, runtime->source_path, 4, val.op, true);
            } else {
                env.erase(key);
                record(key, "", trace_source::NAK_RECORD, runtime->source_path, 4, val.op, true);
            }
        }
    }
 
    // Layer 3: Host environment (rank 3).
    for (const auto& [key, val] : host_env.vars) {
        auto result = apply_env_op(key, val, env);
        if (result.has_value()) {
            env[key] = *result;
            record(key, *result, trace_source::HOST, host_env.source_path, 3, val.op, true);
        } else {
            env.erase(key);
            record(key, "", trace_source::HOST, host_env.source_path, 3, val.op, true);
        }
    }
 
    // Layer 4: Install record overrides (rank 2)
    for (const auto& [key, val] : install.overrides.environment) {
        auto result = apply_env_op(key, val, env);
        if (result.has_value()) {
            env[key] = *result;
            record(key, *result, trace_source::INSTALL_RECORD, install.source_path, 2, val.op, true);
        } else {
            env.erase(key);
            record(key, "", trace_source::INSTALL_RECORD, install.source_path, 2, val.op, true);
        }
    }
 
    // Layer 5: NAH standard variables (rank 1, always set)
    env["NAH_APP_ID"] = contract.app.id;
    record("NAH_APP_ID", contract.app.id, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
 
    env["NAH_APP_VERSION"] = contract.app.version;
    record("NAH_APP_VERSION", contract.app.version, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
 
    env["NAH_APP_ROOT"] = contract.app.root;
    record("NAH_APP_ROOT", contract.app.root, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
 
    env["NAH_APP_ENTRY"] = contract.app.entrypoint;
    record("NAH_APP_ENTRY", contract.app.entrypoint, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
 
    if (runtime) {
        env["NAH_NAK_ID"] = runtime->nak.id;
        record("NAH_NAK_ID", runtime->nak.id, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
 
        env["NAH_NAK_VERSION"] = runtime->nak.version;
        record("NAH_NAK_VERSION", runtime->nak.version, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
 
        env["NAH_NAK_ROOT"] = runtime->paths.root;
        record("NAH_NAK_ROOT", runtime->paths.root, trace_source::NAH_STANDARD, "nah", 1, EnvOp::Set, true);
    }
 
    return env;
}
 
// ============================================================================
// PURE FUNCTIONS - Timestamp Comparison
// ============================================================================
 
inline std::string normalize_rfc3339(const std::string& ts) {
    if (ts.empty()) return ts;
 
    std::string result = ts;
    if (result.size() >= 6) {
        std::string suffix = result.substr(result.size() - 6);
        if (suffix == "+00:00" || suffix == "-00:00") {
            result = result.substr(0, result.size() - 6) + "Z";
        }
    }
 
    return result;
}
 
inline bool timestamp_before(const std::string& a, const std::string& b) {
    return normalize_rfc3339(a) < normalize_rfc3339(b);
}
 
// ============================================================================
// MAIN COMPOSITION FUNCTION
// ============================================================================
 
// Compose a launch contract from app declaration and host state.
//
// This is the main entry point. Given:
//   - app:       What the application declares it needs
//   - host_env:  Host-provided environment variables
//   - install:   Where the app is installed and which runtime to use
//   - inventory: Available runtimes on the host
//
// Returns a CompositionResult. Check result.ok - if true, result.contract
// contains everything needed to launch the application.
//
// This function is pure: no I/O, no syscalls, no side effects. Same inputs
// always produce the same output. This makes it safe to call from any context
// and easy to test.
//
// Example:
//
//     AppDeclaration app;
//     app.id = "com.example.game";
//     app.version = "1.0.0";
//     app.entrypoint_path = "main.lua";
//     app.nak_id = "lua";
//
//     InstallRecord install;
//     install.install.instance_id = "abc123";
//     install.paths.install_root = "/apps/game";
//     install.nak.record_ref = "lua@5.4.6.json";
//
//     HostEnvironment host_env;  // Empty = no host overrides
//
//     RuntimeInventory inventory;
//     inventory.runtimes["lua@5.4.6.json"] = lua_runtime;
//
//     auto result = nah_compose(app, host_env, install, inventory);
//     if (result.ok) {
//         // result.contract.execution.binary = "/runtimes/lua/bin/lua"
//         // result.contract.execution.arguments = ["/apps/game/main.lua"]
//         // result.contract.environment = {"LUA_PATH": "...", "NAH_APP_ID": "com.example.game", ...}
//     }
//
inline CompositionResult nah_compose(
    const AppDeclaration& app,
    const HostEnvironment& host_env,
    const InstallRecord& install,
    const RuntimeInventory& inventory,
    const CompositionOptions& options = {})
{
    CompositionResult result;
 
    // Initialize trace if enabled
    CompositionTrace* trace_ptr = nullptr;
    if (options.enable_trace) {
        result.trace = CompositionTrace{};
        trace_ptr = &(*result.trace);
        trace_ptr->decisions.push_back("Starting composition");
    }
 
    // Validate declaration
    auto decl_valid = validate_declaration(app);
    if (!decl_valid.ok) {
        result.critical_error = CriticalError::MANIFEST_MISSING;
        result.critical_error_context = decl_valid.errors.empty() ?
            "invalid declaration" : decl_valid.errors[0];
        if (trace_ptr) trace_ptr->decisions.push_back("FAILED: Declaration validation failed");
        return result;
    }
    if (trace_ptr) trace_ptr->decisions.push_back("Declaration validated");
 
    // Validate install record
    auto install_valid = validate_install_record(install);
    if ((!install.app.id.empty() && install.app.id != app.id) ||
        (!install.app.version.empty() && install.app.version != app.version)) {
        install_valid.ok = false;
        install_valid.errors.push_back("install record app identity does not match the manifest");
    }
    if (!install_valid.ok) {
        result.critical_error = CriticalError::INSTALL_RECORD_INVALID;
        result.critical_error_context = install_valid.errors.empty() ?
            "invalid install record" : install_valid.errors[0];
        if (trace_ptr) trace_ptr->decisions.push_back("FAILED: Install record validation failed");
        return result;
    }
    if (trace_ptr) trace_ptr->decisions.push_back("Install record validated");
 
    // Resolve runtime
    auto runtime_result = resolve_runtime(app, install, inventory);
    RuntimeDescriptor* runtime_ptr = runtime_result.resolved && !runtime_result.runtime.nak.id.empty()
        ? &runtime_result.runtime : nullptr;
 
    if (!app.nak_id.empty() && !runtime_ptr) {
        result.critical_error = CriticalError::NAK_NOT_FOUND;
        result.critical_error_context = runtime_result.warnings.empty()
            ? "required pinned NAK is unavailable"
            : runtime_result.warnings.front();
        return result;
    }
 
    if (trace_ptr) {
        if (runtime_ptr) {
            trace_ptr->decisions.push_back("Runtime resolved: " + runtime_ptr->nak.id + "@" + runtime_ptr->nak.version);
        } else if (app.nak_id.empty()) {
            trace_ptr->decisions.push_back("Standalone app (no runtime)");
        } else {
            trace_ptr->decisions.push_back("Runtime not found");
        }
    }
 
    // Validate runtime if present
    if (runtime_ptr) {
        auto runtime_valid = validate_runtime(*runtime_ptr);
        if (!runtime_valid.ok) {
            result.critical_error = CriticalError::PATH_TRAVERSAL;
            result.critical_error_context = runtime_valid.errors.empty() ?
                "invalid runtime" : runtime_valid.errors[0];
            if (trace_ptr) trace_ptr->decisions.push_back("FAILED: Runtime validation failed");
            return result;
        }
    }
 
    // Populate basic contract fields
    LaunchContract& contract = result.contract;
 
    contract.app.id = app.id;
    contract.app.version = app.version;
    contract.app.root = install.paths.install_root;
    contract.app.package_hash = install.provenance.package_hash;
 
    if (runtime_ptr) {
        contract.nak.id = runtime_ptr->nak.id;
        contract.nak.version = runtime_ptr->nak.version;
        contract.nak.root = runtime_ptr->paths.root;
        contract.nak.resource_root = runtime_ptr->paths.resource_root.empty() ?
            runtime_ptr->paths.root : runtime_ptr->paths.resource_root;
        contract.nak.record_ref = runtime_result.record_ref;
        contract.nak.package_hash = runtime_ptr->provenance.package_hash;
    }
 
    // Bind paths
    auto paths = bind_paths(app, install, runtime_ptr, host_env);
    if (!paths.ok) {
        result.critical_error = CriticalError::PATH_TRAVERSAL;
        result.critical_error_context = paths.errors.empty() ?
            "path binding failed" : paths.errors.front();
        if (trace_ptr) trace_ptr->decisions.push_back("FAILED: Path binding failed");
        return result;
    }
 
    contract.app.entrypoint = paths.entrypoint;
    contract.exports = paths.exports;
    if (trace_ptr) trace_ptr->decisions.push_back("Paths bound successfully");
 
    // Compose environment
    auto env = compose_environment(app, install, runtime_ptr, host_env, contract, trace_ptr);
    const auto unexpanded_env = env;
    for (auto& [key, value] : env) {
        auto expanded = expand_placeholders(value, unexpanded_env);
        if (!expanded.ok) {
            result.critical_error = CriticalError::EXPANSION_FAILED;
            result.critical_error_context = "environment " + key + ": " + expanded.error;
            if (trace_ptr) trace_ptr->decisions.push_back("FAILED: " + result.critical_error_context);
            return result;
        }
        value = std::move(expanded.value);
    }
    contract.environment = env;
 
    auto fail_expansion = [&](const std::string& context, const std::string& error) {
        result.critical_error = CriticalError::EXPANSION_FAILED;
        result.critical_error_context = context + ": " + error;
        if (trace_ptr) trace_ptr->decisions.push_back("FAILED: " + result.critical_error_context);
    };
 
    // Determine execution binary and arguments
    std::string pinned_loader = install.nak.loader;
 
    // Override loader if specified in options
    if (!options.loader_override.empty()) {
        pinned_loader = options.loader_override;
        if (trace_ptr) trace_ptr->decisions.push_back("Loader override requested: " + pinned_loader);
    }
 
    if (runtime_ptr && runtime_ptr->has_loaders()) {
        std::string effective_loader = pinned_loader;
 
        if (effective_loader.empty()) {
            if (runtime_ptr->loaders.count("default")) {
                effective_loader = "default";
                if (trace_ptr) trace_ptr->decisions.push_back("Auto-selected 'default' loader");
            } else if (runtime_ptr->loaders.size() == 1) {
                effective_loader = runtime_ptr->loaders.begin()->first;
                if (trace_ptr) trace_ptr->decisions.push_back("Auto-selected single loader: " + effective_loader);
            } else {
                result.critical_error = CriticalError::NAK_LOADER_INVALID;
                result.critical_error_context = "multiple NAK loaders are available but none was selected";
                if (trace_ptr) trace_ptr->decisions.push_back("FAILED: No NAK loader selected");
                return result;
            }
        } else {
            if (trace_ptr) trace_ptr->decisions.push_back("Using pinned loader: " + effective_loader);
        }
 
        if (!effective_loader.empty()) {
            auto it = runtime_ptr->loaders.find(effective_loader);
            if (it == runtime_ptr->loaders.end()) {
                result.critical_error = CriticalError::NAK_LOADER_INVALID;
                result.critical_error_context = "loader not found: " + effective_loader;
                if (trace_ptr) trace_ptr->decisions.push_back("FAILED: Loader not found");
                return result;
            }
 
            contract.execution.binary = it->second.exec_path;
            auto expanded = expand_string_vector(it->second.args_template, env);
            if (!expanded.ok) {
                fail_expansion("loader arguments", expanded.error);
                return result;
            }
            contract.execution.arguments = std::move(expanded.values);
        }
    } else {
        contract.execution.binary = contract.app.entrypoint;
        if (trace_ptr) trace_ptr->decisions.push_back("Using app entrypoint as binary");
    }
 
    // Apply argument overrides
    auto expanded_prepend = expand_string_vector(install.overrides.arguments.prepend, env);
    if (!expanded_prepend.ok) {
        fail_expansion("prepended arguments", expanded_prepend.error);
        return result;
    }
    contract.execution.arguments.insert(
        contract.execution.arguments.begin(),
        expanded_prepend.values.begin(),
        expanded_prepend.values.end());
 
    auto expanded_entry_args = expand_string_vector(app.entrypoint_args, env);
    if (!expanded_entry_args.ok) {
        fail_expansion("app arguments", expanded_entry_args.error);
        return result;
    }
    contract.execution.arguments.insert(
        contract.execution.arguments.end(),
        expanded_entry_args.values.begin(),
        expanded_entry_args.values.end());
 
    auto expanded_append = expand_string_vector(install.overrides.arguments.append, env);
    if (!expanded_append.ok) {
        fail_expansion("appended arguments", expanded_append.error);
        return result;
    }
    contract.execution.arguments.insert(
        contract.execution.arguments.end(),
        expanded_append.values.begin(),
        expanded_append.values.end());
 
    // Determine cwd
    if (runtime_ptr && runtime_ptr->execution.present && !runtime_ptr->execution.cwd.empty()) {
        auto cwd_expanded = expand_placeholders(runtime_ptr->execution.cwd, env);
        if (!cwd_expanded.ok) {
            fail_expansion("working directory", cwd_expanded.error);
            return result;
        }
        if (is_absolute_path(cwd_expanded.value)) {
            contract.execution.cwd = cwd_expanded.value;
        } else {
            contract.execution.cwd = join_path(runtime_ptr->paths.root, cwd_expanded.value);
        }
        if (path_escapes_root(runtime_ptr->paths.root, contract.execution.cwd) &&
            path_escapes_root(contract.app.root, contract.execution.cwd)) {
            result.critical_error = CriticalError::PATH_TRAVERSAL;
            result.critical_error_context = "working directory escapes app and runtime roots";
            return result;
        }
    } else {
        contract.execution.cwd = contract.app.root;
    }
 
    // Library paths
    contract.execution.library_path_env_key = get_library_path_env_key();
    contract.execution.library_paths = paths.library_paths;
 
    contract.permissions.filesystem = app.permissions_filesystem;
    contract.permissions.network = app.permissions_network;
 
    // Trust. A runtime participates in the executable trust chain, so the
    // aggregate can only be verified when both app and runtime are verified.
    contract.trust = install.trust;
    if (runtime_ptr) {
        const auto app_state = install.trust.state;
        const auto runtime_state = runtime_ptr->trust.state;
        contract.trust.source = "nah.artifact-chain";
        contract.trust.details["app_state"] = trust_state_to_string(app_state);
        contract.trust.details["runtime_state"] = trust_state_to_string(runtime_state);
        contract.trust.details["app_digest"] = install.provenance.package_hash;
        contract.trust.details["runtime_digest"] = runtime_ptr->provenance.package_hash;
        if (app_state == TrustState::Failed || runtime_state == TrustState::Failed) {
            contract.trust.state = TrustState::Failed;
        } else if (app_state == TrustState::Unknown || runtime_state == TrustState::Unknown) {
            contract.trust.state = TrustState::Unknown;
        } else if (app_state == TrustState::Unverified || runtime_state == TrustState::Unverified) {
            contract.trust.state = TrustState::Unverified;
        } else {
            contract.trust.state = TrustState::Verified;
        }
        if (contract.trust.expires_at.empty() ||
            (!runtime_ptr->trust.expires_at.empty() &&
             timestamp_before(runtime_ptr->trust.expires_at, contract.trust.expires_at))) {
            contract.trust.expires_at = runtime_ptr->trust.expires_at;
        }
    }
 
    if (contract.trust.source.empty() && contract.trust.evaluated_at.empty()) {
        contract.trust.state = TrustState::Unknown;
        result.warnings.push_back({warning_to_string(Warning::trust_state_unknown), {}});
    } else {
        switch (contract.trust.state) {
            case TrustState::Verified:
                break;
            case TrustState::Unverified:
                result.warnings.push_back({warning_to_string(Warning::trust_state_unverified), {}});
                break;
            case TrustState::Failed:
                result.warnings.push_back({warning_to_string(Warning::trust_state_failed), {}});
                break;
            case TrustState::Unknown:
                result.warnings.push_back({warning_to_string(Warning::trust_state_unknown), {}});
                break;
        }
    }
 
    // Check trust staleness
    if (!contract.trust.expires_at.empty() && !options.now.empty()) {
        if (timestamp_before(contract.trust.expires_at, options.now)) {
            result.warnings.push_back({warning_to_string(Warning::trust_state_stale), {}});
            if (trace_ptr) trace_ptr->decisions.push_back("WARNING: Trust verification has expired");
        }
    }
 
    if (trace_ptr) trace_ptr->decisions.push_back("Composition completed successfully");
 
    result.ok = true;
    return result;
}
 
// ============================================================================
// JSON SERIALIZATION (Pure, No External Dependencies)
// ============================================================================
 
namespace json {
 
inline std::string escape(const std::string& s) {
    std::string result;
    result.reserve(s.size() + 16);
    for (char c : s) {
        switch (c) {
            case '"': result += "\\\""; break;
            case '\\': result += "\\\\"; break;
            case '\b': result += "\\b"; break;
            case '\f': result += "\\f"; break;
            case '\n': result += "\\n"; break;
            case '\r': result += "\\r"; break;
            case '\t': result += "\\t"; break;
            default:
                if (static_cast<unsigned char>(c) < 0x20) {
                    char buf[8];
                    snprintf(buf, sizeof(buf), "\\u%04x", static_cast<unsigned char>(c));
                    result += buf;
                } else {
                    result += c;
                }
        }
    }
    return result;
}
 
inline std::string str(const std::string& s) {
    return "\"" + escape(s) + "\"";
}
 
inline std::string object(const std::unordered_map<std::string, std::string>& m, size_t indent = 0) {
    if (m.empty()) return "{}";
 
    std::vector<std::string> keys;
    for (const auto& [k, _] : m) keys.push_back(k);
    std::sort(keys.begin(), keys.end());
 
    std::string pad(indent + 2, ' ');
    std::string result = "{\n";
    for (size_t i = 0; i < keys.size(); i++) {
        result += pad + str(keys[i]) + ": " + str(m.at(keys[i]));
        if (i < keys.size() - 1) result += ",";
        result += "\n";
    }
    result += std::string(indent, ' ') + "}";
    return result;
}
 
inline std::string array(const std::vector<std::string>& v, size_t indent = 0) {
    if (v.empty()) return "[]";
 
    std::string pad(indent + 2, ' ');
    std::string result = "[\n";
    for (size_t i = 0; i < v.size(); i++) {
        result += pad + str(v[i]);
        if (i < v.size() - 1) result += ",";
        result += "\n";
    }
    result += std::string(indent, ' ') + "]";
    return result;
}
 
} // namespace json
 
inline std::string serialize_contract(const LaunchContract& c) {
    std::ostringstream out;
    out << "{\n";
    out << "  \"schema\": \"" << NAH_CONTRACT_SCHEMA << "\",\n";
 
    // app
    out << "  \"app\": {\n";
    out << "    \"id\": " << json::str(c.app.id) << ",\n";
    out << "    \"version\": " << json::str(c.app.version) << ",\n";
    out << "    \"root\": " << json::str(c.app.root) << ",\n";
    out << "    \"entrypoint\": " << json::str(c.app.entrypoint) << ",\n";
    out << "    \"package_hash\": " << json::str(c.app.package_hash) << "\n";
    out << "  },\n";
 
    // nak
    out << "  \"nak\": {\n";
    out << "    \"id\": " << json::str(c.nak.id) << ",\n";
    out << "    \"version\": " << json::str(c.nak.version) << ",\n";
    out << "    \"root\": " << json::str(c.nak.root) << ",\n";
    out << "    \"resource_root\": " << json::str(c.nak.resource_root) << ",\n";
    out << "    \"record_ref\": " << json::str(c.nak.record_ref) << ",\n";
    out << "    \"package_hash\": " << json::str(c.nak.package_hash) << "\n";
    out << "  },\n";
 
    // execution
    out << "  \"execution\": {\n";
    out << "    \"binary\": " << json::str(c.execution.binary) << ",\n";
    out << "    \"arguments\": " << json::array(c.execution.arguments, 4) << ",\n";
    out << "    \"cwd\": " << json::str(c.execution.cwd) << ",\n";
    out << "    \"library_path_env_key\": " << json::str(c.execution.library_path_env_key) << ",\n";
    out << "    \"library_paths\": " << json::array(c.execution.library_paths, 4) << "\n";
    out << "  },\n";
 
    // environment
    out << "  \"environment\": " << json::object(c.environment, 2) << ",\n";
 
    // permission requests
    out << "  \"permissions\": {\n";
    out << "    \"filesystem\": " << json::array(c.permissions.filesystem, 4) << ",\n";
    out << "    \"network\": " << json::array(c.permissions.network, 4) << "\n";
    out << "  },\n";
 
    // trust
    out << "  \"trust\": {\n";
    out << "    \"state\": " << json::str(trust_state_to_string(c.trust.state)) << ",\n";
    out << "    \"source\": " << json::str(c.trust.source) << ",\n";
    out << "    \"evaluated_at\": " << json::str(c.trust.evaluated_at) << ",\n";
    out << "    \"expires_at\": " << json::str(c.trust.expires_at) << "\n";
    out << "  }\n";
 
    out << "}";
    return out.str();
}
 
inline std::string serialize_result(const CompositionResult& r) {
    std::ostringstream out;
    out << "{\n";
    out << "  \"ok\": " << (r.ok ? "true" : "false") << ",\n";
 
    if (r.critical_error.has_value()) {
        out << "  \"critical_error\": " << json::str(critical_error_to_string(*r.critical_error)) << ",\n";
        out << "  \"critical_error_context\": " << json::str(r.critical_error_context) << ",\n";
    } else {
        out << "  \"critical_error\": null,\n";
    }
 
    // warnings
    out << "  \"warnings\": [\n";
    for (size_t i = 0; i < r.warnings.size(); i++) {
        const auto& w = r.warnings[i];
        out << "    {\n";
        out << "      \"key\": " << json::str(w.key) << ",\n";
        out << "      \"fields\": " << json::object(w.fields, 6) << "\n";
        out << "    }";
        if (i < r.warnings.size() - 1) out << ",";
        out << "\n";
    }
    out << "  ],\n";
 
    if (r.ok) {
        out << "  \"contract\": " << serialize_contract(r.contract) << "\n";
    } else {
        out << "  \"contract\": null\n";
    }
 
    out << "}";
    return out.str();
}
 
} // namespace core
} // namespace nah
 
#endif // __cplusplus
 
#endif // NAH_CORE_H