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,
    /// Verified executable generated by LLMC and launched through the
    /// versioned managed-v1 stdio protocol.
    #[serde(rename = "managed-v1")]
    ManagedV1,
    /// ES module bundle hosted by the Burger (QuickJS) runtime host,
    /// `node-app-burger host` (Burger Plan 02, Contract C7).
    Burger,
    /// A UI-only app: a `ui` block (a stage, or a widget a stage composes) and
    /// no backend at all (burger-07, Plans 07a/07b Contracts F5; widgets since
    /// the `ui.widget-ui-only` host feature). Never loaded, spawned or
    /// woken; node-server only lists and serves its UI bundle. Derived by
    /// [`AppManifest::from_json`] for a manifest with a `ui` object and neither
    /// `app_type` nor `entrypoint`. The string `"ui-only"` is also accepted,
    /// so a serialised manifest round-trips.
    #[serde(rename = "ui-only")]
    UiOnly,
}

impl AppType {
    pub fn as_str(self) -> &'static str {
        match self {
            AppType::Native => "native",
            AppType::Bun => "bun",
            AppType::Standalone => "standalone",
            AppType::PlatformRuntime => "platform-runtime",
            AppType::ManagedV1 => "managed-v1",
            AppType::Burger => "burger",
            AppType::UiOnly => "ui-only",
        }
    }
}

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 loads the library now on disk, but depends on the old instance
    /// stopping. The daemon never unloads a native library (the old
    /// instance's threads may still run in it), so a load after an upgrade
    /// maps a private copy of the new file and runs that. When the old
    /// instance's shutdown failed or timed out, the app cannot load again in
    /// that process, and `app.reload` reports that the node must restart
    /// (ADR-084). 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,
            AppType::ManagedV1 => HotReloadKind::Supported,
            AppType::Burger => HotReloadKind::Supported,
            // A stage bundle reloads with the page; there is no process to reload.
            AppType::UiOnly => 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, plus `discoverable`).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProvidedCapability {
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub schema: Option<serde_json::Value>,
    /// Whether `core.capabilities.list` / `search` report this capability.
    /// Default `true`. `false` keeps it out of agent discovery (and so out of
    /// agent tool generation); a caller that names it can still invoke it.
    /// This is discovery hygiene, **not** access control.
    #[serde(
        default = "default_discoverable",
        skip_serializing_if = "is_discoverable"
    )]
    pub discoverable: bool,
}

fn default_discoverable() -> bool {
    true
}

fn is_discoverable(value: &bool) -> bool {
    *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,
}

/// The chat-assistant surface slot: at most one app surface may claim it, and declaring it
/// requires the host to support the assistant slot (`HostFeature::UiAssistantSlot`).
pub const ASSISTANT_SLOT: &str = "assistant";

/// Shell-chrome regions an app may contribute a surface to.
///
/// The shell owns this vocabulary; an app requests a region by name. Keep this
/// list to slots that have a real occupant — a speculative slot is a contract
/// nobody has had to honour yet.
///
/// Checked in TWO places on purpose. `node-app package` rejects an unknown slot
/// so an author sees a typo while they can still fix it; the shell ALSO ignores
/// surfaces whose slot it does not recognise, because an app packaged against a
/// newer SDK can be installed on an older shell, and that shell must degrade by
/// dropping the surface rather than failing the app.
pub const KNOWN_SURFACE_SLOTS: &[&str] = &["status-rail", ASSISTANT_SLOT];

/// A UI unit an app contributes to a named region of the shell's own chrome.
///
/// Not a route: it has no nav entry, and it is mounted by the shell rather than
/// by any stage. `requires` is the surface's OWN authorization scope — the
/// primary containment control, since a surface otherwise receives the same
/// `StageContext` a stage receives. A wallet chip declares `wallet.balance.get`
/// and is refused `wallet.payment.send` even though the app provides it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppUiSurface {
    pub id: String,
    pub slot: String,
    pub entry: String,
    pub title: String,
    #[serde(default)]
    pub order: i32,
    #[serde(default)]
    pub requires: AppUiRequirements,
}

/// 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>,
    /// Kernel commands this UI may send through `ctx.command`. Authorized by the
    /// client kernel only, so deliberately NOT part of `resolved()` (the host-side
    /// device-scope list). Omitted from the wire when empty so kernels that
    /// predate the field keep accepting every manifest that does not use it.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub commands: Vec<String>,
}

impl AppUiRequirements {
    /// Validates `commands` separately from `resolved()`; see the field doc.
    pub fn validate_commands(&self) -> Result<(), String> {
        let mut seen = HashSet::new();
        for command in &self.commands {
            let name = command.trim();
            let versioned = name.rsplit_once(".v").is_some_and(|(head, version)| {
                !head.is_empty()
                    && head.chars().all(|c| {
                        c.is_ascii_lowercase() || c.is_ascii_digit() || c == '.' || c == '-'
                    })
                    && version.chars().next().is_some_and(|c| ('1'..='9').contains(&c))
                    && version.chars().all(|c| c.is_ascii_digit())
            });
            if !versioned || name != command {
                return Err(format!("ui.requires.commands entry '{command}' must be a versioned name like 'devtools.dom.snapshot.v1'"));
            }
            if !seen.insert(name) {
                return Err(format!("ui.requires.commands contains duplicate '{name}'"));
            }
        }
        Ok(())
    }

    /// Return the UI's host-side device-scope declarations 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)
    }
}

/// The shell viewport a stage requests. Omission preserves the column layout.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum UiLayout {
    Full,
    #[default]
    Column,
}

/// Optional stage metadata carried by the canonical app manifest.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppUiManifest {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub layout: Option<UiLayout>,
    #[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>,
    /// Shell-chrome contributions. Empty for the overwhelming majority of apps.
    #[serde(default)]
    pub surfaces: Vec<AppUiSurface>,
    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>,

    /// Runtime resource requests (Burger Plan 02, Contracts C2/C7). Absence means
    /// runtime defaults (Burger: 32 MB QuickJS memory limit, 5000 ms callback deadline).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub resources: Option<ResourcesManifest>,

    /// Recurring jobs this app needs on the node, declared so the host can put
    /// the cron rows there without the app ever having run (econ-v1/node#3185).
    ///
    /// Empty — the default — is exactly the behaviour that shipped before: the
    /// app owns its own registration and nothing happens until it starts. See
    /// [`AppScheduleManifest`] for why declaring one does not pin the isolate.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub schedules: Vec<AppScheduleManifest>,

    /// Host contract features this manifest needs, stamped by
    /// `node-app contract stamp`. Absent in manifests built before stamping
    /// existed; see `check_host_contract`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub host_contract: Option<crate::HostContractStamp>,
}

/// Upper bound for `resources.callback_deadline_ms` (10 minutes).
pub const MAX_CALLBACK_DEADLINE_MS: u32 = 600_000;

/// Runtime resource requests (Contract C2). `memory_mb` becomes the Burger
/// host's per-app QuickJS memory limit (`load_app.memory_limit_mb`);
/// `callback_deadline_ms` becomes its per-callback CPU watchdog
/// (`load_app.callback_deadline_ms`). Both are omitted from `load_app` when
/// absent so the Burger host applies its own defaults (32 MB, 5000 ms).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResourcesManifest {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub memory_mb: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub callback_deadline_ms: Option<u32>,
}

/// Declared responsiveness expectation for an app's lease engine decisions
/// (app lease engine design §8, Task 1). `None` on [`GovernorManifest`] means
/// the app has not declared a preference — the lease engine (Task 5) then
/// falls back to its own default rather than treating an unset field as
/// either variant.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum LatencyClass {
    /// The app serves latency-sensitive, user-facing requests — the lease
    /// engine should prefer to keep it warm.
    Interactive,
    /// The app only does deferred/background work — the lease engine may
    /// treat it as a lower priority to keep resident.
    Background,
}

impl LatencyClass {
    pub fn as_str(&self) -> &'static str {
        match self {
            LatencyClass::Interactive => "interactive",
            LatencyClass::Background => "background",
        }
    }

    #[allow(clippy::should_implement_trait)]
    pub fn from_str(s: &str) -> Result<Self, String> {
        match s {
            "interactive" => Ok(LatencyClass::Interactive),
            "background" => Ok(LatencyClass::Background),
            _ => Err(format!("Invalid LatencyClass: {}", s)),
        }
    }
}

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

/// 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>,

    /// Declared responsiveness expectation (app lease engine design §8,
    /// Task 1). `None` when the app declares no preference — see
    /// [`LatencyClass`] for what each variant means and what `None` defers
    /// to.
    #[serde(default)]
    pub latency_class: Option<LatencyClass>,
}

/// 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>,
}

/// One recurring job an app declares in its own manifest, so the host can put
/// the cron row on the node without the app ever having run (econ-v1/node#3185).
///
/// Before this existed, an app that records on a schedule had to register its
/// own row when it started — which a `lazy` app only does once something first
/// invokes it. On a node whose owner never opens that app, the row was never
/// created, nothing was ever recorded, and nothing said so.
///
/// Declaring the schedule here does NOT make the app resident. The host
/// registers a CAPABILITY-triggered row pointing at [`Self::capability`]; when
/// it fires, the capability router resolves the provider from the registry
/// (seeded at boot for unloaded apps) and cold-starts the app for the duration
/// of the call. Between firings the isolate can be reclaimed exactly as before.
/// `auto_start: "auto"` would also produce the row, and is NOT the answer: it
/// pins the isolate permanently, which is the cost a sparse cadence exists to
/// avoid.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppScheduleManifest {
    /// Stable identifier, unique within this app. Becomes the cron row's
    /// `external_id` (paired with the app name as `external_type`), which is
    /// what lets the host find its own row again without storing anything.
    ///
    /// Changing it retires the old row and creates a new one — it is an
    /// identity, not a label.
    pub id: String,

    /// 6-field cron expression: `sec min hour day month weekday`.
    ///
    /// Checked here only for shape (six non-empty fields over the permitted
    /// character set). The authoritative parse lives in the host, which refuses
    /// the whole manifest on a bad expression — this crate is the schema
    /// contract that app authors compile against, and is deliberately kept to
    /// `serde` alone rather than pulling a cron parser and its date-time
    /// dependencies into every app build.
    pub cron: String,

    /// The capability the row dispatches.
    ///
    /// MUST be one this same app declares in `provides` / `capabilities.provides`,
    /// and the manifest is refused otherwise. Without that restriction any
    /// manifest could schedule repeated dispatches at any capability on the node
    /// — `core.lightning.send_payment`, say — and a manifest is not a surface
    /// the owner reviews.
    pub capability: String,

    /// JSON object handed to the capability on each firing. Absent means `{}`.
    /// A non-object payload is refused: every capability on the dispatch path
    /// takes an object, and the router stamps `caller` into it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub payload: Option<serde_json::Value>,
}

impl AppScheduleManifest {
    /// The payload to dispatch with, defaulting to an empty object.
    pub fn effective_payload(&self) -> serde_json::Value {
        self.payload
            .clone()
            .unwrap_or_else(|| serde_json::Value::Object(serde_json::Map::new()))
    }
}

/// Characters permitted in a cron field. Covers the standard vocabulary
/// (`* , - /`), named months/weekdays, and the `?` / `L` / `W` / `#` forms
/// extended syntaxes use — the host's real parser decides what it accepts, so
/// this only rejects input that could not be a cron field at all.
fn cron_field_char_allowed(ch: char) -> bool {
    ch.is_ascii_alphanumeric() || matches!(ch, '*' | ',' | '-' | '/' | '?' | 'L' | 'W' | '#')
}

/// Shape check for a 6-field cron expression. See [`AppScheduleManifest::cron`]
/// for why the authoritative parse is the host's and not this crate's.
fn validate_cron_shape(expression: &str) -> Result<(), String> {
    let fields: Vec<&str> = expression.split_whitespace().collect();
    if fields.len() != 6 {
        return Err(format!(
            "cron '{}' must have 6 fields (sec min hour day month weekday), found {}",
            expression,
            fields.len()
        ));
    }
    for field in fields {
        if let Some(ch) = field.chars().find(|c| !cron_field_char_allowed(*c)) {
            return Err(format!(
                "cron '{}' contains disallowed character '{}'",
                expression, ch
            ));
        }
    }
    Ok(())
}

/// A schedule id must be a stable, filesystem- and URL-safe token: it travels
/// as the cron row's `external_id` and is matched verbatim on every reconcile.
fn validate_schedule_id(id: &str) -> Result<(), String> {
    if id.is_empty() {
        return Err("schedule id must not be empty".to_string());
    }
    let first = id.chars().next().unwrap();
    if !first.is_ascii_lowercase() && !first.is_ascii_digit() {
        return Err(format!(
            "schedule id '{}' must begin with a lowercase letter or digit",
            id
        ));
    }
    for ch in id.chars() {
        if !ch.is_ascii_lowercase() && !ch.is_ascii_digit() && !matches!(ch, '-' | '_' | '.') {
            return Err(format!(
                "schedule id '{}' contains disallowed character '{}' (allowed: a-z 0-9 - _ .)",
                id, ch
            ));
        }
    }
    Ok(())
}

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 and UI-only apps have no daemon-managed entrypoint (systemd
    /// owns a standalone's lifecycle; a UI-only stage has no process); 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",
                AppType::ManagedV1 => "llmc-generated-app",
                AppType::Burger => "dist/index.js",
                AppType::UiOnly => "",
            }
        }
    }

    /// 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,
                discoverable: true,
            });
        }
        out
    }

    /// Refuse a `schedules` block that the host could not honour, or should not.
    ///
    /// Three distinct refusals, and the third is the one that matters for
    /// security: a schedule may only name a capability THIS app provides.
    /// The host registers the row as the app and the cron app records the app
    /// as its `created_by`, so an unrestricted `capability` field would let any
    /// package schedule repeated dispatches at anything on the node under its
    /// own name. A manifest is not a surface the owner reviews, so the gate is
    /// here, at install, and loud — not at 03:00 and silent.
    fn validate_schedules(&self) -> Result<(), String> {
        if self.schedules.is_empty() {
            return Ok(());
        }
        let provided = self.resolved_capability_provides();
        let mut seen: HashSet<&str> = HashSet::new();
        for schedule in &self.schedules {
            validate_schedule_id(&schedule.id)?;
            if !seen.insert(schedule.id.as_str()) {
                return Err(format!("duplicate schedule id '{}'", schedule.id));
            }
            validate_cron_shape(&schedule.cron)
                .map_err(|e| format!("schedule '{}': {}", schedule.id, e))?;
            if schedule.capability.trim().is_empty() {
                return Err(format!(
                    "schedule '{}': capability must not be blank",
                    schedule.id
                ));
            }
            if !provided.contains_key(schedule.capability.trim()) {
                return Err(format!(
                    "schedule '{}' names capability '{}', which this app does not provide \
                     (a schedule may only dispatch a capability declared in this manifest's \
                     'provides')",
                    schedule.id, schedule.capability
                ));
            }
            if let Some(payload) = &schedule.payload {
                if !payload.is_object() {
                    return Err(format!(
                        "schedule '{}': payload must be a JSON object",
                        schedule.id
                    ));
                }
            }
        }
        Ok(())
    }

    /// 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
            | AppType::ManagedV1
            | AppType::Burger
            | AppType::UiOnly => {
                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::UiOnly {
            validate_ui_only(self)?;
        }

        if let Some(resources) = &self.resources {
            if resources.memory_mb == Some(0) {
                return Err("resources.memory_mb must be at least 1".to_string());
            }
            if let Some(deadline) = resources.callback_deadline_ms {
                if !(1..=MAX_CALLBACK_DEADLINE_MS).contains(&deadline) {
                    return Err(format!(
                        "resources.callback_deadline_ms must be between 1 and {MAX_CALLBACK_DEADLINE_MS} (found {deadline})"
                    ));
                }
            }
        }

        self.validate_schedules()?;

        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 serde_json::from_str::<serde_json::Value>(json).is_ok_and(|raw| declares_ui_only(&raw)) {
            manifest.app_type = AppType::UiOnly;
        }
        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)
}

/// Contracts F5: a UI-only app declares a stage or a widget and nothing that
/// implies a process. A widget runs inside the stage that composes it, so it
/// needs a backend no more than a stage does.
fn validate_ui_only(manifest: &AppManifest) -> Result<(), String> {
    // Exhaustive on purpose: a future ui kind must decide here whether it can be UI-only.
    match manifest.ui.as_ref().map(|ui| ui.kind) {
        Some(AppUiKind::Stage | AppUiKind::Widget) => {}
        None => {
            return Err(
                "ui-only apps must declare a ui block of kind \"stage\" or \"widget\"".to_string(),
            )
        }
    }
    match ui_only_process_declaration(manifest) {
        Some(what) => Err(format!(
            "ui-only apps have no backend process and must not declare {what}"
        )),
        None => Ok(()),
    }
}

/// Contracts F5: the first thing `manifest` declares that implies a backend
/// process, which a UI-only app cannot have. A UI-only app is never started,
/// so it can neither receive events nor wait on dependencies. Shared by
/// [`AppManifest::validate`] and `node-app audit`.
pub fn ui_only_process_declaration(manifest: &AppManifest) -> Option<&'static str> {
    if manifest.entrypoint.is_some() {
        Some("'entrypoint'")
    } else if manifest.has_capability_providers() {
        Some("capability providers ('provides' / 'capabilities.provides')")
    } else if manifest.tcp.is_some() {
        Some("a 'tcp' block")
    } else if manifest.resources.is_some() {
        Some("a 'resources' block")
    } else if manifest.standalone.is_some() {
        Some("a 'standalone' block")
    } else if !manifest.subscribes.is_empty() {
        Some("event subscriptions ('subscribes')")
    } else if manifest
        .depends_on
        .as_ref()
        .is_some_and(|deps| !deps.is_empty())
    {
        Some("dependencies ('depends_on')")
    } else {
        None
    }
}

/// Contracts F5: whether a raw manifest is UI-only — a `ui` object with
/// neither `app_type` nor `entrypoint`, or an explicit `"app_type":
/// "ui-only"`. Read off the raw JSON, because serde's `app_type` default
/// (`native`) hides whether the key was there. The one definition shared by
/// [`AppManifest::from_json`], `node-app audit` and `node-app package`.
///
/// Precedence: an explicit `app_type` other than `"ui-only"` always wins
/// over the derived form. A manifest with `"app_type": "bun"`, a `ui` block
/// and no `entrypoint` is a Bun app, not UI-only — the derived branch's
/// `!object.contains_key("app_type")` check is false, so it never fires, and
/// [`validate_ui_only`] is skipped for it. The derived form only applies
/// when `app_type` is absent entirely.
pub fn declares_ui_only(manifest: &serde_json::Value) -> bool {
    manifest.as_object().is_some_and(|object| {
        let derived = object.get("ui").is_some_and(serde_json::Value::is_object)
            && !object.contains_key("app_type")
            && !object.contains_key("entrypoint");
        derived || object.get("app_type").and_then(serde_json::Value::as_str) == Some("ui-only")
    })
}

/// Scope prefixes no UI may request (C §9.2): the agent engine's runtime is reached only
/// through the agent app, which gates it by mode, approval card and caller. A stage or surface that
/// requested it directly would bypass all three.
const UI_FORBIDDEN_CAPABILITY_PREFIXES: &[&str] = &["graph.runtime."];

fn refuse_forbidden_ui_requirements(
    label: &str,
    requires: &AppUiRequirements,
) -> Result<(), String> {
    // All three fields become browser scopes in resolved() and the client kernel.
    // Run before syntax validation so even bare '*' gets the runtime diagnostic;
    // resolved() still enforces the general per-field syntax afterwards.
    for (field, values) in [
        ("capabilities", &requires.capabilities),
        ("queries", &requires.queries),
        ("streams", &requires.streams),
    ] {
        refuse_forbidden_ui_scopes(&format!("{label}.{field}"), values)?;
    }
    Ok(())
}

fn refuse_forbidden_ui_scopes(label: &str, scopes: &[String]) -> Result<(), String> {
    for scope in scopes {
        let name = scope.trim();
        // `graph.*` and `*` cover the runtime too, not only an entry that names it.
        let wildcard_root = name
            .strip_suffix('*')
            .filter(|_| name == "*" || name.ends_with(".*"));
        let covered = |prefix: &str| {
            name.starts_with(prefix) || wildcard_root.is_some_and(|root| prefix.starts_with(root))
        };
        if let Some(prefix) = UI_FORBIDDEN_CAPABILITY_PREFIXES
            .iter()
            .find(|prefix| covered(prefix))
        {
            return Err(format!(
                "{label} must not request '{name}': {prefix}* is reachable only through the agent app"
            ));
        }
    }
    Ok(())
}

fn validate_app_ui(app_name: &str, ui: &AppUiManifest) -> Result<(), String> {
    // `layout` is validated during deserialization by UiLayout: only full/column
    // are representable. None resolves to UiLayout::default() (column).
    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());
    }
    refuse_forbidden_ui_requirements("ui.requires", &ui.requires)?;
    ui.requires.resolved()?;
    ui.requires.validate_commands()?;
    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());
        }
    }
    // Widgets own app data under exactly the stage rules. Which hosts accept
    // that is decided by the `ui.widget-data` host feature, not here
    // (see `host_contract::check_host_contract`).
    if let Some(data) = &ui.data {
        validate_app_data(app_name, 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}'"));
        }
    }

    let mut surface_ids = HashSet::new();
    for surface in &ui.surfaces {
        let id = surface.id.trim();
        if id.is_empty() {
            return Err("ui.surfaces entry id must not be blank".to_string());
        }
        if !surface_ids.insert(id.to_string()) {
            return Err(format!("ui.surfaces contains duplicate id '{id}'"));
        }
        if !KNOWN_SURFACE_SLOTS.contains(&surface.slot.as_str()) {
            return Err(format!(
                "ui.surfaces entry '{id}' requests unknown slot '{}'; known slots: {}",
                surface.slot,
                KNOWN_SURFACE_SLOTS.join(", ")
            ));
        }
        if surface.title.trim().is_empty() {
            return Err(format!("ui.surfaces entry '{id}' title must not be blank"));
        }
        validate_manifest_path(&surface.entry)
            .map_err(|error| format!("ui.surfaces entry '{id}' entry invalid: {error}"))?;
        // Same rule `ui.entry` and `ui.icon` get below, and for a sharper reason: the client
        // kernel's `ensureIntegrityForUi` (`client/kernel/src/stages/stage-registry-service.js`)
        // REQUIRES a digest for every surface entry, and the throw there propagates out of
        // `parseCatalogEntry` through `parseCatalogResponse`'s `value.map(...)` — failing the
        // whole catalog snapshot, every stage on the node, and looping on retry. Without this
        // check a typo, or an entry emitted outside `ui_path` (which is the only tree
        // `generate_staged_integrity` stamps), packages cleanly, installs cleanly, and then
        // bricks every client's stage list. Refuse it here, where the author can still fix it.
        if !ui.integrity.contains_key(&surface.entry) {
            return Err(format!("ui.integrity must include surface '{id}' entry"));
        }
        refuse_forbidden_ui_requirements(
            &format!("ui.surfaces entry '{id}' requires"),
            &surface.requires,
        )?;
        surface
            .requires
            .resolved()
            .map_err(|error| format!("ui.surfaces entry '{id}' requires invalid: {error}"))?;
        surface
            .requires
            .validate_commands()
            .map_err(|error| format!("ui.surfaces entry '{id}': {error}"))?;
    }

    if ui
        .surfaces
        .iter()
        .filter(|surface| surface.slot == ASSISTANT_SLOT)
        .count()
        > 1
    {
        return Err("ui.surfaces may declare at most one 'assistant' surface".to_string());
    }

    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(
    app_name: &str,
    data: &AppDataManifest,
    resolved_requires: &[String],
) -> Result<(), String> {
    validate_app_data_namespace(&data.namespace)?;
    validate_app_data_namespace_owner(app_name, &data.namespace)?;
    validate_app_data_sync_policy(&data.sync)?;
    if data.queries.is_empty() && data.offline != AppDataOfflinePolicy::OnlineOnly {
        return Err("ui.data.queries must declare at least one query for last-known data".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(())
}

/// A stage's projections are stored under `ui.data.namespace`, and the
/// Client Node PWA only accepts a namespace the app owns
/// (`validateEntryCompatibility`,
/// `client/kernel/src/stages/offline-readiness-coordinator.js`): any other
/// stage fails there as `schema-incompatible` and never reaches the nav. The
/// client also admits `<app>.`-prefixed namespaces, but a namespace cannot
/// contain a dot ([`validate_app_data_namespace`]), so here the rule is plain
/// equality. node-app-burger 0.2.0 shipped `burger` for `burger-runtime`.
///
/// Public so `node-app audit` reports the same rule, with the same message.
pub fn validate_app_data_namespace_owner(app_name: &str, namespace: &str) -> Result<(), String> {
    if namespace != app_name {
        return Err(format!(
            "ui.data namespace '{namespace}' must equal the app name '{app_name}' — the Client \
             Node PWA refuses a stage whose data namespace it does not own; rename the namespace \
             to '{app_name}' and its query and stream names to '{app_name}.<name>.v<N>'"
        ));
    }
    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")
    }

    // ── schedules (econ-v1/node#3185) ────────────────────────────────────────

    const SCHEDULED_APP: &str = r#"{
        "name":"network","version":"1.0.0","app_type":"bun","auto_start":"lazy",
        "provides":{"network.ledger.poll":{"description":"Record connections"}},
        "schedules":[{"id":"ledger-poll","cron":"0 */15 * * * *",
                      "capability":"network.ledger.poll"}]
    }"#;

    #[test]
    fn a_manifest_with_no_schedules_block_parses_to_an_empty_list() {
        // The default has to stay byte-for-byte the old behaviour: every
        // manifest on every installed node predates this field.
        let m = parse_ok(r#"{"name":"cron","version":"1.0.0","app_type":"native"}"#);
        assert!(m.schedules.is_empty());
    }

    #[test]
    fn a_schedule_is_parsed_whole() {
        let m = parse_ok(SCHEDULED_APP);
        assert_eq!(m.schedules.len(), 1);
        let s = &m.schedules[0];
        assert_eq!(s.id, "ledger-poll");
        assert_eq!(s.cron, "0 */15 * * * *");
        assert_eq!(s.capability, "network.ledger.poll");
        // An absent payload is an empty object, not null — the router stamps
        // `caller` into it, which requires an object.
        assert_eq!(s.effective_payload(), serde_json::json!({}));
    }

    #[test]
    fn a_schedule_may_only_dispatch_a_capability_this_app_provides() {
        // The security gate. Without it any package could schedule repeated
        // dispatches at anything on the node under its own name.
        let err = parse_err(
            r#"{"name":"network","version":"1.0.0","app_type":"bun",
                "provides":{"network.ledger.poll":{"description":"x"}},
                "schedules":[{"id":"drain","cron":"0 0 * * * *",
                              "capability":"core.lightning.send_payment"}]}"#,
        );
        assert!(err.contains("core.lightning.send_payment"), "{err}");
        assert!(err.contains("does not provide"), "{err}");
    }

    #[test]
    fn a_v2_capabilities_provides_entry_also_satisfies_the_gate() {
        // v2 manifests list provided capability NAMES under `capabilities.provides`
        // rather than the v1 `provides` map; both are the same declaration.
        let m = parse_ok(
            r#"{"manifest_version":2,"abi":"v1","name":"network","version":"1.0.0",
                "app_type":"bun",
                "capabilities":{"provides":["network.ledger.poll"]},
                "schedules":[{"id":"ledger-poll","cron":"0 */15 * * * *",
                              "capability":"network.ledger.poll"}]}"#,
        );
        assert_eq!(m.schedules.len(), 1);
    }

    #[test]
    fn a_cron_expression_without_six_fields_is_refused() {
        // 5 fields is the Unix crontab shape; this platform's cron takes 6.
        let err = parse_err(
            r#"{"name":"n","version":"1.0.0","app_type":"bun",
                "provides":{"n.poll":{"description":"x"}},
                "schedules":[{"id":"p","cron":"*/15 * * * *","capability":"n.poll"}]}"#,
        );
        assert!(err.contains("6 fields"), "{err}");
    }

    #[test]
    fn a_cron_expression_with_junk_in_it_is_refused() {
        let err = parse_err(
            r#"{"name":"n","version":"1.0.0","app_type":"bun",
                "provides":{"n.poll":{"description":"x"}},
                "schedules":[{"id":"p","cron":"0 0 2 * * $(whoami)","capability":"n.poll"}]}"#,
        );
        assert!(err.contains("disallowed character"), "{err}");
    }

    #[test]
    fn two_schedules_cannot_share_an_id() {
        // The id is the cron row's `external_id`; a duplicate would make the
        // reconcile's read-before-write lookup ambiguous.
        let err = parse_err(
            r#"{"name":"n","version":"1.0.0","app_type":"bun",
                "provides":{"n.poll":{"description":"x"}},
                "schedules":[{"id":"p","cron":"0 0 * * * *","capability":"n.poll"},
                             {"id":"p","cron":"0 30 * * * *","capability":"n.poll"}]}"#,
        );
        assert!(err.contains("duplicate schedule id"), "{err}");
    }

    #[test]
    fn a_schedule_id_must_be_a_safe_token() {
        let err = parse_err(
            r#"{"name":"n","version":"1.0.0","app_type":"bun",
                "provides":{"n.poll":{"description":"x"}},
                "schedules":[{"id":"../escape","cron":"0 0 * * * *","capability":"n.poll"}]}"#,
        );
        assert!(err.contains("schedule id"), "{err}");
    }

    #[test]
    fn a_non_object_payload_is_refused() {
        let err = parse_err(
            r#"{"name":"n","version":"1.0.0","app_type":"bun",
                "provides":{"n.poll":{"description":"x"}},
                "schedules":[{"id":"p","cron":"0 0 * * * *","capability":"n.poll",
                              "payload":"not-an-object"}]}"#,
        );
        assert!(err.contains("JSON object"), "{err}");
    }

    #[test]
    fn a_declared_payload_survives_the_round_trip() {
        let m = parse_ok(
            r#"{"name":"n","version":"1.0.0","app_type":"bun",
                "provides":{"n.poll":{"description":"x"}},
                "schedules":[{"id":"p","cron":"0 0 * * * *","capability":"n.poll",
                              "payload":{"depth":2}}]}"#,
        );
        assert_eq!(m.schedules[0].effective_payload(), serde_json::json!({"depth": 2}));
        let round_tripped: AppManifest =
            serde_json::from_str(&serde_json::to_string(&m).unwrap()).unwrap();
        assert_eq!(round_tripped.schedules, m.schedules);
    }

    #[test]
    fn an_empty_schedules_list_is_omitted_from_the_serialized_form() {
        // So re-serializing an old manifest does not grow a field it never had.
        let m = parse_ok(r#"{"name":"cron","version":"1.0.0","app_type":"native"}"#);
        let json = serde_json::to_string(&m).unwrap();
        assert!(!json.contains("schedules"), "{json}");
    }

    // ── 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"));
    }

    /// `provides.<name>.discoverable` defaults to `true`; `false` survives the
    /// v1/v2 merge and a round-trip, and is written back only when `false`.
    #[test]
    fn provides_discoverable_defaults_true_and_parses_false() {
        let json = r#"{
            "name": "remote-support",
            "version": "1.0.0",
            "app_type": "bun",
            "capabilities": { "provides": ["remote_support.status", "remote_support.challenge"] },
            "provides": {
                "remote_support.status": { "description": "Status" },
                "remote_support.mode.set": { "description": "Set mode", "discoverable": false }
            }
        }"#;
        let m = parse_ok(json);
        assert!(m.provides["remote_support.status"].discoverable);
        assert!(!m.provides["remote_support.mode.set"].discoverable);

        let resolved = m.resolved_capability_provides();
        assert!(!resolved["remote_support.mode.set"].discoverable);
        assert!(resolved["remote_support.status"].discoverable);
        // A v2-only name has no rich entry to carry the flag: discoverable.
        assert!(resolved["remote_support.challenge"].discoverable);

        let written = serde_json::to_value(&m).unwrap();
        assert_eq!(
            written["provides"]["remote_support.mode.set"]["discoverable"],
            serde_json::json!(false)
        );
        assert!(written["provides"]["remote_support.status"]
            .get("discoverable")
            .is_none());
    }

    #[test]
    fn provides_discoverable_must_be_a_boolean() {
        let json = r#"{
            "name": "example",
            "version": "1.0.0",
            "app_type": "bun",
            "provides": { "example.run": { "discoverable": "no" } }
        }"#;
        assert!(AppManifest::from_json(json).is_err());
    }

    // ── 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 stage_layout_parses_validates_and_defaults_to_column() {
        let source = include_str!(
            "../../../specs/456-node-app-distribution-infrastructure/contracts/fixtures/stage-manifest-v2.json"
        );
        let mut value: serde_json::Value = serde_json::from_str(source).unwrap();
        assert_eq!(parse_ok(source).ui.unwrap().layout, None);
        assert_eq!(UiLayout::default(), UiLayout::Column);
        for (name, layout) in [("full", UiLayout::Full), ("column", UiLayout::Column)] {
            value["ui"]["layout"] = serde_json::json!(name);
            let manifest = parse_ok(&value.to_string());
            assert_eq!(manifest.ui.as_ref().unwrap().layout, Some(layout));
            validate_app_ui(&manifest.name, manifest.ui.as_ref().unwrap()).unwrap();
            assert_eq!(
                serde_json::to_value(manifest.ui.unwrap()).unwrap()["layout"],
                name
            );
        }
        value["ui"]["layout"] = serde_json::json!("wide");
        assert!(parse_err(&value.to_string()).contains("unknown variant"));
    }

    #[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"));
    }

    /// node-app-burger 0.2.0 shipped `ui.data.namespace: "burger"` for the app
    /// `burger-runtime`. The host accepted it, the Client Node PWA refused it
    /// as `schema-incompatible`, and the stage silently never appeared. The
    /// rule now fails `node-app validate` instead.
    #[test]
    fn ui_data_namespace_must_equal_the_app_name() {
        let manifest = |namespace: &str| {
            format!(
                r#"{{
                    "name":"burger-runtime","version":"0.2.0",
                    "ui":{{
                        "kind":"stage","entry":"ui/dist/main.js","title":"Burger","ui_api":1,
                        "requires":{{"capabilities":["core.runtime.burger_snapshot"]}},
                        "integrity":{{"ui/dist/main.js":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}},
                        "data":{{
                            "namespace":"{namespace}","offline":"online-only","sync":"snapshot",
                            "queries":[{{"name":"{namespace}.snapshot.v1","capability":"core.runtime.burger_snapshot","kind":"snapshot"}}],
                            "streams":[{{"name":"{namespace}.metrics.v1","kind":"events"}}]
                        }}
                    }}
                }}"#
            )
        };

        let error = parse_err(&manifest("burger"));
        assert!(
            error.contains("ui.data namespace 'burger' must equal the app name 'burger-runtime'"),
            "unexpected error: {error}"
        );

        let accepted = parse_ok(&manifest("burger-runtime"));
        let data = accepted.ui.as_ref().and_then(|ui| ui.data.as_ref());
        assert_eq!(
            data.map(|data| data.namespace.as_str()),
            Some("burger-runtime")
        );
    }

    #[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"));
    }

    // ── ui.surfaces[] ────────────────────────────────────────────────────────

    /// A minimal valid manifest with a `ui` block, for tests that only care
    /// about `ui.surfaces`. Mirrors the fixture used by
    /// `stage_requires_integrity_for_entry_and_icon` above.
    ///
    /// The integrity map covers `surface()`'s entry as well as `ui.entry`, because a surface
    /// entry must be integrity-pinned exactly like the stage entry and the icon — see
    /// `surface_entry_missing_from_integrity_is_rejected`. Before that rule existed this fixture
    /// declared a surface no digest covered, which is precisely the manifest the client kernel
    /// refuses.
    fn manifest_with_ui() -> AppManifest {
        parse_ok(
            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",
                "ui/dist/surfaces/chip.js":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}
            }"#,
        )
    }

    fn surface(id: &str, slot: &str) -> AppUiSurface {
        AppUiSurface {
            id: id.to_string(),
            slot: slot.to_string(),
            entry: "ui/dist/surfaces/chip.js".to_string(),
            title: "Chip".to_string(),
            order: 10,
            requires: AppUiRequirements {
                capabilities: vec!["wallet.balance.get".to_string()],
                ..Default::default()
            },
        }
    }

    #[test]
    fn manifest_without_surfaces_still_parses() {
        let manifest = manifest_with_ui();
        assert!(manifest.ui.as_ref().unwrap().surfaces.is_empty());
        assert!(manifest.validate().is_ok());
    }

    #[test]
    fn surface_in_a_known_slot_is_accepted() {
        let mut manifest = manifest_with_ui();
        manifest.ui.as_mut().unwrap().surfaces = vec![surface("balance-chip", "status-rail")];
        assert!(manifest.validate().is_ok());
    }

    #[test]
    fn surface_in_an_unknown_slot_is_rejected() {
        let mut manifest = manifest_with_ui();
        manifest.ui.as_mut().unwrap().surfaces = vec![surface("balance-chip", "menu-bar")];
        let error = manifest.validate().unwrap_err();
        assert!(error.contains("menu-bar"), "unexpected error: {error}");
    }

    #[test]
    fn duplicate_surface_ids_are_rejected() {
        let mut manifest = manifest_with_ui();
        manifest.ui.as_mut().unwrap().surfaces = vec![
            surface("chip", "status-rail"),
            surface("chip", "status-rail"),
        ];
        let error = manifest.validate().unwrap_err();
        assert!(error.contains("duplicate"), "unexpected error: {error}");
    }

    #[test]
    fn surface_with_a_blank_id_is_rejected() {
        let mut manifest = manifest_with_ui();
        manifest.ui.as_mut().unwrap().surfaces = vec![surface("  ", "status-rail")];
        assert!(manifest.validate().is_err());
    }

    #[test]
    fn surface_with_an_unsafe_entry_path_is_rejected() {
        let mut manifest = manifest_with_ui();
        let mut bad = surface("chip", "status-rail");
        bad.entry = "../../etc/passwd".to_string();
        manifest.ui.as_mut().unwrap().surfaces = vec![bad];
        assert!(manifest.validate().is_err());
    }

    #[test]
    fn surface_entry_missing_from_integrity_is_rejected() {
        // The client kernel requires a digest for every surface entry and fails the WHOLE
        // catalog snapshot when one is missing, so a manifest that packages without one bricks
        // every installing node's stage list. Catch it at package time instead.
        let mut manifest = manifest_with_ui();
        let mut unpinned = surface("chip", "status-rail");
        unpinned.entry = "ui/dist/surfaces/typo.js".to_string();
        manifest.ui.as_mut().unwrap().surfaces = vec![unpinned];
        let error = manifest.validate().unwrap_err();
        assert!(
            error.contains("ui.integrity must include surface 'chip' entry"),
            "unexpected error: {error}"
        );
    }

    #[test]
    fn surface_with_a_blank_required_capability_is_rejected() {
        let mut manifest = manifest_with_ui();
        let mut bad = surface("chip", "status-rail");
        bad.requires.capabilities = vec!["   ".to_string()];
        manifest.ui.as_mut().unwrap().surfaces = vec![bad];
        assert!(manifest.validate().is_err());
    }

    #[test]
    fn a_stage_requesting_graph_runtime_is_rejected() {
        for name in ["graph.runtime.pi_mono.react", "graph.runtime.*", "graph.*"] {
            let mut manifest = manifest_with_ui();
            manifest
                .ui
                .as_mut()
                .unwrap()
                .requires
                .capabilities
                .push(name.to_string());
            let error = manifest.validate().unwrap_err();
            assert!(
                error.contains(&format!("ui.requires.capabilities must not request '{name}'")),
                "{name}: {error}"
            );
        }
    }

    #[test]
    fn a_surface_requesting_graph_runtime_is_rejected() {
        let mut manifest = manifest_with_ui();
        let mut chip = surface("chip", "status-rail");
        chip.requires
            .capabilities
            .push("graph.runtime.pi_mono.react".to_string());
        manifest.ui.as_mut().unwrap().surfaces = vec![chip];
        let error = manifest.validate().unwrap_err();
        assert!(
            error.contains("ui.surfaces entry 'chip' requires.capabilities must not request 'graph.runtime.pi_mono.react'"),
            "{error}"
        );
    }

    #[test]
    fn graph_capabilities_outside_the_runtime_are_still_accepted() {
        let mut manifest = manifest_with_ui();
        manifest
            .ui
            .as_mut()
            .unwrap()
            .requires
            .capabilities
            .push("graph.engine.flows.list".to_string());
        assert!(manifest.validate().is_ok());
    }

    // Exercise the public validator at both UI boundaries; a capabilities-only
    // check must not leave the query/stream delegation paths open.
    fn manifest_with_ui_requirement(
        surface_requirement: bool,
        field: &str,
        name: &str,
    ) -> AppManifest {
        let mut manifest = manifest_with_ui();
        let ui = manifest.ui.as_mut().unwrap();
        let requires = if surface_requirement {
            ui.surfaces.push(surface("chip", "status-rail"));
            &mut ui.surfaces[0].requires
        } else {
            &mut ui.requires
        };
        match field {
            "capabilities" => &mut requires.capabilities,
            "queries" => &mut requires.queries,
            "streams" => &mut requires.streams,
            _ => panic!("unknown requirement field"),
        }
        .push(name.to_string());
        manifest
    }

    #[test]
    fn ui_runtime_scope_fields_reject_exact_names_and_covering_wildcards() {
        let mut failures = Vec::new();
        for is_surface in [false, true] {
            for field in ["capabilities", "queries", "streams"] {
                for name in [
                    "graph.runtime.pi_mono.react",
                    "graph.runtime.pi_mono.tool_result",
                    "graph.runtime.pi_mono.card_resolve",
                    "graph.runtime.pi_mono.pending",
                    "graph.runtime.*",
                    "graph.runtime.pi_mono.*",
                    "graph.*",
                    "*",
                    "graph.runtime.",
                    "  graph.runtime.pi_mono.react  ",
                    "  *  ",
                ] {
                    let manifest = manifest_with_ui_requirement(is_surface, field, name);
                    let label = if is_surface {
                        "ui.surfaces entry 'chip' requires"
                    } else {
                        "ui.requires"
                    };
                    let expected = format!(
                        "{label}.{field} must not request '{}': graph.runtime.* is reachable only through the agent app",
                        name.trim()
                    );
                    if manifest.validate() != Err(expected.clone()) {
                        failures.push(format!("{expected}; got {:?}", manifest.validate()));
                    }
                }
            }
        }
        assert!(failures.is_empty(), "{}", failures.join("\n"));
    }

    #[test]
    fn ui_runtime_boundary_preserves_unrelated_names_and_capability_wildcards() {
        for is_surface in [false, true] {
            for field in ["capabilities", "queries", "streams"] {
                for name in [
                    "graph.engine.flows.list",
                    "graph.runtime_tools.read",
                    "graph.runtimes.read",
                    "other.graph.runtime.read",
                    "agent.prompt",
                    "observability.snapshot",
                    "core.diag.snapshot",
                    "core.apps.restart",
                ] {
                    let result = manifest_with_ui_requirement(is_surface, field, name).validate();
                    assert!(result.is_ok(), "{is_surface}/{field}/{name}: {result:?}");
                }
            }
            for name in [
                "graph.engine.*",
                "graph.runtime_tools.*",
                "agent.*",
                "core.*",
            ] {
                let result =
                    manifest_with_ui_requirement(is_surface, "capabilities", name).validate();
                assert!(result.is_ok(), "{is_surface}/{name}: {result:?}");
            }
        }
    }

    #[test]
    fn ui_runtime_boundary_does_not_relax_requirement_syntax() {
        for is_surface in [false, true] {
            for field in ["capabilities", "queries", "streams"] {
                for name in [
                    "",
                    "  ",
                    "graph*",
                    "gra*",
                    "graph..read",
                    "Graph.read",
                    "agent/read",
                    "agent.",
                ] {
                    let error = manifest_with_ui_requirement(is_surface, field, name)
                        .validate()
                        .unwrap_err();
                    assert!(
                        !error.contains("reachable only through the agent app"),
                        "{error}"
                    );
                }
            }
            for field in ["queries", "streams"] {
                for name in ["graph.engine.*", "agent.*"] {
                    let error = manifest_with_ui_requirement(is_surface, field, name)
                        .validate()
                        .unwrap_err();
                    assert!(error.contains("invalid"), "{error}");
                }
            }
        }
        // The runtime diagnostic must not make bare '*' generally valid syntax.
        for field in ["capabilities", "queries", "streams"] {
            let manifest = manifest_with_ui_requirement(false, field, "*");
            assert!(manifest.ui.unwrap().requires.resolved().is_err());
        }
    }

    #[test]
    fn ui_runtime_boundary_preserves_backend_requirements() {
        for nested in [false, true] {
            let mut manifest = manifest_with_ui();
            let requires = if nested {
                &mut manifest.capabilities.requires
            } else {
                &mut manifest.requires
            };
            *requires = vec![
                "graph.runtime.pi_mono.react".to_string(),
                "graph.runtime.*".to_string(),
            ];
            assert!(manifest.validate().is_ok());
            assert_eq!(
                manifest.resolved_requires().unwrap(),
                vec!["graph.runtime.pi_mono.react", "graph.runtime.*"]
            );
        }
    }

    #[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));
    }

    // ── GovernorManifest latency_class (app lease engine §8, Task 1) ────────────

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

    #[test]
    fn latency_class_parses_declared_interactive() {
        let json = r#"{
            "name": "example",
            "version": "1.0.0",
            "app_type": "bun",
            "governor": {"latency_class": "interactive"}
        }"#;
        let m = parse_ok(json);
        let governor = m.governor.expect("governor block should parse");
        assert_eq!(governor.latency_class, Some(LatencyClass::Interactive));
    }

    #[test]
    fn latency_class_parses_declared_background() {
        let parsed: GovernorManifest =
            serde_json::from_str(r#"{"latency_class": "background"}"#).unwrap();
        assert_eq!(parsed.latency_class, Some(LatencyClass::Background));
    }

    #[test]
    fn latency_class_invalid_value_is_parse_error() {
        let result: Result<GovernorManifest, _> =
            serde_json::from_str(r#"{"latency_class": "urgent"}"#);
        assert!(result.is_err(), "unknown latency_class value must fail to parse");
    }

    #[test]
    fn latency_class_as_str_and_from_str_roundtrip() {
        for class in [LatencyClass::Interactive, LatencyClass::Background] {
            let s = class.as_str();
            assert_eq!(LatencyClass::from_str(s), Ok(class));
        }
        assert!(LatencyClass::from_str("urgent").is_err());
    }

    // ── UI-only stage apps (burger-07, Plans 07a/07b Contracts F5) ───────────

    fn ui_only_manifest() -> serde_json::Value {
        serde_json::json!({
            "manifest_version": 2, "abi": "v1", "name": "burger-runtime", "version": "1.0.0",
            "auto_start": false, "has_ui": true, "ui_path": "ui/dist",
            "ui": {
                "kind": "stage", "entry": "ui/dist/main.js", "title": "Burger", "icon": "ui/dist/icon.svg",
                "nav": { "section": "system", "order": 90 }, "ui_api": 1,
                "requires": {
                    "capabilities": ["core.runtime.burger_snapshot", "core.runtime.burger_logs"],
                    "queries": [], "streams": ["app.burger_metrics"]
                },
                "data": {
                    "namespace": "burger-runtime", "offline": "online-only", "sync": "snapshot",
                    "queries": [{ "name": "burger-runtime.snapshot.v1", "capability": "core.runtime.burger_snapshot", "kind": "snapshot" }],
                    "streams": [{ "name": "burger-runtime.metrics.v1", "kind": "events" }]
                },
                "integrity": { "ui/dist/main.js": "a".repeat(64), "ui/dist/icon.svg": "b".repeat(64) }
            }
        })
    }

    fn ui_only_with(key: &str, value: serde_json::Value) -> String {
        let mut manifest = ui_only_manifest();
        manifest[key] = value;
        manifest.to_string()
    }

    #[test]
    fn a_stage_manifest_without_app_type_or_entrypoint_is_ui_only() {
        let m = parse_ok(&ui_only_manifest().to_string());
        assert_eq!(m.app_type, AppType::UiOnly);
        assert_eq!(m.app_type.as_str(), "ui-only");
        assert_eq!(m.effective_entrypoint(), "", "no backend, no entrypoint");
        assert_eq!(m.effective_hot_reload(), HotReloadKind::Unsupported);
        assert!(m.has_ui);
        let ui = m.ui.as_ref().expect("a ui block");
        assert_eq!(ui.kind, AppUiKind::Stage);
        let data = ui.data.as_ref().expect("the F5 ui.data block validates");
        assert_eq!(data.namespace, "burger-runtime");
        assert_eq!(data.offline, AppDataOfflinePolicy::OnlineOnly);
        assert_eq!(data.queries[0].capability, "core.runtime.burger_snapshot");
        assert_eq!(data.streams[0].name, "burger-runtime.metrics.v1");
    }

    #[test]
    fn a_ui_only_manifest_round_trips_through_its_serialized_form() {
        let m = parse_ok(&ui_only_manifest().to_string());
        let wire = serde_json::to_string(&m).unwrap();
        assert!(wire.contains(r#""app_type":"ui-only""#), "{wire}");
        assert_eq!(parse_ok(&wire).app_type, AppType::UiOnly);
    }

    #[test]
    fn a_ui_only_manifest_refuses_everything_that_implies_a_process() {
        for (key, value) in [
            (
                "provides",
                serde_json::json!({ "burger.runtime.peek": { "description": "x" } }),
            ),
            (
                "capabilities",
                serde_json::json!({ "provides": ["burger.runtime.peek"] }),
            ),
            ("tcp", serde_json::json!({ "preferred_port": 7010 })),
            ("resources", serde_json::json!({ "memory_mb": 16 })),
            (
                "standalone",
                serde_json::json!({ "socket_path": "/run/node/x.sock" }),
            ),
            ("subscribes", serde_json::json!(["system.network.changed"])),
            ("depends_on", serde_json::json!(["cron"])),
        ] {
            let err = parse_err(&ui_only_with(key, value));
            assert!(err.contains("ui-only"), "{key}: {err}");
        }
        let mut explicit_with_entry = ui_only_manifest();
        explicit_with_entry["app_type"] = serde_json::json!("ui-only");
        explicit_with_entry["entrypoint"] = serde_json::json!("dist/index.js");
        assert!(parse_err(&explicit_with_entry.to_string()).contains("'entrypoint'"));
    }

    #[test]
    fn a_ui_only_manifest_must_declare_a_ui_block() {
        let no_ui = r#"{"manifest_version":2,"abi":"v1","name":"x","version":"1.0.0","app_type":"ui-only"}"#;
        assert!(parse_err(no_ui).contains(r#"kind "stage" or "widget""#));
    }

    // ── UI-only widgets (ui.widget-ui-only host feature) ─────────────────────

    /// A composed widget with no backend: the agent chat widget's shape.
    fn ui_only_widget_manifest() -> serde_json::Value {
        serde_json::json!({
            "manifest_version": 2, "abi": "v1", "name": "agent-chat", "version": "1.0.0",
            "has_ui": true, "ui_path": "ui/dist",
            "ui": {
                "kind": "widget", "entry": "ui/dist/main.js", "title": "Agent chat", "ui_api": 2,
                "requires": {
                    "capabilities": ["agent.prompt", "agent.conversation.entries"],
                    "queries": [], "streams": ["app.agent_session"]
                },
                "integrity": { "ui/dist/main.js": "a".repeat(64) }
            }
        })
    }

    fn ui_only_widget_with(key: &str, value: serde_json::Value) -> String {
        let mut manifest = ui_only_widget_manifest();
        manifest[key] = value;
        manifest.to_string()
    }

    #[test]
    fn a_widget_manifest_without_app_type_or_entrypoint_is_ui_only() {
        let m = parse_ok(&ui_only_widget_manifest().to_string());
        assert_eq!(m.app_type, AppType::UiOnly);
        assert_eq!(m.effective_entrypoint(), "", "no backend, no entrypoint");
        assert_eq!(m.effective_hot_reload(), HotReloadKind::Unsupported);
        assert!(m.has_ui);
        assert_eq!(m.ui.as_ref().expect("a ui block").kind, AppUiKind::Widget);

        let mut explicit = ui_only_widget_manifest();
        explicit["app_type"] = serde_json::json!("ui-only");
        let m = parse_ok(&explicit.to_string());
        assert_eq!(m.app_type, AppType::UiOnly);
        let wire = serde_json::to_string(&m).unwrap();
        assert_eq!(parse_ok(&wire).app_type, AppType::UiOnly, "{wire}");
    }

    #[test]
    fn a_ui_only_widget_refuses_everything_that_implies_a_process() {
        for (key, value) in [
            (
                "provides",
                serde_json::json!({ "agent-chat.widget.peek": { "description": "x" } }),
            ),
            (
                "capabilities",
                serde_json::json!({ "provides": ["agent-chat.widget.peek"] }),
            ),
            ("tcp", serde_json::json!({ "preferred_port": 7010 })),
            ("resources", serde_json::json!({ "memory_mb": 16 })),
            (
                "standalone",
                serde_json::json!({ "socket_path": "/run/node/x.sock" }),
            ),
            ("subscribes", serde_json::json!(["system.network.changed"])),
            ("depends_on", serde_json::json!(["agent"])),
        ] {
            let err = parse_err(&ui_only_widget_with(key, value));
            assert!(err.contains("ui-only"), "{key}: {err}");
        }
        let mut explicit_with_entry = ui_only_widget_manifest();
        explicit_with_entry["app_type"] = serde_json::json!("ui-only");
        explicit_with_entry["entrypoint"] = serde_json::json!("dist/index.js");
        assert!(parse_err(&explicit_with_entry.to_string()).contains("'entrypoint'"));
    }

    #[test]
    fn a_ui_only_widget_keeps_the_widget_rules() {
        let mut with_nav = ui_only_widget_manifest();
        with_nav["ui"]["nav"] = serde_json::json!({ "section": "system", "order": 1 });
        assert!(parse_err(&with_nav.to_string()).contains("widget ui must omit nav metadata"));

        let data = |namespace: &str| {
            serde_json::json!({
                "namespace": namespace, "offline": "online-only", "sync": "snapshot",
                "queries": [], "streams": []
            })
        };
        let mut foreign_data = ui_only_widget_manifest();
        foreign_data["ui"]["data"] = data("agent");
        assert!(parse_err(&foreign_data.to_string()).contains("must equal the app name"));

        let mut own_data = ui_only_widget_manifest();
        own_data["ui"]["data"] = data("agent-chat");
        assert_eq!(parse_ok(&own_data.to_string()).app_type, AppType::UiOnly);
    }

    /// A widget that declares a backend keeps its declared type: dropping
    /// `app_type` and `entrypoint` is what makes it UI-only, nothing else.
    #[test]
    fn a_widget_with_a_backend_is_not_ui_only() {
        let mut bun = ui_only_widget_manifest();
        bun["app_type"] = serde_json::json!("bun");
        bun["entrypoint"] = serde_json::json!("dist/index.js");
        assert_eq!(parse_ok(&bun.to_string()).app_type, AppType::Bun);
    }

    #[test]
    fn declaring_app_type_or_entrypoint_keeps_the_existing_defaults() {
        assert_eq!(
            parse_ok(r#"{"name":"cron","version":"1.0.0"}"#).app_type,
            AppType::Native
        );
        let mut with_entry = ui_only_manifest();
        with_entry["entrypoint"] = serde_json::json!("app.so");
        assert_eq!(parse_ok(&with_entry.to_string()).app_type, AppType::Native);
        let mut bun = ui_only_manifest();
        bun["app_type"] = serde_json::json!("bun");
        assert_eq!(parse_ok(&bun.to_string()).app_type, AppType::Bun);
    }

    #[test]
    fn declares_ui_only_accepts_the_derived_and_the_explicit_form_only() {
        assert!(declares_ui_only(&ui_only_manifest()));
        assert!(declares_ui_only(
            &serde_json::json!({ "app_type": "ui-only" })
        ));
        assert!(!declares_ui_only(
            &serde_json::json!({ "app_type": "bun", "ui": {} })
        ));
        assert!(!declares_ui_only(
            &serde_json::json!({ "entrypoint": "app.so", "ui": {} })
        ));
        assert!(!declares_ui_only(&serde_json::json!({ "name": "cron" })));
        assert!(!declares_ui_only(&serde_json::json!("ui-only")));
    }
}

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

    /// The SAME corpus the kernel validator runs
    /// (`client/kernel/src/stages/stage-registry-contract.test.js`). Two independent
    /// implementations of one contract, with nothing but this comparing them —
    /// whichever side drifts fails here.
    #[test]
    fn shared_app_data_corpus_matches_the_host_validator() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("fixtures/app-data");
        let mut checked = 0;
        for entry in std::fs::read_dir(&dir).expect("fixture directory must exist") {
            let path = entry.expect("readable entry").path();
            if path.extension().and_then(|e| e.to_str()) != Some("json") {
                continue;
            }
            let fixture: serde_json::Value =
                serde_json::from_str(&std::fs::read_to_string(&path).expect("readable fixture"))
                    .expect("valid fixture json");
            let name = path
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or("?")
                .to_string();
            // `notes`: the app name the kernel half of this corpus uses, and the
            // namespace every corpus fixture declares — a data namespace must
            // equal its app name (`validate_app_data_namespace_owner`).
            let manifest = serde_json::json!({
                "manifest_version": 2, "abi": "v1", "name": "notes", "version": "0.1.0",
                "app_type": "bun", "entrypoint": "dist/index.js",
                "ui": fixture["ui"],
            });
            let result = AppManifest::from_json(&manifest.to_string()).and_then(|m| m.validate());
            match fixture["expect"].as_str().expect("expect field") {
                "accept" => assert!(result.is_ok(), "{name} should be accepted: {result:?}"),
                "reject" => {
                    let error = result.expect_err(&format!("{name} should be rejected"));
                    let reason = fixture["reason"]
                        .as_str()
                        .expect("reject fixtures need a reason");
                    assert!(
                        error.contains(reason),
                        "{name}: {error:?} should mention {reason:?}"
                    );
                }
                other => panic!("{name}: unknown expect {other:?}"),
            }
            checked += 1;
        }
        // Guards against a silently empty or mis-globbed corpus reporting success.
        assert!(checked >= 10, "expected the full corpus, walked {checked}");
    }
}

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

    #[test]
    fn burger_app_type_parses_with_bundle_entrypoint_default() {
        let m = AppManifest::from_json(r#"{"name":"did","version":"2.0.0","app_type":"burger"}"#)
            .expect("burger manifest parses");
        assert_eq!(m.app_type, AppType::Burger);
        assert_eq!(m.app_type.as_str(), "burger");
        assert_eq!(m.effective_entrypoint(), "dist/index.js");
        assert_eq!(m.effective_hot_reload(), HotReloadKind::Supported);
        assert!(m.resources.is_none());
    }

    #[test]
    fn resources_memory_mb_is_carried() {
        let m = AppManifest::from_json(
            r#"{"name":"did","version":"2.0.0","app_type":"burger","resources":{"memory_mb":48}}"#,
        )
        .expect("resources block parses");
        assert_eq!(
            m.resources,
            Some(ResourcesManifest { memory_mb: Some(48), callback_deadline_ms: None })
        );
    }

    #[test]
    fn resources_callback_deadline_ms_is_carried() {
        let m = AppManifest::from_json(
            r#"{"name":"did","version":"2.0.0","app_type":"burger","resources":{"callback_deadline_ms":750}}"#,
        )
        .expect("callback deadline parses");
        assert_eq!(
            m.resources,
            Some(ResourcesManifest { memory_mb: None, callback_deadline_ms: Some(750) })
        );
        let max = AppManifest::from_json(
            r#"{"name":"did","version":"2.0.0","app_type":"burger","resources":{"callback_deadline_ms":600000}}"#,
        )
        .expect("the maximum is inclusive");
        assert_eq!(
            max.resources.and_then(|r| r.callback_deadline_ms),
            Some(MAX_CALLBACK_DEADLINE_MS)
        );
    }

    #[test]
    fn resources_callback_deadline_ms_out_of_range_is_rejected() {
        for bad in ["0", "600001"] {
            let json = format!(
                r#"{{"name":"did","version":"2.0.0","app_type":"burger","resources":{{"callback_deadline_ms":{bad}}}}}"#
            );
            let err = AppManifest::from_json(&json).expect_err("out-of-range callback deadline");
            assert!(err.contains("resources.callback_deadline_ms"), "{bad}: {err}");
        }
    }

    #[test]
    fn resources_callback_deadline_ms_must_be_a_positive_integer() {
        for bad in ["-1", "1.5", "\"5000\""] {
            let json = format!(
                r#"{{"name":"did","version":"2.0.0","app_type":"burger","resources":{{"callback_deadline_ms":{bad}}}}}"#
            );
            assert!(
                AppManifest::from_json(&json).is_err(),
                "callback_deadline_ms={bad} must be rejected"
            );
        }
    }

    #[test]
    fn resources_memory_mb_zero_is_rejected() {
        let err = AppManifest::from_json(
            r#"{"name":"did","version":"2.0.0","app_type":"burger","resources":{"memory_mb":0}}"#,
        )
        .expect_err("a zero memory limit is invalid");
        assert!(err.contains("resources.memory_mb"), "{err}");
    }

    #[test]
    fn burger_manifest_rejects_a_standalone_block() {
        let err = AppManifest::from_json(
            r#"{"name":"did","version":"2.0.0","app_type":"burger","standalone":{"socket_path":"/run/node-app-did.sock"}}"#,
        )
        .expect_err("standalone block is only valid for standalone apps");
        assert!(err.contains("only valid when app_type == 'standalone'"), "{err}");
    }
}