node_app_manifest/

manifest.rs

//! App manifest domain entity — unified v1/v2 schema.
//!
//! This module defines the canonical `AppManifest` used by the Node daemon to
//! discover, load, and validate mini apps. It is a backward-compatible superset
//! of the existing `PerAppManifest` (now promoted from `apps/server`).
//!
//! # Schema version detection
//!
//! - **v1** (legacy): no `manifest_version` field → `manifest_version = 1`.
//!   All v2-only fields default to their v1-equivalent values. Zero existing
//!   app manifests are invalidated.
//! - **v2** (extended): `manifest_version = 2`. Adds `abi`, `entrypoint`,
//!   `hot_reload`, and the typed `capabilities` block. Requires `abi` to be
//!   present when `manifest_version == 2`.
//!
//! # Path-safety (SEC-H3)
//!
//! `entrypoint` and `ui_path` are validated at parse time:
//! 1. Matches regex `^[a-zA-Z0-9_][a-zA-Z0-9_./-]*$`
//! 2. Contains no `..` segment
//! 3. Does not begin with `/`
//!
//! The canonicalize-inside-install-dir check (step 4) is performed by
//! `tier_validator.rs` at load time because the install directory is not known
//! until the daemon resolves the path.

use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};

// ── Enums ────────────────────────────────────────────────────────────────────

/// App execution model — determines how the daemon loads and isolates the app.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AppType {
    /// In-process cdylib loaded via dlopen. First-party path only (SEC-H1).
    Native,
    /// Isolated subprocess managed by the Bun runtime.
    Bun,
    /// Independent systemd-managed service that owns its own Unix domain socket.
    /// The daemon does not start or supervise the process; it only routes
    /// capability invocations to the app's socket as JSON-RPC 2.0.
    /// Requires a `standalone.socket_path` when the manifest declares any
    /// `provides` / `capabilities.provides` entries.
    Standalone,
    /// Packaging-only runtime dependency (for example the shared Bun runtime).
    /// It is installed and versioned like an app package but is never loaded,
    /// registered as a capability provider, or hot-reloaded as an app.
    #[serde(rename = "platform-runtime")]
    PlatformRuntime,
}

impl AppType {
    pub fn as_str(self) -> &'static str {
        match self {
            AppType::Native => "native",
            AppType::Bun => "bun",
            AppType::Standalone => "standalone",
            AppType::PlatformRuntime => "platform-runtime",
        }
    }
}

impl std::fmt::Display for AppType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

/// Trust/distribution tier — derived at load time from the install path
/// AND (per FR-028 cycle 4) the manifest sidecar's GPG signature.
///
/// This is **not** stored in the manifest; it is computed by `tier_validator`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AppTier {
    /// App installed at the bundled path (`/usr/share/node/builtin-apps/`)
    /// OR at the apt path with a manifest sidecar signed by a node project key.
    /// May be `Native` or `Bun`. Highest trust.
    FirstParty,
    /// App installed at the optional apt path (`/usr/lib/node/apps/`) with
    /// no/invalid project signature. MUST be `Bun`; `Native` at this tier
    /// triggers `TierError` (FR-028).
    Optional,
    /// App loaded from a developer's local dev directory (`NODE_DEV_APPS_DIR`),
    /// via `node-app-build dev` or manual sideload. Bypasses signature checks
    /// because the dev directory is owned by the developer (security gate is
    /// the file-system path: only the dev user can write to it). Permitted
    /// for `Native` apps so cdylib developers can iterate without per-build
    /// GPG signing.
    ///
    /// Daemon logs every Development-tier load at `info!` so operators of a
    /// real node can see when a non-prod app is active. UI badges this tier
    /// distinctly (amber/red, never green).
    Development,
}

impl AppTier {
    pub fn as_str(self) -> &'static str {
        match self {
            AppTier::FirstParty => "first_party",
            AppTier::Optional => "optional",
            AppTier::Development => "development",
        }
    }
}

impl std::fmt::Display for AppTier {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

/// Host ABI compatibility version declared by the app.
///
/// The runtime's currently supported set is `[V1]`. Apps declaring an
/// unsupported version are rejected with `AbiIncompatible` (FR-018).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum AbiVersion {
    V1,
}

impl AbiVersion {
    pub fn as_str(&self) -> &'static str {
        match self {
            AbiVersion::V1 => "v1",
        }
    }

    /// Returns true if this ABI version is supported by the current runtime.
    pub fn is_supported(&self) -> bool {
        matches!(self, AbiVersion::V1)
    }
}

impl std::fmt::Display for AbiVersion {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

/// How in-process (native) app reload is expected to behave.
///
/// Per research.md §R10, native hot-reload is inherently unreliable due to
/// `dlclose` semantics. The manifest field sets correct user expectations.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum HotReloadKind {
    /// Reload is reliable (Bun subprocess restart). Default for `Bun` apps.
    Supported,
    /// Reload attempted but may fail; expect `RequiresRestart` on failure.
    /// Default for `Native` apps (FR-024).
    Experimental,
    /// App must be restarted to pick up changes.
    Unsupported,
}

impl HotReloadKind {
    pub fn default_for(app_type: AppType) -> Self {
        match app_type {
            AppType::Native => HotReloadKind::Experimental,
            AppType::Bun => HotReloadKind::Supported,
            // Standalone apps are restarted by systemd, not the daemon —
            // from the daemon's perspective they are never hot-reloaded.
            AppType::Standalone => HotReloadKind::Unsupported,
            AppType::PlatformRuntime => HotReloadKind::Unsupported,
        }
    }
}

// ── Sub-types ─────────────────────────────────────────────────────────────────

/// Capability declarations from the v2 manifest `capabilities` block.
///
/// Semantic equivalent of the existing `permissions` + `provides` fields;
/// v2 manifests may use either or both (backward compat preserved).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ManifestCapabilities {
    /// Capabilities this app requests from the host or other apps.
    /// Format: `"core.lightning.payment.send:max=1000sat/day"` (see §1.2).
    #[serde(default)]
    pub requires: Vec<String>,

    /// Capabilities this app provides to other apps.
    /// Format: `"core.cron.register"`.
    #[serde(default)]
    pub provides: Vec<String>,
}

/// A single scope provided by an app (existing v1 model, preserved verbatim).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ProvidedScope {
    pub scope: String,
    pub description: String,
    pub resource_pattern: String,
}

/// Declarative per-endpoint access policy (existing v1 model, preserved verbatim).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EndpointPolicy {
    pub method: String,
    pub path: String,
    pub required_permissions: Vec<String>,
}

/// Capability provider declaration (existing v1 model, preserved verbatim).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProvidedCapability {
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub schema: Option<serde_json::Value>,
}

/// Configuration for `AppType::Standalone` apps.
///
/// Carried only by manifests whose `app_type == "standalone"`. The daemon uses
/// `socket_path` to route capability invocations as line-delimited JSON-RPC 2.0
/// over the standalone daemon's own Unix domain socket.
///
/// Path-safety rules (validated by `AppManifest::validate`):
/// - Absolute path.
/// - Lives under `/run/`.
/// - No `..` segments.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StandaloneConfig {
    pub socket_path: std::path::PathBuf,
}

/// Browser UI unit shipped by an app package.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AppUiKind {
    Stage,
    Widget,
}

fn default_app_ui_kind() -> AppUiKind {
    AppUiKind::Stage
}

fn default_nav_section() -> String {
    "default".to_string()
}

/// Shell-owned navigation metadata for a top-level stage.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppUiNav {
    #[serde(default = "default_nav_section")]
    pub section: String,
    #[serde(default)]
    pub order: i32,
}

/// How the client shell may behave when the home node is unavailable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AppDataOfflinePolicy {
    /// A stage may render the last verified cached projection with stale/offline labeling.
    LastKnown,
    /// A stage must fail clearly when the home node is unavailable.
    OnlineOnly,
}

/// Generic query declaration shape for app-owned cached projections.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AppDataQueryKind {
    Collection,
    Detail,
    Snapshot,
}

/// Generic stream declaration shape for app-owned invalidation/cursor feeds.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AppDataStreamKind {
    Changes,
    Events,
}

/// How the client shell refreshes app-owned data.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AppDataSyncKind {
    Cursor,
    Snapshot,
}

/// Bounded synchronization policy for generic app data.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AppDataSyncPolicy {
    pub kind: AppDataSyncKind,
    pub cursor_ttl_secs: Option<u32>,
    pub full_refresh_interval_secs: Option<u32>,
    pub retention_secs: Option<u32>,
}

impl Serialize for AppDataSyncPolicy {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct;

        if self.cursor_ttl_secs.is_none()
            && self.full_refresh_interval_secs.is_none()
            && self.retention_secs.is_none()
        {
            return self.kind.serialize(serializer);
        }

        let mut state = serializer.serialize_struct("AppDataSyncPolicy", 4)?;
        state.serialize_field("kind", &self.kind)?;
        if let Some(cursor_ttl_secs) = self.cursor_ttl_secs {
            state.serialize_field("cursor_ttl_secs", &cursor_ttl_secs)?;
        }
        if let Some(full_refresh_interval_secs) = self.full_refresh_interval_secs {
            state.serialize_field("full_refresh_interval_secs", &full_refresh_interval_secs)?;
        }
        if let Some(retention_secs) = self.retention_secs {
            state.serialize_field("retention_secs", &retention_secs)?;
        }
        state.end()
    }
}

impl<'de> Deserialize<'de> for AppDataSyncPolicy {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct ObjectPolicy {
            kind: AppDataSyncKind,
            #[serde(default)]
            cursor_ttl_secs: Option<u32>,
            #[serde(default)]
            full_refresh_interval_secs: Option<u32>,
            #[serde(default)]
            retention_secs: Option<u32>,
        }

        #[derive(Deserialize)]
        #[serde(untagged)]
        enum WirePolicy {
            Kind(AppDataSyncKind),
            Object(ObjectPolicy),
        }

        match WirePolicy::deserialize(deserializer)? {
            WirePolicy::Kind(kind) => Ok(Self {
                kind,
                cursor_ttl_secs: None,
                full_refresh_interval_secs: None,
                retention_secs: None,
            }),
            WirePolicy::Object(policy) => Ok(Self {
                kind: policy.kind,
                cursor_ttl_secs: policy.cursor_ttl_secs,
                full_refresh_interval_secs: policy.full_refresh_interval_secs,
                retention_secs: policy.retention_secs,
            }),
        }
    }
}

/// A namespaced app-owned query exposed through the generic stage data plane.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AppDataQueryDeclaration {
    pub name: String,
    pub capability: String,
    pub kind: AppDataQueryKind,
}

/// A namespaced app-owned stream exposed through the generic stage data plane.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AppDataStreamDeclaration {
    pub name: String,
    pub kind: AppDataStreamKind,
}

/// Generic, app-owned data contract declared by a stage manifest.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AppDataManifest {
    pub namespace: String,
    pub offline: AppDataOfflinePolicy,
    pub sync: AppDataSyncPolicy,
    #[serde(default)]
    pub queries: Vec<AppDataQueryDeclaration>,
    #[serde(default)]
    pub streams: Vec<AppDataStreamDeclaration>,
}

/// Capability, query, and stream contracts exposed to an app-delivered UI
/// stage. This is intentionally separate from the app's backend dependency
/// declaration (`requires` / `capabilities.requires`): backend providers may
/// need capabilities that must never be delegated to browser UI code.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct AppUiRequirements {
    #[serde(default)]
    pub capabilities: Vec<String>,
    #[serde(default)]
    pub queries: Vec<String>,
    #[serde(default)]
    pub streams: Vec<String>,
}

impl AppUiRequirements {
    /// Return the UI's complete declared contract in stable, de-duplicated
    /// order. Query and stream names are included because they are separately
    /// authorized stage declarations at the client RPC boundary.
    pub fn resolved(&self) -> Result<Vec<String>, String> {
        let mut resolved = Vec::new();
        let mut seen = HashSet::new();
        for (values, allow_wildcard) in [
            (&self.capabilities, true),
            (&self.queries, false),
            (&self.streams, false),
        ] {
            for value in values {
                let requirement = value.trim();
                if requirement.is_empty() {
                    return Err("ui.requires entries must not be blank".to_string());
                }
                validate_ui_requirement_name(requirement, allow_wildcard)
                    .map_err(|error| format!("ui.requires entry '{requirement}' invalid: {error}"))?;
                if seen.insert(requirement.to_string()) {
                    resolved.push(requirement.to_string());
                }
            }
        }
        Ok(resolved)
    }
}

/// Optional stage metadata carried by the canonical app manifest.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppUiManifest {
    #[serde(default = "default_app_ui_kind")]
    pub kind: AppUiKind,
    pub entry: String,
    pub title: String,
    #[serde(default)]
    pub icon: Option<String>,
    #[serde(default)]
    pub nav: Option<AppUiNav>,
    #[serde(default)]
    pub composes: Vec<String>,
    pub ui_api: u8,
    #[serde(default)]
    pub integrity: BTreeMap<String, String>,
    /// Stage-specific description that overrides the app-level
    /// `AppManifest::description` when the stage's UI purpose differs from the
    /// app's. Optional; when absent the app-level description is used.
    #[serde(default)]
    pub description: Option<String>,
    /// Author-supplied synonyms for this stage (search/intent phrasings).
    /// Optional; defaults to empty.
    #[serde(default)]
    pub keywords: Vec<String>,
    /// The browser stage contract. Do not populate this from the app's
    /// backend `requires` declaration.
    #[serde(default)]
    pub requires: AppUiRequirements,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<AppDataManifest>,
}

// ── Path-safety helpers ───────────────────────────────────────────────────────

/// Validate a relative file path declared in a manifest (`entrypoint`, `ui_path`).
///
/// Rules (SEC-H3):
/// 1. Matches `^[a-zA-Z0-9_][a-zA-Z0-9_./-]*$` — rejects shell metacharacters,
///    leading `.`, leading `/`, etc.
/// 2. No `..` segment anywhere.
/// 3. Does not begin with `/` (absolute paths).
///
/// Returns `Ok(())` if valid, `Err(reason)` describing the violation.
pub fn validate_manifest_path(path: &str) -> Result<(), String> {
    if path.is_empty() {
        return Err("path must not be empty".to_string());
    }

    // Rule 3: no absolute paths
    if path.starts_with('/') {
        return Err(format!(
            "path '{}' must not be absolute (starts with /)",
            path
        ));
    }

    // Rule 1: allowed character set
    // ^[a-zA-Z0-9_][a-zA-Z0-9_./-]*$
    let first = path.chars().next().unwrap();
    if !first.is_ascii_alphanumeric() && first != '_' {
        return Err(format!(
            "path '{}' must begin with an alphanumeric character or underscore",
            path
        ));
    }
    for ch in path.chars().skip(1) {
        if !ch.is_ascii_alphanumeric() && !matches!(ch, '_' | '.' | '/' | '-') {
            return Err(format!(
                "path '{}' contains disallowed character '{}'",
                path, ch
            ));
        }
    }

    // Rule 2: no `..` segment
    for segment in path.split('/') {
        if segment == ".." {
            return Err(format!(
                "path '{}' contains a '..' segment (path traversal rejected)",
                path
            ));
        }
    }

    Ok(())
}

// ── AppManifest ───────────────────────────────────────────────────────────────

/// Canonical manifest entity — unified v1/v2 format.
///
/// Deserializes both old (v1, no `manifest_version`) and new (v2) manifests.
/// All v2-only fields use `#[serde(default)]` so that v1 manifests parse
/// correctly without any field changes.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AppManifest {
    /// Schema version. Absent or 1 = legacy v1; 2 = extended v2.
    #[serde(default = "default_manifest_version", rename = "manifest_version")]
    pub manifest_version: u8,

    pub name: String,
    pub version: String,

    #[serde(default = "default_app_type_native")]
    pub app_type: AppType,

    #[serde(default)]
    pub description: String,

    // ── v2-only additions (all optional, v1-compatible defaults) ─────────────
    /// Host ABI compatibility version. Required when `manifest_version == 2`.
    pub abi: Option<AbiVersion>,

    /// Payload entry point relative to the app directory.
    /// Default: `app.so` for Native, `dist/index.js` for Bun.
    pub entrypoint: Option<String>,

    /// Hot-reload behaviour classification.
    /// Default: `experimental` for Native, `supported` for Bun.
    pub hot_reload: Option<HotReloadKind>,

    // ── Existing v1 fields (preserved verbatim — DO NOT RENAME) ──────────────
    #[serde(default)]
    pub critical: bool,

    #[serde(
        default = "default_auto_start",
        deserialize_with = "deserialize_auto_start"
    )]
    pub auto_start: bool,

    #[serde(default)]
    pub has_ui: bool,

    #[serde(default = "default_ui_path")]
    pub ui_path: String,

    #[serde(default)]
    pub permissions: Vec<String>,

    /// Capability requirements in the v2 top-level vocabulary. This is an
    /// alias for `capabilities.requires`, not a second permission system.
    #[serde(default)]
    pub requires: Vec<String>,

    #[serde(default)]
    pub optional_permissions: Vec<String>,

    #[serde(default)]
    pub provides_scopes: Vec<ProvidedScope>,

    #[serde(default)]
    pub endpoint_policies: Vec<EndpointPolicy>,

    #[serde(default)]
    pub capability_scopes: HashMap<String, String>,

    #[serde(default)]
    pub provides: HashMap<String, ProvidedCapability>,

    // ── v2 capabilities block (semantic alias for permissions + provides) ─────
    #[serde(default)]
    pub capabilities: ManifestCapabilities,

    /// App-delivered browser UI metadata. Legacy `has_ui`/`ui_path` remains
    /// readable but does not synthesize this block.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ui: Option<AppUiManifest>,

    // ── Optional metadata fields ──────────────────────────────────────────────
    #[serde(default)]
    pub author: Option<String>,

    #[serde(default)]
    pub homepage: Option<String>,

    #[serde(default)]
    pub depends_on: Option<Vec<String>>,

    #[serde(default)]
    pub boot_priority: Option<u32>,

    /// App-governor idle-termination policy (issue #811 SP1). Absent means
    /// the app is subject to the default eligibility rules with no explicit
    /// opt-out and no minimum-idle override.
    #[serde(default)]
    pub governor: Option<GovernorManifest>,

    /// Event-bus topics this app listens for while lazily started. Only
    /// meaningful for apps holding the `EVENT_LISTENER` capability — a
    /// listener with no declared `subscribes` topics is exempt from idle
    /// termination because the governor cannot know what would need to wake
    /// it back up (see `node-app-host::governor_eligibility`).
    #[serde(default)]
    pub subscribes: Vec<String>,

    /// Required when `app_type == "standalone"` and the manifest declares any
    /// `provides` / `capabilities.provides` entries. Carries the Unix domain
    /// socket path the daemon dispatches capability calls to.
    #[serde(default)]
    pub standalone: Option<StandaloneConfig>,

    /// Optional TCP-binding block — feature 470 (port registry).
    /// Absence means the app does not bind a TCP port the registry manages.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tcp: Option<TcpManifest>,
}

/// Idle-termination policy for a lazily-started app (issue #811 SP1 — the
/// app governor). Nested under `AppManifest::governor`.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct GovernorManifest {
    /// Explicit opt-out. `Some(false)` exempts the app from idle termination
    /// regardless of any other eligibility rule. `None`/`Some(true)` defers
    /// to the other eligibility rules.
    #[serde(default)]
    pub terminable: Option<bool>,

    /// Minimum idle duration, in seconds, before the governor may terminate
    /// this app — overrides the governor's default sweep threshold. `None`
    /// defers to the default.
    #[serde(default)]
    pub min_idle_secs: Option<u64>,

    /// Memory budget in KB. When the app's measured footprint — on the basis
    /// selected by its measurement attribution, see
    /// `node_app_host::app_memory::budget` — exceeds this, the owner is warned
    /// in the shell.
    ///
    /// # What `None` defers to
    ///
    /// NOT one number. The default is chosen PER BASIS
    /// (`node_app_host::app_memory::budget::default_budget_kb`), because the
    /// bases are not comparable quantities:
    ///
    /// | basis                | default   | why                                     |
    /// |----------------------|-----------|-----------------------------------------|
    /// | `heap_used`, `pss`   | 10,240 KB | the app and nothing else                |
    /// | `rss`                | 61,440 KB | the whole OS process, runtime included  |
    /// | `not_attributable`   | 10,240 KB | never `over`; carried only for the wire |
    ///
    /// A shared-runtime Bun worker is compared on `heap_used`; a dedicated
    /// process or cgroup-scoped standalone on `rss`, which charges it for a
    /// JavaScript engine it did not choose and cannot shed.
    ///
    /// On top of that, a host-side runtime-critical entry
    /// (`RUNTIME_CRITICAL_BUDGETS`) acts as a FLOOR, never a ceiling: it can
    /// only raise an app above the per-basis default, never pull it below one.
    ///
    /// A value declared HERE is the one thing that overrides both, in either
    /// direction — it is a deliberate choice by the app author, not a fallback,
    /// so it is honoured unchanged even when it is lower than the default.
    ///
    /// Apps that legitimately need more than their basis default MUST declare a
    /// realistic budget here; otherwise the warning is permanently lit and
    /// stops meaning anything.
    #[serde(default)]
    pub memory_budget_kb: Option<u64>,
}

/// TCP port preferences for standalone apps that bind their own port.
/// Consumed by the port registry (`system/server/src/services/port_registry/`)
/// at install time.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct TcpManifest {
    /// The TCP port the app would like to bind. Honored when free;
    /// otherwise the registry assigns the next free port from the pool
    /// (default 7000–7099). Absent → registry picks any free pool slot.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preferred_port: Option<u16>,

    /// When `true`, the platform UI shell builds iframe URLs as direct LAN
    /// connections to the assigned port rather than routing via the
    /// `/api/v2/node-apps/{name}/ui/` reverse-proxy. Intended only for apps
    /// that must outlive a platform restart (e.g. OTA self-upgrade). Remote
    /// users may see a degraded experience — owned by the consuming app's UI,
    /// not this spec (see `specs/470-port-registry/spec.md` Clarifications Q5b).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub direct_bind: Option<bool>,
}

fn default_manifest_version() -> u8 {
    1
}

fn default_auto_start() -> bool {
    true
}

/// Deserialize `auto_start` from either a bool (manifest v1) or a load-mode
/// string (v2, e.g. `"lazy"`/`"eager"`/`"active"`). Eager-start modes map to
/// `true`; `"lazy"` and other on-demand/inactive states map to `false` (the app
/// is started on first capability use, not at boot). This keeps both manifest
/// schema generations parseable by `AppManifest::from_json`.
fn deserialize_auto_start<'de, D>(deserializer: D) -> Result<bool, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum BoolOrStr {
        Bool(bool),
        Str(String),
    }
    Ok(match BoolOrStr::deserialize(deserializer)? {
        BoolOrStr::Bool(b) => b,
        BoolOrStr::Str(s) => matches!(
            s.trim().to_ascii_lowercase().as_str(),
            "true" | "eager" | "active" | "auto" | "on" | "1"
        ),
    })
}

fn default_ui_path() -> String {
    "dist".to_string()
}

fn default_app_type_native() -> AppType {
    AppType::Native
}

impl AppManifest {
    /// Resolve top-level `requires` and `capabilities.requires` into one
    /// canonical declaration list. Equal aliases are accepted regardless of
    /// order or duplicates; differing aliases are rejected.
    pub fn resolved_requires(&self) -> Result<Vec<String>, String> {
        let top = normalized_requirements(&self.requires)?;
        let nested = normalized_requirements(&self.capabilities.requires)?;
        if !top.is_empty()
            && !nested.is_empty()
            && top.iter().cloned().collect::<BTreeSet<_>>()
                != nested.iter().cloned().collect::<BTreeSet<_>>()
        {
            return Err("top-level 'requires' conflicts with 'capabilities.requires'".to_string());
        }
        Ok(if !top.is_empty() { top } else { nested })
    }

    /// Returns the effective `HotReloadKind` — explicit field or the default
    /// for the app type.
    pub fn effective_hot_reload(&self) -> HotReloadKind {
        self.hot_reload
            .unwrap_or_else(|| HotReloadKind::default_for(self.app_type))
    }

    /// Returns the effective entrypoint — explicit field or the type-specific default.
    ///
    /// Standalone apps have no daemon-managed entrypoint (systemd owns the
    /// lifecycle); the empty string signals "not applicable".
    pub fn effective_entrypoint(&self) -> &str {
        if let Some(ref ep) = self.entrypoint {
            ep.as_str()
        } else {
            match self.app_type {
                AppType::Native => "app.so",
                AppType::Bun => "dist/index.js",
                AppType::Standalone => "",
                AppType::PlatformRuntime => "bun",
            }
        }
    }

    /// True iff this manifest declares at least one capability provider
    /// (via either the v1 `provides` map or the v2 `capabilities.provides` list).
    pub fn has_capability_providers(&self) -> bool {
        !self.provides.is_empty() || !self.capabilities.provides.is_empty()
    }

    /// Merges the v1 `provides` map and the v2 `capabilities.provides` name
    /// list into a single capability→declaration map (composition-root
    /// cleanup Round 4 T28 — extracted from
    /// `control_ipc::handlers::handle_app_register_standalone`, which uses
    /// this to shape a standalone app's declared providers for capability
    /// registration).
    ///
    /// - v1 entries (the `provides` map) carry their real
    ///   description/schema and always win on a name conflict.
    /// - v2-only names (declared only via `capabilities.provides`, format
    ///   `"name"` or `"name:extra"` — only the part before the first `:` is
    ///   used) get a blank declaration, inserted only if the name is not
    ///   already present from v1. Blank/whitespace-only names are skipped.
    pub fn resolved_capability_provides(&self) -> HashMap<String, ProvidedCapability> {
        let mut out: HashMap<String, ProvidedCapability> = self.provides.clone();
        for raw in &self.capabilities.provides {
            let name = raw.split(':').next().unwrap_or(raw).trim().to_string();
            if name.is_empty() {
                continue;
            }
            out.entry(name).or_insert(ProvidedCapability {
                description: String::new(),
                schema: None,
            });
        }
        out
    }

    /// Validate the manifest for structural correctness.
    ///
    /// Returns `Ok(())` on success, or a human-readable error string.
    /// Called by the manifest parser after deserialization.
    pub fn validate(&self) -> Result<(), String> {
        self.validate_with_socket_path_policy(false)
    }

    /// Validate this manifest with an explicit standalone socket-path policy.
    ///
    /// Runtime adapters may opt into non-`/run` paths for development without
    /// making the domain model read process configuration.
    pub fn validate_with_socket_path_policy(&self, allow_non_run: bool) -> Result<(), String> {
        // v2 requires abi field
        if self.manifest_version == 2 && self.abi.is_none() {
            return Err("manifest_version 2 requires an 'abi' field".to_string());
        }

        // Name validation: ^[a-z][a-z0-9-]*(/([a-z][a-z0-9-]*))?$
        // (publisher/name form accepted but not yet semantically used — FR-019)
        validate_app_name(&self.name)?;
        self.resolved_requires()?;

        // Path-safety on entrypoint and ui_path
        if let Some(ref ep) = self.entrypoint {
            validate_manifest_path(ep).map_err(|e| format!("entrypoint invalid: {}", e))?;
        }
        // ui_path is only meaningful when has_ui is true, but validate always
        if !self.ui_path.is_empty() && self.ui_path != "dist" {
            validate_manifest_path(&self.ui_path).map_err(|e| format!("ui_path invalid: {}", e))?;
        }

        if let Some(ui) = &self.ui {
            validate_app_ui(&self.name, ui)?;
        }

        // Homepage scheme validation (if present)
        if let Some(ref hp) = self.homepage {
            if !hp.starts_with("https://") && !hp.starts_with("http://") {
                return Err(format!(
                    "homepage '{}' must use https:// or http:// scheme",
                    hp
                ));
            }
        }

        // Standalone-app rules:
        // - When `app_type == "standalone"` AND the manifest declares any
        //   capability providers, `standalone.socket_path` is required and
        //   must be an absolute path under `/run/` with no `..` segments.
        // - Non-standalone manifests MUST NOT carry a `standalone` block
        //   (rejected to surface accidental schema misuse).
        match self.app_type {
            AppType::Standalone => {
                if self.has_capability_providers() {
                    let cfg = self.standalone.as_ref().ok_or_else(|| {
                        "standalone apps that declare 'provides' require a \
                         'standalone.socket_path' field"
                            .to_string()
                    })?;
                    validate_standalone_socket_path_with_policy(&cfg.socket_path, allow_non_run)?;
                }
            }
            AppType::Native | AppType::Bun | AppType::PlatformRuntime => {
                if self.standalone.is_some() {
                    return Err(format!(
                        "'standalone' block is only valid when app_type == 'standalone' \
                         (found app_type='{}')",
                        self.app_type
                    ));
                }
            }
        }

        if self.app_type == AppType::PlatformRuntime
            && !self.resolved_capability_provides().is_empty()
        {
            return Err(
                "platform-runtime packages cannot provide runtime capabilities".to_string(),
            );
        }

        Ok(())
    }

    /// Parse from a JSON string, validate, and return the manifest.
    pub fn from_json(json: &str) -> Result<Self, String> {
        Self::from_json_with_socket_path_policy(json, false)
    }

    /// Parse and validate with an explicit standalone socket-path policy.
    pub fn from_json_with_socket_path_policy(
        json: &str,
        allow_non_run: bool,
    ) -> Result<Self, String> {
        let mut manifest: Self =
            serde_json::from_str(json).map_err(|e| format!("manifest JSON parse error: {}", e))?;
        if manifest.ui.is_some() {
            manifest.has_ui = true;
        }
        manifest.validate_with_socket_path_policy(allow_non_run)?;
        Ok(manifest)
    }
}

fn normalized_requirements(values: &[String]) -> Result<Vec<String>, String> {
    let mut seen = HashSet::new();
    let mut resolved = Vec::new();
    for value in values {
        let requirement = value.trim();
        if requirement.is_empty() {
            return Err("capability requirements must not be blank".to_string());
        }
        if seen.insert(requirement.to_string()) {
            resolved.push(requirement.to_string());
        }
    }
    Ok(resolved)
}

fn validate_app_ui(
    app_name: &str,
    ui: &AppUiManifest,
) -> Result<(), String> {
    if ui.ui_api != 1 && ui.ui_api != 2 {
        return Err(format!(
            "ui.ui_api {} is unsupported; only versions 1 and 2 are supported",
            ui.ui_api
        ));
    }
    if ui.title.trim().is_empty() {
        return Err("ui.title must not be blank".to_string());
    }
    ui.requires.resolved()?;
    validate_manifest_path(&ui.entry).map_err(|error| format!("ui.entry invalid: {error}"))?;
    if let Some(icon) = &ui.icon {
        validate_manifest_path(icon).map_err(|error| format!("ui.icon invalid: {error}"))?;
    }
    if let Some(nav) = &ui.nav {
        if ui.kind == AppUiKind::Widget {
            return Err("widget ui must omit nav metadata".to_string());
        }
        if nav.section.trim().is_empty() {
            return Err("ui.nav.section must not be blank".to_string());
        }
    }
    if let Some(data) = &ui.data {
        if ui.kind != AppUiKind::Stage {
            return Err("widget ui must omit app data declarations".to_string());
        }
        validate_app_data(data, &ui.requires.resolved()?)?;
    }

    let mut composed = HashSet::new();
    for name in &ui.composes {
        validate_app_name(name).map_err(|error| format!("ui.composes entry invalid: {error}"))?;
        if name == app_name {
            return Err("ui.composes must not contain the app itself".to_string());
        }
        if !composed.insert(name) {
            return Err(format!("ui.composes contains duplicate app '{name}'"));
        }
    }

    for (path, digest) in &ui.integrity {
        validate_manifest_path(path)
            .map_err(|error| format!("ui.integrity path invalid: {error}"))?;
        if !is_lowercase_sha256(digest) {
            return Err(format!(
                "ui.integrity digest for '{path}' must be a lowercase 64-character SHA-256"
            ));
        }
    }
    if !ui.integrity.contains_key(&ui.entry) {
        return Err("ui.integrity must include the declared entry".to_string());
    }
    if let Some(icon) = &ui.icon {
        if !ui.integrity.contains_key(icon) {
            return Err("ui.integrity must include the declared icon".to_string());
        }
    }
    Ok(())
}

fn validate_app_data(data: &AppDataManifest, resolved_requires: &[String]) -> Result<(), String> {
    validate_app_data_namespace(&data.namespace)?;
    validate_app_data_sync_policy(&data.sync)?;
    if data.queries.is_empty() {
        return Err("ui.data.queries must declare at least one query".to_string());
    }

    let requires: BTreeSet<&str> = resolved_requires.iter().map(String::as_str).collect();
    let mut names = BTreeSet::new();
    for query in &data.queries {
        validate_namespaced_data_name(&query.name, &data.namespace)
            .map_err(|error| format!("ui.data query '{}' invalid: {error}", query.name))?;
        validate_capability_name(&query.capability).map_err(|error| {
            format!(
                "ui.data query '{}' capability '{}' invalid: {error}",
                query.name, query.capability
            )
        })?;
        if !requires.contains(query.capability.as_str()) {
            return Err(format!(
                "ui.data query '{}' capability '{}' must be declared in requires",
                query.name, query.capability
            ));
        }
        if !names.insert(query.name.as_str()) {
            return Err(format!("ui.data contains duplicate query '{}'", query.name));
        }
    }

    for stream in &data.streams {
        validate_namespaced_data_name(&stream.name, &data.namespace)
            .map_err(|error| format!("ui.data stream '{}' invalid: {error}", stream.name))?;
        if !names.insert(stream.name.as_str()) {
            return Err(format!(
                "ui.data contains duplicate declaration '{}'",
                stream.name
            ));
        }
    }

    Ok(())
}

fn validate_app_data_namespace(namespace: &str) -> Result<(), String> {
    if !is_safe_name_segment(namespace) {
        return Err(format!(
            "ui.data namespace '{}' must match [a-z][a-z0-9-]*",
            namespace
        ));
    }
    if matches!(
        namespace,
        "core" | "internal" | "node" | "platform" | "system"
    ) {
        return Err(format!("ui.data namespace '{namespace}' is reserved"));
    }
    Ok(())
}

fn validate_app_data_sync_policy(sync: &AppDataSyncPolicy) -> Result<(), String> {
    validate_optional_range("cursor_ttl_secs", sync.cursor_ttl_secs, 60, 86_400)?;
    validate_optional_range(
        "full_refresh_interval_secs",
        sync.full_refresh_interval_secs,
        60,
        604_800,
    )?;
    validate_optional_range("retention_secs", sync.retention_secs, 300, 31_536_000)?;
    if sync.kind == AppDataSyncKind::Snapshot && sync.cursor_ttl_secs.is_some() {
        return Err("ui.data.sync cursor_ttl_secs is only valid for cursor sync".to_string());
    }
    Ok(())
}

fn validate_optional_range(
    field: &str,
    value: Option<u32>,
    min: u32,
    max: u32,
) -> Result<(), String> {
    if let Some(value) = value {
        if value < min || value > max {
            return Err(format!(
                "ui.data.sync {field} must be between {min} and {max} seconds"
            ));
        }
    }
    Ok(())
}

fn validate_namespaced_data_name(name: &str, namespace: &str) -> Result<(), String> {
    validate_capability_name(name)?;
    let Some(rest) = name
        .strip_prefix(namespace)
        .and_then(|suffix| suffix.strip_prefix('.'))
    else {
        return Err(format!("name must use namespace '{namespace}'"));
    };
    if rest.is_empty() {
        return Err("name must include a value after its namespace".to_string());
    }
    if !has_version_suffix(name) {
        return Err("name must end with a .vN version suffix".to_string());
    }
    Ok(())
}

fn validate_capability_name(name: &str) -> Result<(), String> {
    if name.is_empty() {
        return Err("name must not be empty".to_string());
    }
    if name.contains('/') || name.contains("..") {
        return Err("name must not contain path separators or traversal".to_string());
    }
    if !name.split('.').all(is_safe_declaration_segment) {
        return Err("name must contain only lowercase dot-separated segments".to_string());
    }
    Ok(())
}

fn validate_ui_requirement_name(name: &str, allow_wildcard: bool) -> Result<(), String> {
    if allow_wildcard && name.ends_with(".*") {
        return validate_capability_name(&name[..name.len() - 2]);
    }
    validate_capability_name(name)
}

fn has_version_suffix(name: &str) -> bool {
    let Some(version) = name.rsplit('.').next() else {
        return false;
    };
    let Some(digits) = version.strip_prefix('v') else {
        return false;
    };
    !digits.is_empty()
        && !digits.starts_with('0')
        && digits.bytes().all(|byte| byte.is_ascii_digit())
}

fn is_safe_name_segment(segment: &str) -> bool {
    if segment.is_empty() {
        return false;
    }
    let mut chars = segment.chars();
    let Some(first) = chars.next() else {
        return false;
    };
    first.is_ascii_lowercase()
        && chars.all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '-')
}

/// A segment of a capability, query, or stream name.
///
/// Deliberately looser than [`is_safe_name_segment`] by exactly one character:
/// `_`. Capability actions in this codebase are snake_case almost without
/// exception (`core.lightning.create_invoice`, `core.did.current_did`,
/// `contest.world.studio_state`), and app-event resources are too
/// (`app.agent_session` — `APP_EVENT_RESOURCE_PATTERN` in `@econ-v1/domain`
/// admits `_` for precisely these). Rejecting `_` here did not make a stage
/// safer, it made `ui.requires` unusable: a stage that declared any real
/// capability failed `resolved()`, and `build_ui_stage_catalog` then dropped
/// that stage from the shell entirely. The characters that actually matter —
/// path separators, traversal, uppercase, leading digits — are still refused.
fn is_safe_declaration_segment(segment: &str) -> bool {
    let mut chars = segment.chars();
    let Some(first) = chars.next() else {
        return false;
    };
    first.is_ascii_lowercase()
        && chars.all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '-' || ch == '_')
}

fn is_lowercase_sha256(value: &str) -> bool {
    value.len() == 64
        && value
            .bytes()
            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}

/// Validate a `StandaloneConfig::socket_path`.
///
/// Rules:
/// 1. Absolute path (starts with `/`).
/// 2. Lives under `/run/` (rejects `/etc/...`, `/tmp/...`, etc. — pins the
///    socket to a tmpfs path predictably writable by the standalone daemon).
///    Runtime adapters can explicitly bypass this restriction for development.
/// 3. No `..` segments anywhere in the path.
pub fn validate_standalone_socket_path(path: &std::path::Path) -> Result<(), String> {
    validate_standalone_socket_path_with_policy(path, false)
}

/// Validate a standalone socket path with an explicit runtime policy.
pub fn validate_standalone_socket_path_with_policy(
    path: &std::path::Path,
    allow_non_run: bool,
) -> Result<(), String> {
    if !path.is_absolute() {
        return Err(format!(
            "standalone.socket_path '{}' must be absolute",
            path.display()
        ));
    }
    if !allow_non_run && !path.starts_with("/run/") {
        return Err(format!(
            "standalone.socket_path '{}' must live under /run/",
            path.display()
        ));
    }
    if path
        .components()
        .any(|c| matches!(c, std::path::Component::ParentDir))
    {
        return Err(format!(
            "standalone.socket_path '{}' must not contain '..' segments",
            path.display()
        ));
    }
    Ok(())
}

/// Validate an app name string.
///
/// Accepts `app-name` (simple) and `publisher/app-name` (publisher-prefixed, FR-019).
fn validate_app_name(name: &str) -> Result<(), String> {
    let (publisher, app) = if let Some(slash) = name.find('/') {
        let (p, rest) = name.split_at(slash);
        (Some(p), &rest[1..])
    } else {
        (None, name)
    };

    let valid_segment = |s: &str| -> bool {
        if s.is_empty() {
            return false;
        }
        let mut chars = s.chars();
        let first = chars.next().unwrap();
        if !first.is_ascii_lowercase() {
            return false;
        }
        chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
    };

    if let Some(pub_name) = publisher {
        if !valid_segment(pub_name) {
            return Err(format!(
                "publisher segment '{}' must match [a-z][a-z0-9-]*",
                pub_name
            ));
        }
    }

    if !valid_segment(app) {
        return Err(format!(
            "app name segment '{}' must match [a-z][a-z0-9-]*",
            app
        ));
    }

    Ok(())
}

// ── Tests ─────────────────────────────────────────────────────────────────────

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

    fn parse_ok(json: &str) -> AppManifest {
        AppManifest::from_json(json).expect("should parse")
    }

    fn parse_err(json: &str) -> String {
        AppManifest::from_json(json).expect_err("should fail")
    }

    // ── v1 manifests ──────────────────────────────────────────────────────────

    #[test]
    fn v1_minimal_native() {
        let m = parse_ok(r#"{"name":"cron","version":"1.0.0","app_type":"native"}"#);
        assert_eq!(m.manifest_version, 1);
        assert_eq!(m.app_type, AppType::Native);
        assert!(m.abi.is_none());
    }

    #[test]
    fn v1_minimal_bun() {
        let m = parse_ok(r#"{"name":"my-app","version":"0.1.0","app_type":"bun"}"#);
        assert_eq!(m.app_type, AppType::Bun);
        assert_eq!(m.effective_entrypoint(), "dist/index.js");
    }

    #[test]
    fn v1_no_manifest_version_field_defaults_to_1() {
        let m = parse_ok(r#"{"name":"example","version":"1.0.0","app_type":"bun"}"#);
        assert_eq!(m.manifest_version, 1);
    }

    #[test]
    fn v1_all_optional_fields_missing() {
        let m = parse_ok(r#"{"name":"example","version":"1.0.0","app_type":"bun"}"#);
        assert!(!m.critical);
        assert!(m.auto_start);
        assert!(!m.has_ui);
        assert_eq!(m.ui_path, "dist");
        assert!(m.permissions.is_empty());
        assert!(m.optional_permissions.is_empty());
        // #1556: governor/subscribes absent → today's implicit behavior
        // (no opt-out, no min-idle override, no declared subscriptions).
        assert!(m.governor.is_none());
        assert!(m.subscribes.is_empty());
    }

    #[test]
    fn v1_with_permissions_and_provides() {
        let json = r#"{
            "name": "example",
            "version": "1.0.0",
            "app_type": "bun",
            "permissions": ["core.storage.kv"],
            "optional_permissions": ["core.notifications.create"],
            "provides": {
                "core.example.run": { "description": "Run example job" }
            }
        }"#;
        let m = parse_ok(json);
        assert_eq!(m.permissions, vec!["core.storage.kv"]);
        assert_eq!(m.optional_permissions, vec!["core.notifications.create"]);
        assert!(m.provides.contains_key("core.example.run"));
    }

    // ── v2 manifests ──────────────────────────────────────────────────────────

    #[test]
    fn v2_minimal_native() {
        let json = r#"{
            "manifest_version": 2,
            "name": "cron",
            "version": "1.0.0",
            "app_type": "native",
            "abi": "v1",
            "entrypoint": "app.so",
            "hot_reload": "experimental"
        }"#;
        let m = parse_ok(json);
        assert_eq!(m.manifest_version, 2);
        assert_eq!(m.abi, Some(AbiVersion::V1));
        assert_eq!(m.entrypoint.as_deref(), Some("app.so"));
        assert_eq!(m.hot_reload, Some(HotReloadKind::Experimental));
    }

    #[test]
    fn v2_minimal_bun_with_capabilities() {
        let json = r#"{
            "manifest_version": 2,
            "name": "example-fullstack",
            "version": "1.0.0",
            "app_type": "bun",
            "abi": "v1",
            "entrypoint": "dist/index.js",
            "hot_reload": "supported",
            "has_ui": true,
            "ui_path": "ui/dist",
            "capabilities": {
                "requires": ["core.storage.kv", "core.lightning.payment.send:max=500sat/day"],
                "provides": []
            },
            "governor": { "terminable": false, "min_idle_secs": 300 },
            "subscribes": ["core.chat.message.received"]
        }"#;
        let m = parse_ok(json);
        assert_eq!(m.manifest_version, 2);
        assert_eq!(m.capabilities.requires.len(), 2);
        // #1556: governor/subscribes present → parsed through verbatim.
        let governor = m.governor.expect("governor block should parse");
        assert_eq!(governor.terminable, Some(false));
        assert_eq!(governor.min_idle_secs, Some(300));
        assert_eq!(m.subscribes, vec!["core.chat.message.received"]);
    }

    #[test]
    fn stage_contract_fixture_parses_with_normalized_requirements() {
        let json = include_str!(
            "../../../specs/456-node-app-distribution-infrastructure/contracts/fixtures/stage-manifest-v2.json"
        );
        let m = parse_ok(json);
        assert!(m.has_ui);
        assert_eq!(m.resolved_requires().unwrap(), vec!["core.metrics.latest"]);
        let ui = m.ui.expect("fixture should declare ui");
        assert_eq!(ui.kind, AppUiKind::Stage);
        assert_eq!(ui.entry, "ui/main.js");
        assert_eq!(ui.nav.unwrap().order, 10);
    }

    #[test]
    fn omitted_ui_keeps_legacy_flags_without_fabricating_a_stage() {
        let m = parse_ok(
            r#"{"name":"legacy","version":"1.0.0","app_type":"bun","has_ui":true,"ui_path":"ui/dist"}"#,
        );
        assert!(m.has_ui);
        assert_eq!(m.ui_path, "ui/dist");
        assert!(m.ui.is_none());
    }

    #[test]
    fn ui_requirements_are_typed_serialized_and_separate_from_backend_requires() {
        let manifest = parse_ok(
            r#"{
                "name":"ui-contract","version":"1.0.0","app_type":"bun",
                "requires":["core.cron.register"],
                "ui":{
                    "kind":"stage","entry":"ui/main.js","title":"UI contract","ui_api":1,
                    "requires":{
                        "capabilities":["ui.snapshot.v1"],
                        "queries":["ui.query.v1"],
                        "streams":["ui.event.v1"]
                    },
                    "integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
                }
            }"#,
        );

        assert_eq!(manifest.resolved_requires().unwrap(), vec!["core.cron.register"]);
        let ui = manifest.ui.as_ref().expect("ui requirements should parse");
        assert_eq!(ui.requires.capabilities, vec!["ui.snapshot.v1"]);
        assert_eq!(ui.requires.queries, vec!["ui.query.v1"]);
        assert_eq!(ui.requires.streams, vec!["ui.event.v1"]);
        assert_eq!(
            ui.requires.resolved().unwrap(),
            vec!["ui.snapshot.v1", "ui.query.v1", "ui.event.v1"]
        );
        let serialized = serde_json::to_value(ui).unwrap();
        assert_eq!(serialized["requires"]["queries"], serde_json::json!(["ui.query.v1"]));
    }

    #[test]
    fn ui_requirements_reject_blank_entries() {
        let error = parse_err(
            r#"{
                "name":"ui-contract","version":"1.0.0","app_type":"bun",
                "ui":{
                    "kind":"stage","entry":"ui/main.js","title":"UI contract","ui_api":1,
                    "requires":{"capabilities":[""],"queries":[],"streams":[]},
                    "integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
                }
            }"#,
        );
        assert!(error.contains("ui.requires entries must not be blank"));
    }

    #[test]
    fn ui_data_namespace_stays_hyphen_only_when_declarations_allow_underscore() {
        // `is_safe_declaration_segment` deliberately admits `_` so `ui.requires`
        // can name real capabilities. `ui.data.namespace` is a different thing —
        // a storage key, contract `[a-z][a-z0-9-]*` — and keeps the stricter
        // `is_safe_name_segment`. Nothing else pins that separation, so a future
        // refactor collapsing the two predicates back together would silently
        // widen the namespace rule. This is the tripwire for that.
        assert!(validate_app_data_namespace("obs-viewer").is_ok());

        let error = validate_app_data_namespace("obs_viewer")
            .expect_err("underscore must not be admitted into a storage namespace");
        assert!(
            error.contains("must match [a-z][a-z0-9-]*"),
            "unexpected error: {error}"
        );
    }

    #[test]
    fn ui_data_query_capability_does_not_fall_back_to_backend_requires() {
        let error = parse_err(
            r#"{
                "name":"ui-data","version":"1.0.0","app_type":"bun",
                "requires":["ui.snapshot.v1"],
                "ui":{
                    "kind":"stage","entry":"ui/main.js","title":"UI data","ui_api":1,
                    "requires":{"capabilities":[],"queries":[],"streams":[]},
                    "integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},
                    "data":{
                        "namespace":"ui-data","offline":"last-known","sync":{"kind":"cursor"},
                        "queries":[{"name":"ui-data.snapshot.v1","capability":"ui.snapshot.v1","kind":"snapshot"}],
                        "streams":[]
                    }
                }
            }"#,
        );
        assert!(error.contains("must be declared in requires"));
    }

    #[test]
    fn top_level_and_nested_requires_must_resolve_to_the_same_set() {
        let accepted = parse_ok(
            r#"{
                "name":"aliases","version":"1.0.0","app_type":"bun",
                "requires":["core.chat.read","core.chat.read","core.chat.send"],
                "capabilities":{"requires":["core.chat.send","core.chat.read"]}
            }"#,
        );
        assert_eq!(
            accepted.resolved_requires().unwrap(),
            vec!["core.chat.read", "core.chat.send"]
        );

        let err = parse_err(
            r#"{
                "name":"aliases","version":"1.0.0","app_type":"bun",
                "requires":["core.chat.read"],
                "capabilities":{"requires":["core.wallet.pay"]}
            }"#,
        );
        assert!(err.contains("conflicts"), "unexpected error: {err}");
    }

    #[test]
    fn stage_and_widget_ui_kinds_have_distinct_navigation_rules() {
        let base = |ui: &str| {
            format!(r#"{{"name":"stage","version":"1.0.0","app_type":"bun","ui":{ui}}}"#)
        };
        let widget = base(
            r#"{"kind":"widget","entry":"ui/main.js","title":"Stage","ui_api":1,"integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}"#,
        );
        assert_eq!(
            parse_ok(&widget).ui.expect("widget ui").kind,
            AppUiKind::Widget
        );
        let widget_nav = base(
            r#"{"kind":"widget","entry":"ui/main.js","title":"Widget","nav":{"section":"default","order":1},"ui_api":1,"integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}"#,
        );
        assert!(parse_err(&widget_nav).contains("must omit nav"));
        let api = base(
            r#"{"kind":"stage","entry":"ui/main.js","title":"Stage","ui_api":2,"integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}"#,
        );
        assert_eq!(parse_ok(&api).ui.expect("v2 stage ui").ui_api, 2);
        let unsupported_api = base(
            r#"{"kind":"stage","entry":"ui/main.js","title":"Stage","ui_api":3,"integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}"#,
        );
        assert!(parse_err(&unsupported_api).contains("ui_api"));
        let path = base(
            r#"{"kind":"stage","entry":"../main.js","title":"Stage","ui_api":1,"integrity":{"../main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}"#,
        );
        assert!(parse_err(&path).contains("entry"));
    }

    #[test]
    fn stage_requires_integrity_for_entry_and_icon() {
        let missing_entry = r#"{
            "name":"stage","version":"1.0.0","app_type":"bun",
            "ui":{"entry":"ui/main.js","title":"Stage","ui_api":1,"integrity":{}}
        }"#;
        assert!(parse_err(missing_entry).contains("entry"));
        let missing_icon = r#"{
            "name":"stage","version":"1.0.0","app_type":"bun",
            "ui":{"entry":"ui/main.js","icon":"ui/icon.svg","title":"Stage","ui_api":1,
            "integrity":{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}
        }"#;
        assert!(parse_err(missing_icon).contains("icon"));
        let uppercase = r#"{
            "name":"stage","version":"1.0.0","app_type":"bun",
            "ui":{"entry":"ui/main.js","title":"Stage","ui_api":1,
            "integrity":{"ui/main.js":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}}
        }"#;
        assert!(parse_err(uppercase).contains("lowercase"));
    }

    #[test]
    fn stage_composes_rejects_self_duplicate_and_unsafe_names() {
        let manifest = |composes: &str| {
            format!(
                r#"{{
                    "name":"stage","version":"1.0.0","app_type":"bun",
                    "ui":{{"entry":"ui/main.js","title":"Stage","ui_api":1,
                    "composes":{composes},
                    "integrity":{{"ui/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}
                }}"#
            )
        };
        assert!(parse_err(&manifest(r#"["stage"]"#)).contains("itself"));
        assert!(parse_err(&manifest(r#"["chat","chat"]"#)).contains("duplicate"));
        assert!(parse_err(&manifest(r#"["../chat"]"#)).contains("invalid"));
    }

    #[test]
    fn v2_missing_abi_is_error() {
        let json = r#"{
            "manifest_version": 2,
            "name": "example",
            "version": "1.0.0",
            "app_type": "bun"
        }"#;
        let err = parse_err(json);
        assert!(err.contains("abi"), "expected abi error, got: {}", err);
    }

    // ── Publisher-prefixed name (FR-019) ──────────────────────────────────────

    #[test]
    fn publisher_prefixed_name_accepted() {
        let m = parse_ok(r#"{"name":"alice/weather","version":"1.0.0","app_type":"bun"}"#);
        assert_eq!(m.name, "alice/weather");
    }

    #[test]
    fn double_slash_name_rejected() {
        let err = parse_err(r#"{"name":"a/b/c","version":"1.0.0","app_type":"bun"}"#);
        assert!(!err.is_empty());
    }

    // ── Malformed names ───────────────────────────────────────────────────────

    #[test]
    fn name_starting_with_digit_rejected() {
        let err = parse_err(r#"{"name":"1bad","version":"1.0.0","app_type":"bun"}"#);
        assert!(!err.is_empty());
    }

    #[test]
    fn name_with_uppercase_rejected() {
        let err = parse_err(r#"{"name":"MyApp","version":"1.0.0","app_type":"bun"}"#);
        assert!(!err.is_empty());
    }

    #[test]
    fn empty_name_rejected() {
        let err = parse_err(r#"{"name":"","version":"1.0.0","app_type":"bun"}"#);
        assert!(!err.is_empty());
    }

    // ── Path-safety (SEC-H3) ─────────────────────────────────────────────────

    #[test]
    fn path_traversal_double_dot_rejected() {
        let json = r#"{
            "manifest_version": 2, "name": "evil", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "entrypoint": "../etc/passwd"
        }"#;
        let err = parse_err(json);
        assert!(err.contains(".."), "expected traversal error, got: {}", err);
    }

    #[test]
    fn path_traversal_encoded_dot_not_decoded() {
        // The regex rejects '%' so encoded traversal fails at char check
        let json = r#"{
            "manifest_version": 2, "name": "evil", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "entrypoint": "foo/../bar"
        }"#;
        let err = parse_err(json);
        assert!(!err.is_empty(), "should have failed: {}", err);
    }

    #[test]
    fn absolute_path_rejected() {
        let json = r#"{
            "manifest_version": 2, "name": "evil", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "entrypoint": "/usr/bin/sh"
        }"#;
        let err = parse_err(json);
        assert!(
            err.contains("absolute"),
            "expected absolute error, got: {}",
            err
        );
    }

    #[test]
    fn shell_metachar_in_path_rejected() {
        let json = r#"{
            "manifest_version": 2, "name": "evil", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "entrypoint": "dist/index.js;rm -rf /"
        }"#;
        let err = parse_err(json);
        assert!(!err.is_empty());
    }

    #[test]
    fn valid_nested_path_accepted() {
        let json = r#"{
            "manifest_version": 2, "name": "my-app", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "entrypoint": "dist/index.js",
            "ui_path": "ui/dist"
        }"#;
        parse_ok(json);
    }

    // ── Homepage scheme ───────────────────────────────────────────────────────

    #[test]
    fn homepage_https_accepted() {
        let json = r#"{
            "name": "my-app", "version": "1.0.0", "app_type": "bun",
            "homepage": "https://example.com"
        }"#;
        parse_ok(json);
    }

    #[test]
    fn homepage_javascript_scheme_rejected() {
        let json = r#"{
            "name": "my-app", "version": "1.0.0", "app_type": "bun",
            "homepage": "javascript:alert(1)"
        }"#;
        let err = parse_err(json);
        assert!(
            err.contains("scheme"),
            "expected scheme error, got: {}",
            err
        );
    }

    #[test]
    fn homepage_file_scheme_rejected() {
        let json = r#"{
            "name": "my-app", "version": "1.0.0", "app_type": "bun",
            "homepage": "file:///etc/passwd"
        }"#;
        let err = parse_err(json);
        assert!(!err.is_empty());
    }

    // ── Effective defaults ────────────────────────────────────────────────────

    #[test]
    fn effective_entrypoint_native_default() {
        let m = parse_ok(r#"{"name":"cron","version":"1.0.0","app_type":"native"}"#);
        assert_eq!(m.effective_entrypoint(), "app.so");
    }

    #[test]
    fn effective_entrypoint_bun_default() {
        let m = parse_ok(r#"{"name":"myapp","version":"1.0.0","app_type":"bun"}"#);
        assert_eq!(m.effective_entrypoint(), "dist/index.js");
    }

    #[test]
    fn effective_hot_reload_native_default_is_experimental() {
        let m = parse_ok(r#"{"name":"cron","version":"1.0.0","app_type":"native"}"#);
        assert_eq!(m.effective_hot_reload(), HotReloadKind::Experimental);
    }

    #[test]
    fn effective_hot_reload_bun_default_is_supported() {
        let m = parse_ok(r#"{"name":"myapp","version":"1.0.0","app_type":"bun"}"#);
        assert_eq!(m.effective_hot_reload(), HotReloadKind::Supported);
    }

    #[test]
    fn hot_reload_unsupported_explicit() {
        let json = r#"{
            "manifest_version": 2, "name": "myapp", "version": "1.0.0",
            "app_type": "bun", "abi": "v1", "hot_reload": "unsupported"
        }"#;
        let m = parse_ok(json);
        assert_eq!(m.effective_hot_reload(), HotReloadKind::Unsupported);
    }

    // ── validate_manifest_path unit tests ─────────────────────────────────────

    #[test]
    fn validate_path_simple_valid() {
        assert!(validate_manifest_path("dist/index.js").is_ok());
        assert!(validate_manifest_path("app.so").is_ok());
        assert!(validate_manifest_path("ui/dist/bundle.js").is_ok());
        assert!(validate_manifest_path("build_output/main").is_ok());
    }

    #[test]
    fn validate_path_empty_rejected() {
        assert!(validate_manifest_path("").is_err());
    }

    #[test]
    fn validate_path_absolute_rejected() {
        assert!(validate_manifest_path("/usr/bin/sh").is_err());
    }

    #[test]
    fn validate_path_double_dot_segment_rejected() {
        assert!(validate_manifest_path("foo/../bar").is_err());
        assert!(validate_manifest_path("../etc/passwd").is_err());
    }

    #[test]
    fn validate_path_leading_dot_rejected() {
        assert!(validate_manifest_path(".hidden").is_err());
    }

    #[test]
    fn validate_path_null_byte_rejected() {
        // null byte is non-ASCII, rejected by char check
        let path = "foo\0bar";
        assert!(validate_manifest_path(path).is_err());
    }

    #[test]
    fn standalone_socket_path_development_override_is_explicit_and_pure() {
        let path = std::path::Path::new("/tmp/node-app/example.sock");
        assert!(validate_standalone_socket_path(path).is_err());
        assert!(validate_standalone_socket_path_with_policy(path, true).is_ok());
        assert!(validate_standalone_socket_path_with_policy(
            std::path::Path::new("/tmp/node-app/../escape.sock"),
            true,
        )
        .is_err());
    }

    // ── ManifestCapabilities defaults ─────────────────────────────────────────

    #[test]
    fn manifest_capabilities_defaults_to_empty() {
        let m = parse_ok(r#"{"name":"myapp","version":"1.0.0","app_type":"bun"}"#);
        assert!(m.capabilities.requires.is_empty());
        assert!(m.capabilities.provides.is_empty());
    }

    // ── resolved_capability_provides (T28 standalone-registration shaping) ────

    #[test]
    fn resolved_capability_provides_v1_only() {
        let json = r#"{
            "name": "example", "version": "1.0.0", "app_type": "bun",
            "provides": { "core.example.run": { "description": "Run example job" } }
        }"#;
        let m = parse_ok(json);
        let out = m.resolved_capability_provides();
        assert_eq!(out.len(), 1);
        assert_eq!(
            out.get("core.example.run").unwrap().description,
            "Run example job"
        );
    }

    #[test]
    fn resolved_capability_provides_v2_names_get_blank_declaration() {
        let json = r#"{
            "manifest_version": 2, "name": "example", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "capabilities": { "requires": [], "provides": ["core.example.run", "core.example.other:extra"] }
        }"#;
        let m = parse_ok(json);
        let out = m.resolved_capability_provides();
        assert_eq!(out.len(), 2);
        assert_eq!(out.get("core.example.run").unwrap().description, "");
        assert!(out.get("core.example.run").unwrap().schema.is_none());
        // Only the part before the first ':' is used as the name.
        assert!(out.contains_key("core.example.other"));
        assert!(!out.contains_key("core.example.other:extra"));
    }

    #[test]
    fn resolved_capability_provides_v1_wins_on_conflict() {
        let json = r#"{
            "manifest_version": 2, "name": "example", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "provides": { "core.example.run": { "description": "v1 wins" } },
            "capabilities": { "requires": [], "provides": ["core.example.run"] }
        }"#;
        let m = parse_ok(json);
        let out = m.resolved_capability_provides();
        assert_eq!(out.len(), 1);
        assert_eq!(out.get("core.example.run").unwrap().description, "v1 wins");
    }

    #[test]
    fn resolved_capability_provides_blank_v2_name_skipped() {
        let json = r#"{
            "manifest_version": 2, "name": "example", "version": "1.0.0",
            "app_type": "bun", "abi": "v1",
            "capabilities": { "requires": [], "provides": ["  ", "core.example.run"] }
        }"#;
        let m = parse_ok(json);
        let out = m.resolved_capability_provides();
        assert_eq!(out.len(), 1);
        assert!(out.contains_key("core.example.run"));
    }

    #[test]
    fn resolved_capability_provides_empty_manifest_yields_empty_map() {
        let m = parse_ok(r#"{"name":"myapp","version":"1.0.0","app_type":"bun"}"#);
        assert!(m.resolved_capability_provides().is_empty());
    }

    // ── ABI version ───────────────────────────────────────────────────────────

    #[test]
    fn abi_v1_is_supported() {
        assert!(AbiVersion::V1.is_supported());
    }

    // ── AppTier display ───────────────────────────────────────────────────────

    #[test]
    fn app_tier_display() {
        assert_eq!(AppTier::FirstParty.to_string(), "first_party");
        assert_eq!(AppTier::Optional.to_string(), "optional");
        assert_eq!(AppTier::Development.to_string(), "development");
    }

    #[test]
    fn app_tier_serde_roundtrip() {
        // Wire format must stay snake_case for the existing API contract.
        for tier in [AppTier::FirstParty, AppTier::Optional, AppTier::Development] {
            let json = serde_json::to_string(&tier).unwrap();
            let back: AppTier = serde_json::from_str(&json).unwrap();
            assert_eq!(
                tier, back,
                "roundtrip failed for {:?}: serialized as {}",
                tier, json
            );
        }
        assert_eq!(
            serde_json::to_string(&AppTier::Development).unwrap(),
            "\"development\""
        );
    }

    // ── AppType display ───────────────────────────────────────────────────────

    #[test]
    fn app_type_display() {
        assert_eq!(AppType::Native.to_string(), "native");
        assert_eq!(AppType::Bun.to_string(), "bun");
        assert_eq!(AppType::PlatformRuntime.to_string(), "platform-runtime");
    }

    #[test]
    fn platform_runtime_is_a_supported_packaging_type() {
        let manifest: AppManifest = serde_json::from_value(serde_json::json!({
            "manifest_version": 2,
            "abi": "v1",
            "name": "bun-runtime",
            "version": "1.0.0",
            "app_type": "platform-runtime",
            "entrypoint": "bun"
        }))
        .expect("platform runtime manifest should parse");

        assert_eq!(manifest.app_type, AppType::PlatformRuntime);
        assert_eq!(manifest.effective_hot_reload(), HotReloadKind::Unsupported);
    }

    // ── GovernorManifest memory budget ──────────────────────────────────────────

    #[test]
    fn governor_manifest_memory_budget_defaults_to_none() {
        let parsed: GovernorManifest = serde_json::from_str(r#"{"terminable": true}"#).unwrap();
        assert_eq!(parsed.memory_budget_kb, None);
    }

    #[test]
    fn governor_manifest_parses_declared_memory_budget() {
        let parsed: GovernorManifest =
            serde_json::from_str(r#"{"memory_budget_kb": 40960}"#).unwrap();
        assert_eq!(parsed.memory_budget_kb, Some(40_960));
    }
}