frame-host 0.3.0

//! The single `frame.toml` that describes the whole stack.
//!
//! One config file, two sections:
//!
//! - `[frame]` — the console HTTP server: `bind`, `assets`, `auth_token`
//!   (surfaced to the page verbatim; empty = open server), optional `channel`.
//! - `[bus]` — the embedded messaging-bus component (liminal). This section
//!   deserializes into liminal's own
//!   [`liminal_server::config::ServerConfig`], so the bus validates its own
//!   section (required fields, `deny_unknown_fields`, channel-schema loading).
//!
//! **Defaults policy (BINDING ruling, 2026-07-21):** a required key that has
//! only one value it could possibly hold is FORBIDDEN from being required —
//! it defaults to that value, PROVEN from the deployed demos or the scaffold
//! template, never invented. Genuinely deployment-specific values (bind
//! addresses, file paths, channel names, document ids, auth tokens) stay
//! required with the existing loud errors. Because `ServerConfig` and its
//! nested `WebSocketConfig` are liminal's OWN external types (this crate
//! depends on the published `liminal-server` crate and cannot add
//! `#[serde(default)]` attributes to them), the handful of bus-section
//! defaults this ruling adds (`drain_timeout_ms`, `[bus.websocket].path`,
//! `[bus.websocket].allowed_origins`) are injected into the raw TOML table by
//! this module's private `apply_bus_defaults` helper BEFORE the table is
//! handed to liminal's own `ServerConfig` deserializer — a declared value is
//! always left untouched and reaches liminal's own validation exactly as
//! before. See `apply_bus_defaults` for the per-key sourcing.
//!
//! **Compatibility window:** the pre-rename section name `[liminal]` (with
//! `[liminal.websocket]`) still parses as an alias of `[bus]`, but every
//! acceptance logs a loud `tracing::warn!` deprecation naming the new section.
//! Declaring both sections is refused. The alias is removed after one window.
//!
//! Because the embedded bus's WebSocket address is derived from THIS one
//! configured section (see [`crate::embedded`]), the page's `busEndpoint`
//! and the server's actual bound listener can never drift — there is exactly
//! one source of truth.

use std::collections::BTreeMap;
use std::net::SocketAddr;
use std::path::{Path, PathBuf};

use liminal_server::config::{ServerConfig, ServiceProfile, apply_env_overrides, validate};
use serde::Deserialize;

use crate::error::HostError;

/// The raw `frame.toml` shape: the console section plus the embedded bus
/// section under its primary name (`[bus]`) or its deprecated alias
/// (`[liminal]`). Exactly one of the two must be present; [`FrameConfig::load`]
/// enforces that and logs the deprecation on the alias.
///
/// The bus sections are captured as raw [`toml::Value`] tables rather than
/// `ServerConfig` directly: [`FrameConfig::load`] injects frame-host's own
/// proven defaults into the table (see [`apply_bus_defaults`]) BEFORE handing
/// it to liminal's own `ServerConfig` deserializer, since `ServerConfig` is
/// an external type this crate cannot annotate.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RawFrameConfig {
    /// Console HTTP server configuration.
    frame: FrameSection,
    /// Optional document-service binding (IRIDIUM-A3 R11).
    document: Option<DocumentSection>,
    /// Embedded bus component configuration — the primary section name.
    bus: Option<toml::Value>,
    /// DEPRECATED alias of `[bus]`, kept for one compatibility window.
    liminal: Option<toml::Value>,
}

/// The parsed `frame.toml`: the console section plus the embedded bus
/// section (liminal's own config type).
#[derive(Debug)]
pub struct FrameConfig {
    /// Console HTTP server configuration.
    pub frame: FrameSection,
    /// The optional `[document]` binding: when present, the host boots the
    /// document service (IRIDIUM-A3 R11) against the embedded bus.
    pub document: Option<DocumentSection>,
    /// Embedded bus component configuration — liminal's own config type,
    /// validated by liminal's own validator.
    pub bus: ServerConfig,
    /// Whether the embedded bus's `[bus.websocket].allowed_origins` list is
    /// DERIVED (the operator did not state it) rather than stated verbatim.
    ///
    /// When `true`, [`Self::finalize_page_origins`] fills the list from the
    /// page server's REAL bound address once it is known
    /// ([`crate::page::PageServer::resolve`]) — both the `127.0.0.1` and the
    /// `localhost` spelling — so the served page's own origin is always
    /// allow-listed. When `false` the operator's explicit list is LAW and is
    /// never touched (2026-07-22 portless ruling: stated config remains
    /// authoritative, no silent fallback).
    pub page_origins_derived: bool,
    /// Whether the whole port topology is stated verbatim by the operator:
    /// `[frame].bind` is present AND `[bus.websocket].allowed_origins` is
    /// stated. Only a fully-stated topology has any port coherence to check
    /// (`frame check`); a derived/portless one is coherent by construction.
    pub ports_explicit: bool,
}

/// The `[frame]` section: everything the console HTTP server needs.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FrameSection {
    /// Socket address the console HTTP server binds, e.g. `127.0.0.1:4173`.
    ///
    /// Optional (2026-07-22 portless ruling). When present it is LAW: the page
    /// server binds exactly this address and a taken port is a loud failure
    /// (never a silent move). When absent the host prefers `127.0.0.1:4190` and
    /// walks forward to the next free port, printing the chosen URL loudly on
    /// boot — see [`crate::page::PageServer::resolve`]. Either way the page's
    /// REAL bound address is what flows into the derived
    /// `[bus.websocket].allowed_origins` and the boot log line, so the two can
    /// never drift.
    #[serde(default)]
    pub bind: Option<SocketAddr>,
    /// Directory containing the static console bundle (`index.html` at root).
    pub assets: PathBuf,
    /// Bearer token surfaced to the page verbatim as `authToken`. Required key
    /// — the operator states it, the binary never invents it. An explicitly
    /// empty value (`auth_token = ""`) is legal and means an open server,
    /// matching the console's config contract.
    pub auth_token: String,
    /// Feed channel surfaced to the page as `channel`. Absent → the field is
    /// omitted and the page applies the SDK's default channel. When present it
    /// must be non-empty (the console refuses an empty channel).
    #[serde(default)]
    pub channel: Option<String>,
}

/// The `[document]` section (IRIDIUM-A3 R11): the document binding.
///
/// Deployment-identity fields (`id`, `language`, `content_path`,
/// `component_id`, `feed_channel`, `authoring_channel`, `state_dir`) stay
/// fully required — A1 constraint 9's no-assumed-defaults law still governs
/// them, since each one is a genuinely deployment-specific decision with no
/// single "the" value. The five pure tuning/presentation knobs below
/// (`lease_expiry_ms`, `journal_length_bound`, `quiesce_window_ms`,
/// `dark_theme`, `blink_interval_ms`) are amended by the 2026-07-21 BINDING
/// ruling (the same amendment that gave `syntax_theme` its built-in default):
/// every known deployment types the identical value, so requiring the
/// operator to retype it is exactly the "stupid required key" the ruling
/// forbids. `frame_authority::AuthorityConfig::declare` (constraint 9's
/// actual enforcement point) still receives an explicit, concrete,
/// non-invented value either way — the default only decides where that
/// value comes from when the key is absent.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DocumentSection {
    /// The bound document id (`[a-z0-9-]+`).
    pub id: String,
    /// The document language.
    pub language: String,
    /// The initial content source, resolved relative to the config file.
    pub content_path: PathBuf,
    /// The component instance id on every feed envelope (`[a-z0-9-]+`).
    pub component_id: String,
    /// The feed channel: the service publishes; every page subscribes.
    pub feed_channel: String,
    /// The authoring channel: pages publish; the service subscribes.
    pub authoring_channel: String,
    /// The frame-state store directory, resolved relative to the config
    /// file.
    pub state_dir: PathBuf,
    /// Lease expiry (§5.5 policy), milliseconds. Optional — absent defaults
    /// to [`DEFAULT_LEASE_EXPIRY_MS`], the value every known
    /// `[document]`-enabled deployment declares
    /// (`examples/code-view-console/frame.toml`, matching the live deployed
    /// demo `~/.frame-demo/code-view/frame.toml`). A present-but-zero value
    /// still refuses loudly (`FrameConfig::check_document_contract`).
    #[serde(default = "default_lease_expiry_ms")]
    pub lease_expiry_ms: u64,
    /// The journal-length snapshot bound (T3(i) signal 3). Optional —
    /// absent defaults to [`DEFAULT_JOURNAL_LENGTH_BOUND`], sourced the same
    /// way as [`Self::lease_expiry_ms`].
    #[serde(default = "default_journal_length_bound")]
    pub journal_length_bound: u64,
    /// The quiesce debounce window (T3(i) signal 4), milliseconds. Optional
    /// — absent defaults to [`DEFAULT_QUIESCE_WINDOW_MS`], sourced the same
    /// way as [`Self::lease_expiry_ms`].
    #[serde(default = "default_quiesce_window_ms")]
    pub quiesce_window_ms: u64,
    /// The publisher-seat dark-mode presentation input (C5). Optional —
    /// absent defaults to [`DEFAULT_DARK_THEME`], sourced the same way as
    /// [`Self::lease_expiry_ms`].
    #[serde(default = "default_dark_theme")]
    pub dark_theme: bool,
    /// The component's cursor-blink interval (T4), milliseconds — a
    /// component policy value carried by frame.toml per constraint 12 and
    /// advertised to the page. Optional — absent defaults to
    /// [`DEFAULT_BLINK_INTERVAL_MS`], sourced the same way as
    /// [`Self::lease_expiry_ms`].
    #[serde(default = "default_blink_interval_ms")]
    pub blink_interval_ms: u64,
    /// The publisher-seat syntax-theme presentation input (C5, amended
    /// 2026-07-21): capture-name → `#rrggbb` hex colour, TOML table.
    /// Optional — when absent, [`crate::doc_binding::DocBinding::boot`]
    /// falls back to the built-in default palette
    /// ([`crate::syntax_theme::default_syntax_theme`], copied from the
    /// proven `SYNTAX_THEME` in `examples/code-view-console/src/fake-feed.ts`).
    /// When present, this table REPLACES the built-in default WHOLESALE —
    /// there is no per-key merging with the default (merging would invent
    /// behaviour nobody asked for). Every declared value must be `#rrggbb`
    /// hex; [`FrameConfig::load`] fails loudly on a malformed or
    /// non-string entry rather than dropping it silently.
    #[serde(default)]
    pub syntax_theme: Option<BTreeMap<String, String>>,
}

/// Proven `[document].lease_expiry_ms` default (milliseconds), source:
/// `examples/code-view-console/frame.toml` L36, matching the live deployed
/// demo `~/.frame-demo/code-view/frame.toml`.
pub const DEFAULT_LEASE_EXPIRY_MS: u64 = 30_000;
/// Proven `[document].journal_length_bound` default, source:
/// `examples/code-view-console/frame.toml` L37, matching the live deployed
/// demo.
pub const DEFAULT_JOURNAL_LENGTH_BOUND: u64 = 256;
/// Proven `[document].quiesce_window_ms` default (milliseconds), source:
/// `examples/code-view-console/frame.toml` L38, matching the live deployed
/// demo.
pub const DEFAULT_QUIESCE_WINDOW_MS: u64 = 2_000;
/// Proven `[document].dark_theme` default, source:
/// `examples/code-view-console/frame.toml` L39, matching the live deployed
/// demo.
pub const DEFAULT_DARK_THEME: bool = true;
/// Proven `[document].blink_interval_ms` default (milliseconds), source:
/// `examples/code-view-console/frame.toml` L40, matching the live deployed
/// demo.
pub const DEFAULT_BLINK_INTERVAL_MS: u64 = 530;

const fn default_lease_expiry_ms() -> u64 {
    DEFAULT_LEASE_EXPIRY_MS
}
const fn default_journal_length_bound() -> u64 {
    DEFAULT_JOURNAL_LENGTH_BOUND
}
const fn default_quiesce_window_ms() -> u64 {
    DEFAULT_QUIESCE_WINDOW_MS
}
const fn default_dark_theme() -> bool {
    DEFAULT_DARK_THEME
}
const fn default_blink_interval_ms() -> u64 {
    DEFAULT_BLINK_INTERVAL_MS
}

/// The closed hex-colour grammar the wire enforces (`#rrggbb`, matching
/// `frame_editor_wire::snapshot`'s `validate_syntax_theme` and the
/// console's `hexColor` codec check), checked at config load so a doomed
/// theme value fails here, not at first encode.
fn is_hex_color(value: &str) -> bool {
    value.len() == 7
        && value.starts_with('#')
        && value[1..].bytes().all(|byte| byte.is_ascii_hexdigit())
}

/// The closed ASCII id grammar the wire enforces (`[a-z0-9-]+`), checked
/// at config load so a doomed id fails here, not at first encode.
fn is_wire_id(value: &str) -> bool {
    !value.is_empty()
        && value
            .bytes()
            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
}

/// Proven `[bus].drain_timeout_ms` default (milliseconds). Source: every
/// known deployment types the identical value —
/// `examples/code-view-console/frame.toml` L38 (`drain_timeout_ms = 1000`,
/// matching the live deployed demo `~/.frame-demo/code-view/frame.toml`),
/// `crates/frame-cli/templates/frame.toml` L19 (the scaffold every new app
/// starts from), and `docs/guides/BUILDING-APPS.md`'s worked example.
pub const DEFAULT_BUS_DRAIN_TIMEOUT_MS: i64 = 1_000;

/// Proven `[bus.websocket].path` default. Source: every known deployment
/// types the identical value — `examples/code-view-console/frame.toml`
/// (matching the live deployed demo), `crates/frame-cli/templates/frame.toml`
/// L27 (the scaffold every new app starts from), and
/// `docs/guides/BUILDING-APPS.md`'s worked example. `WebSocketConfig::path`
/// (liminal-server's own type) still requires the value to start with `/`;
/// this default satisfies that grammar.
pub const DEFAULT_WEBSOCKET_PATH: &str = "/liminal";

/// The OS-assigned bind sentinel for an internal endpoint that carries no
/// stated address (2026-07-22 portless ruling): binding `127.0.0.1:0` lets
/// the kernel pick a free port, and [`crate::embedded::EmbeddedLiminal`]
/// captures the REAL bound address via each listener's `local_addr`, which is
/// what `/frame/config.json` advertises to the page. A synthesized portless
/// `[bus]` uses this for its wire, health, and WebSocket listeners.
const OS_ASSIGNED: &str = "127.0.0.1:0";

/// Injects frame-host's own proven bus-section defaults into the raw
/// `[bus]` (or `[liminal]` alias) TOML table BEFORE it is handed to
/// liminal's own `ServerConfig` deserializer.
///
/// `ServerConfig` and its nested `WebSocketConfig` are liminal's OWN
/// external types (this crate depends on the published `liminal-server`
/// crate and cannot add `#[serde(default)]` attributes to them), so this is
/// the frame-host-owned seam where the 2026-07-21 BINDING defaults ruling
/// is enforced for the bus section: a key the operator DID declare is left
/// byte-identical and reaches liminal's own validation exactly as before; a
/// key the operator omitted gets the proven default documented at its call
/// site.
///
/// Defaulted:
/// - `drain_timeout_ms` → [`DEFAULT_BUS_DRAIN_TIMEOUT_MS`] (milliseconds).
/// - `websocket.path` → [`DEFAULT_WEBSOCKET_PATH`], but ONLY when a
///   `[bus.websocket]` table is already present — the section itself stays
///   required (embedded frame mode has nowhere for the browser to connect
///   without it; `FrameConfig::check_embedded_mode` still refuses an absent
///   section).
///
/// `allowed_origins` is deliberately NOT defaulted here (2026-07-22 portless
/// ruling): the served page's origin is the page server's REAL bound address,
/// which is not known until [`crate::page::PageServer::resolve`] has walked to
/// a free port. When the operator did not state the list,
/// [`FrameConfig::load`] records [`FrameConfig::page_origins_derived`] and
/// [`FrameConfig::finalize_page_origins`] fills it from that real address at
/// boot — both the `127.0.0.1` and `localhost` spellings — before the bus
/// binds. A stated list is LAW and never touched.
///
/// # Errors
///
/// Returns [`HostError::ConfigParse`] if `bus` (or a present `websocket`
/// key inside it) is not a TOML table — a genuinely malformed shape that
/// would fail liminal's own deserializer anyway; caught here with a
/// frame-host-flavoured message instead of a generic serde one.
fn apply_bus_defaults(mut bus: toml::Value, path: &Path) -> Result<toml::Value, HostError> {
    let table = bus.as_table_mut().ok_or_else(|| HostError::ConfigParse {
        path: path.to_path_buf(),
        detail: "[bus] (or [liminal]) must be a TOML table".to_owned(),
    })?;

    table
        .entry("drain_timeout_ms")
        .or_insert_with(|| toml::Value::Integer(DEFAULT_BUS_DRAIN_TIMEOUT_MS));

    if let Some(websocket_value) = table.get_mut("websocket") {
        let websocket = websocket_value
            .as_table_mut()
            .ok_or_else(|| HostError::ConfigParse {
                path: path.to_path_buf(),
                detail: "[bus.websocket] (or [liminal.websocket]) must be a TOML table".to_owned(),
            })?;
        websocket
            .entry("path")
            .or_insert_with(|| toml::Value::String(DEFAULT_WEBSOCKET_PATH.to_owned()));
    }

    Ok(bus)
}

/// Synthesizes the raw `[bus]` TOML table for a PORTLESS scaffold — a
/// `frame.toml` that states no `[bus]` section at all (2026-07-22 portless
/// ruling).
///
/// The host owns the whole shape: the wire, health, and WebSocket listeners
/// bind OS-assigned free ports ([`OS_ASSIGNED`]); the single channel is the
/// application's own `[frame].channel` (the one place a portless scaffold
/// names its channel); routing is empty; the WebSocket upgrade path is the
/// proven [`DEFAULT_WEBSOCKET_PATH`]. `allowed_origins` is intentionally
/// omitted here and derived from the real page address at boot (see
/// [`apply_bus_defaults`]). Every field frame-host authors is correct by
/// construction, so [`FrameConfig::load`] skips liminal's own port-non-zero
/// validation for this synthesized shape — the `:0` sentinels are intentional
/// and resolved by the OS at bind, exactly the state liminal's validator was
/// written to forbid for an operator-authored file.
///
/// The channel name is the single deployment-specific value; it comes from
/// the required `[frame].channel`. A portless scaffold with no `[frame].channel`
/// has nothing to name its bus channel and is refused loudly by the caller.
fn synthesize_portless_bus(channel: &str) -> toml::Value {
    let mut channel_entry = toml::value::Table::new();
    channel_entry.insert("name".to_owned(), toml::Value::String(channel.to_owned()));
    channel_entry.insert("durable".to_owned(), toml::Value::Boolean(false));

    let mut websocket = toml::value::Table::new();
    websocket.insert(
        "listen_address".to_owned(),
        toml::Value::String(OS_ASSIGNED.to_owned()),
    );

    let mut table = toml::value::Table::new();
    table.insert(
        "listen_address".to_owned(),
        toml::Value::String(OS_ASSIGNED.to_owned()),
    );
    table.insert(
        "health_listen_address".to_owned(),
        toml::Value::String(OS_ASSIGNED.to_owned()),
    );
    table.insert(
        "channels".to_owned(),
        toml::Value::Array(vec![toml::Value::Table(channel_entry)]),
    );
    table.insert("routing_rules".to_owned(), toml::Value::Array(Vec::new()));
    table.insert("websocket".to_owned(), toml::Value::Table(websocket));
    toml::Value::Table(table)
}

/// Whether the raw `[bus]` (or `[liminal]`) table states
/// `[bus.websocket].allowed_origins` verbatim. A stated list is LAW; an
/// absent one is derived from the real page address at boot.
fn bus_states_allowed_origins(bus: &toml::Value) -> bool {
    bus.as_table()
        .and_then(|table| table.get("websocket"))
        .and_then(toml::Value::as_table)
        .is_some_and(|websocket| websocket.contains_key("allowed_origins"))
}

impl FrameConfig {
    /// Loads and fully validates `frame.toml`.
    ///
    /// Accepts the embedded bus section as `[bus]` (primary), `[liminal]`
    /// (deprecated alias — parsed with a loud `tracing::warn!` naming `[bus]`;
    /// never a silent fallback), or ENTIRELY ABSENT (the portless scaffold,
    /// 2026-07-22 ruling): a missing `[bus]` is synthesized wholesale by
    /// frame-host ([`synthesize_portless_bus`]) with OS-assigned internal
    /// ports and the single channel taken from `[frame].channel`. An
    /// operator-authored bus runs liminal's own validation (channel
    /// `schema_ref` paths resolve relative to the config file's directory,
    /// exactly as standalone liminal resolves them); a synthesized one is
    /// correct by construction and skips only liminal's port-non-zero check
    /// (the `:0` sentinels are intentional). Either way frame-host then
    /// refuses any bus shape the embedded frame server does not faithfully
    /// orchestrate.
    ///
    /// # Errors
    ///
    /// Returns a typed failure for an unreadable file, malformed TOML, both
    /// section spellings present at once, a portless config with no
    /// `[frame].channel` to name its bus channel, an operator bus section
    /// liminal's validator rejects, or an embedded-mode shape refusal.
    pub fn load(path: &Path) -> Result<Self, HostError> {
        let text = std::fs::read_to_string(path).map_err(|source| HostError::ConfigRead {
            path: path.to_path_buf(),
            source,
        })?;
        let RawFrameConfig {
            frame,
            document,
            bus,
            liminal,
        } = toml::from_str(&text).map_err(|error| HostError::ConfigParse {
            path: path.to_path_buf(),
            detail: error.to_string(),
        })?;
        // `synthesized` is true when the operator stated no `[bus]`/`[liminal]`
        // at all: frame-host authors the whole bus shape (OS-assigned ports,
        // the `[frame].channel` channel) and, being correct by construction,
        // skips liminal's operator-facing port-non-zero validation below.
        let (bus, synthesized) = match (bus, liminal) {
            (Some(_), Some(_)) => {
                return Err(HostError::ConfigParse {
                    path: path.to_path_buf(),
                    detail: "both [bus] and [liminal] sections are present; [liminal] is the \
                             deprecated alias of [bus] — declare exactly one section (use [bus])"
                        .to_owned(),
                });
            }
            (Some(bus), None) => (bus, false),
            (None, Some(bus)) => {
                tracing::warn!(
                    config = %path.display(),
                    "frame.toml section [liminal] is DEPRECATED: rename [liminal] to [bus] and \
                     [liminal.websocket] to [bus.websocket]; the [liminal] alias is accepted for \
                     one compatibility window only"
                );
                (bus, false)
            }
            (None, None) => {
                // Portless scaffold: the single deployment-specific value the
                // synthesized bus needs is the channel, and the one place a
                // portless file names it is `[frame].channel`. With neither a
                // `[bus]` nor a `[frame].channel`, the host has nothing to name
                // its bus channel — a loud refusal naming the fix, never a
                // silent invented channel.
                let Some(channel) = frame.channel.as_deref() else {
                    return Err(HostError::ConfigParse {
                        path: path.to_path_buf(),
                        detail: "no [bus] section and no [frame].channel: a portless frame.toml \
                                 derives its embedded bus channel from [frame].channel, so state \
                                 [frame].channel = \"<name>.events\" (or declare a full [bus] \
                                 section to pin ports explicitly)"
                            .to_owned(),
                    });
                };
                (synthesize_portless_bus(channel), true)
            }
        };
        // Whether the operator stated `[bus.websocket].allowed_origins`
        // verbatim: a stated list is LAW; an absent one is derived from the
        // real page address at boot (`finalize_page_origins`). A synthesized
        // portless bus never states it.
        let origins_stated = bus_states_allowed_origins(&bus);
        // Inject frame-host's own proven bus-section defaults into the raw
        // table BEFORE liminal's ServerConfig deserializer sees it — see
        // `apply_bus_defaults` for what is defaulted and why. A key the
        // operator DID declare is left byte-identical.
        let bus = apply_bus_defaults(bus, path)?;
        let bus: ServerConfig =
            bus.try_into()
                .map_err(|error: toml::de::Error| HostError::ConfigParse {
                    path: path.to_path_buf(),
                    detail: error.to_string(),
                })?;
        // Faithful bus load: run liminal's OWN pipeline in liminal's OWN
        // order — environment overrides FIRST, then validation — exactly as
        // standalone liminal's `load_config` does. Omitting the env layer would
        // silently diverge: e.g. `LIMINAL_AUTH_TOKEN` (which liminal uses to
        // inject an `[auth]` section absent from the file) would be ignored,
        // downgrading a token-gated deployment to an open one with no warning.
        // Channel `schema_ref` paths resolve relative to the config file's
        // directory, matching standalone liminal.
        let mut bus =
            apply_env_overrides(bus).map_err(|source| HostError::LiminalConfig { source })?;
        // A synthesized portless bus intentionally binds OS-assigned `:0`
        // ports, exactly the state liminal's operator-facing validator rejects
        // (`listen_address: port must be non-zero`). Every other field is
        // frame-host-authored and correct by construction (one schema-less
        // channel, empty routing, the proven WebSocket path), so validating it
        // would add nothing but a false rejection of the intended `:0`. An
        // operator-authored bus still runs the full validation unchanged.
        if !synthesized {
            validate(&mut bus, path.parent())
                .map_err(|source| HostError::LiminalConfig { source })?;
        }
        let document = match document {
            None => None,
            Some(mut section) => {
                // Resolve the declared paths relative to the config file,
                // exactly as the bus resolves its schema refs.
                if let Some(parent) = path.parent() {
                    if section.content_path.is_relative() {
                        section.content_path = parent.join(&section.content_path);
                    }
                    if section.state_dir.is_relative() {
                        section.state_dir = parent.join(&section.state_dir);
                    }
                }
                Some(section)
            }
        };
        let ports_explicit = frame.bind.is_some() && origins_stated;
        let config = Self {
            frame,
            document,
            bus,
            page_origins_derived: !origins_stated,
            ports_explicit,
        };
        config.check_console_contract()?;
        config.check_embedded_mode()?;
        config.check_document_contract()?;
        Ok(config)
    }

    /// Fills the embedded bus's `[bus.websocket].allowed_origins` from the page
    /// server's REAL bound address once it is known, but ONLY when the operator
    /// did not state the list ([`Self::page_origins_derived`]).
    ///
    /// The served page's origin is `http://<page-addr>`; the browser presents
    /// it on every WebSocket upgrade and liminal's acceptor checks it against
    /// this allow-list (fail-closed when empty). Both the `127.0.0.1` and the
    /// `localhost` spelling of the bound port are added — the exact fix for a
    /// real deployment that died on a 127-vs-localhost Origin mismatch when
    /// only one spelling was allow-listed. Call this AFTER
    /// [`crate::page::PageServer::resolve`] and BEFORE the bus binds
    /// ([`crate::application::Application::boot`]); a stated list is LAW and is
    /// left untouched.
    ///
    /// Idempotent and side-effect-free when the list was stated: the operator's
    /// bytes reach liminal's acceptor exactly as written.
    pub fn finalize_page_origins(&mut self, page_addr: SocketAddr) {
        if !self.page_origins_derived {
            return;
        }
        let Some(websocket) = self.bus.websocket.as_mut() else {
            return;
        };
        let port = page_addr.port();
        websocket.allowed_origins = vec![
            format!("http://127.0.0.1:{port}"),
            format!("http://localhost:{port}"),
        ];
    }

    /// Refuses a `[document]` section the document service would refuse at
    /// boot: bad wire ids, zero policy values, or channels the embedded
    /// bus does not carry — every refusal typed and loud, here rather
    /// than mid-boot.
    fn check_document_contract(&self) -> Result<(), HostError> {
        let Some(document) = &self.document else {
            return Ok(());
        };
        for (field, value) in [
            ("[document].id", document.id.as_str()),
            ("[document].component_id", document.component_id.as_str()),
        ] {
            if !is_wire_id(value) {
                return Err(HostError::ConfigContract {
                    detail: format!("{field} must match [a-z0-9-]+, got {value:?}"),
                });
            }
        }
        if document.feed_channel == document.authoring_channel {
            return Err(HostError::ConfigContract {
                detail: "[document].feed_channel and [document].authoring_channel must be two                          distinct channels (C2: two channels per document)"
                    .to_owned(),
            });
        }
        for (field, channel) in [
            ("[document].feed_channel", &document.feed_channel),
            ("[document].authoring_channel", &document.authoring_channel),
        ] {
            if !self
                .bus
                .channels
                .iter()
                .any(|configured| configured.name == *channel)
            {
                return Err(HostError::ConfigContract {
                    detail: format!(
                        "{field} {channel:?} is not one of the embedded bus's configured \
                         channels: declare it under [bus].channels"
                    ),
                });
            }
        }
        // C8/R11 transport reality, verified at the pinned SDK (0.3.0):
        // the TCP channel-subscription client cannot present an auth token,
        // so the document service cannot subscribe a token-gated bus.
        // Refused loudly here; the upstream ask is recorded in the leg's
        // report.
        if self.bus.auth.is_some() {
            return Err(HostError::ConfigContract {
                detail: "[document] cannot run against a token-gated [bus.auth]: the pinned bus                          SDK's channel subscription presents no auth token (upstream ask                          recorded). Run the embedded bus open, or drop [document]."
                    .to_owned(),
            });
        }
        for (field, value, default) in [
            (
                "[document].lease_expiry_ms",
                document.lease_expiry_ms,
                DEFAULT_LEASE_EXPIRY_MS,
            ),
            (
                "[document].journal_length_bound",
                document.journal_length_bound,
                DEFAULT_JOURNAL_LENGTH_BOUND,
            ),
            (
                "[document].quiesce_window_ms",
                document.quiesce_window_ms,
                DEFAULT_QUIESCE_WINDOW_MS,
            ),
            (
                "[document].blink_interval_ms",
                document.blink_interval_ms,
                DEFAULT_BLINK_INTERVAL_MS,
            ),
        ] {
            if value == 0 {
                return Err(HostError::ConfigContract {
                    detail: format!(
                        "{field} must be positive when declared explicitly; omit the key \
                         entirely to use the documented default of {default}"
                    ),
                });
            }
        }
        if let Some(theme) = &document.syntax_theme {
            for (capture, color) in theme {
                if capture.is_empty() {
                    return Err(HostError::ConfigContract {
                        detail: "[document].syntax_theme keys must be non-empty".to_owned(),
                    });
                }
                if !is_hex_color(color) {
                    return Err(HostError::ConfigContract {
                        detail: format!(
                            "[document].syntax_theme.{capture} must be #rrggbb hex, got {color:?}"
                        ),
                    });
                }
            }
        }
        Ok(())
    }

    /// Refuses `[frame]` values the console's own config contract would reject,
    /// so a doomed config fails loudly here rather than in the browser.
    fn check_console_contract(&self) -> Result<(), HostError> {
        if let Some(channel) = &self.frame.channel
            && channel.is_empty()
        {
            return Err(HostError::ConfigContract {
                detail: "[frame].channel, when present, must be non-empty: the console refuses an \
                         empty channel; omit the key to use the SDK's default channel"
                    .to_owned(),
            });
        }
        // The served /frame/config.json advertises the FULL configured channel
        // list (the console subscribes every one of them). A bus section
        // with zero channels leaves the console with no feed to subscribe — a
        // doomed deployment refused here, not discovered as a browser-side
        // subscribe rejection.
        if self.bus.channels.is_empty() {
            return Err(HostError::ConfigContract {
                detail: "[bus].channels is empty: the console subscribes every configured \
                         channel and serves the list as `channels` in /frame/config.json, so a \
                         zero-channel bus leaves the console with no feed. Declare at least \
                         one [[bus.channels]] entry."
                    .to_owned(),
            });
        }
        // The console's primary channel must be one the embedded bus
        // actually carries: the page refuses a `channels` roster that omits its
        // `channel`, so serving that pair is a composition error caught here.
        if let Some(channel) = &self.frame.channel
            && !self
                .bus
                .channels
                .iter()
                .any(|configured| configured.name == *channel)
        {
            return Err(HostError::ConfigContract {
                detail: format!(
                    "[frame].channel \"{channel}\" is not one of the embedded bus's \
                     configured channels [{roster}]: the console would subscribe a channel the \
                     embedded server does not carry. Name a configured channel or add it to \
                     [bus].channels.",
                    roster = self
                        .bus
                        .channels
                        .iter()
                        .map(|configured| configured.name.as_str())
                        .collect::<Vec<_>>()
                        .join(", ")
                ),
            });
        }
        // If the bus gates connections behind a token but the page is handed an
        // empty one, the browser would present an empty token to a closed
        // server and be refused — a silent "page can't connect". Refuse loudly.
        if self.bus.auth.is_some() && self.frame.auth_token.is_empty() {
            return Err(HostError::ConfigContract {
                detail: "[bus.auth] gates the embedded server behind a token, but \
                         [frame].auth_token is empty: the page would present an empty token and be \
                         refused. Set [frame].auth_token to the token the page must present."
                    .to_owned(),
            });
        }
        Ok(())
    }

    /// Refuses bus shapes the embedded frame server does not faithfully
    /// orchestrate.
    ///
    /// Embedded frame mode runs liminal's single-node **Full** profile with the
    /// **WebSocket transport required** (the browser is a direct bus
    /// participant per D3, so it needs a WebSocket address). Clustered and
    /// worker-front-door deployments have their own boot orchestration in
    /// standalone liminal that this embedding does not reproduce; rather than
    /// silently mis-boot them, they are refused with a typed error.
    fn check_embedded_mode(&self) -> Result<(), HostError> {
        if self.bus.cluster.is_some() {
            return Err(HostError::EmbeddedModeUnsupported {
                detail: "[bus.cluster] is set, but the embedded frame server runs a \
                         single-node deployment and does not start liminal's distribution \
                         cluster. Remove [bus.cluster] or run liminal standalone."
                    .to_owned(),
            });
        }
        match self
            .bus
            .services
            .profile()
            .map_err(|source| HostError::LiminalConfig { source })?
        {
            ServiceProfile::Full => {}
            ServiceProfile::WorkerFrontDoor => {
                return Err(HostError::EmbeddedModeUnsupported {
                    detail: "[bus.services].profile is \"worker-front-door\", but the embedded \
                             frame server runs liminal's \"full\" profile (channels/conversations \
                             back the console feed). Remove the profile override or run liminal \
                             standalone."
                        .to_owned(),
                });
            }
        }
        if self.bus.websocket.is_none() {
            return Err(HostError::EmbeddedModeUnsupported {
                detail: "[bus.websocket] is absent, but the embedded frame server requires it: \
                         the browser connects to the bus's WebSocket directly (D3), so the console \
                         has nowhere to connect without it. Add a [bus.websocket] section."
                    .to_owned(),
            });
        }
        Ok(())
    }
}