veredictum 0.1.4

// SPDX-FileCopyrightText: Veredictum contributors
// SPDX-License-Identifier: Apache-2.0

//! Operation bindings — the wire layer, one file per SM operation per ITS.
//!
//! A binding maps request construction, each outcome kind → wire
//! expectation, and each logical capture → wire source; every mapping cites
//! its OAS source (ITS-REST 1.1.0 `specifications/operations/*.yaml` +
//! `responses/*.yaml`). The capture-source, header-matcher, and
//! body-selector vocabularies are closed.

#![expect(
    clippy::disallowed_types,
    reason = "dev/verification tooling over JSON artifacts (the catalogue, results, wire \
              exchanges), whose shapes belong to the artifacts and the SUT"
)]

use serde::de::Error as DeError;
use serde::{Deserialize, Deserializer, Serialize};

use crate::ids::{CaptureName, SmOperationRef};
use crate::model::case::Applies;
use crate::refgrammar::Template;
use crate::vocab::{FormatName, HttpMethod, ItsName, OutcomeKind};

/// A wire location a capture reads from (closed grammar):
/// `header <Name>` · `header <Name> last-segment` · `body "<path>"` ·
/// `capture <name>`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum WireFrom {
    /// `header <Name>` — a response header's value.
    Header {
        /// The response header field name.
        name: String,
        /// Take only the last `/`-separated segment of the header value.
        last_segment: bool,
    },
    /// `body "<path>"` — a value inside the response body.
    Body {
        /// The path addressing the value inside the response body.
        path: String,
    },
    /// Derive from another capture.
    Capture(CaptureName),
}

impl WireFrom {
    /// Parse the closed source grammar.
    ///
    /// # Errors
    /// Returns a message when the text is outside the grammar.
    pub fn parse(raw: &str) -> Result<Self, String> {
        if let Some(rest) = raw.strip_prefix("header ") {
            let (name, last_segment) = match rest.strip_suffix(" last-segment") {
                Some(name) => (name, true),
                None => (rest, false),
            };
            let name = name.trim();
            if name.is_empty() || name.contains(char::is_whitespace) {
                return Err(format!(
                    "capture source {raw:?}: header name must be one token"
                ));
            }
            return Ok(Self::Header {
                name: name.to_owned(),
                last_segment,
            });
        }
        if let Some(rest) = raw.strip_prefix("body ") {
            let path = rest
                .trim()
                .strip_prefix('"')
                .and_then(|p| p.strip_suffix('"'))
                .ok_or_else(|| format!("capture source {raw:?}: body path must be quoted"))?;
            if path.is_empty() {
                return Err(format!("capture source {raw:?}: empty body path"));
            }
            return Ok(Self::Body {
                path: path.to_owned(),
            });
        }
        if let Some(rest) = raw.strip_prefix("capture ") {
            return CaptureName::parse(rest.trim())
                .map(Self::Capture)
                .map_err(|e| format!("capture source {raw:?}: {e}"));
        }
        Err(format!(
            "capture source {raw:?} is outside the closed grammar (header … | body \"…\" | capture …)"
        ))
    }
}

impl<'de> Deserialize<'de> for WireFrom {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        Self::parse(&s).map_err(D::Error::custom)
    }
}

/// Post-extraction modifier: strip the weak-ETag wrapper.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
pub enum StripRule {
    /// Unwrap a weak `ETag` (`W/"…"`) down to the bare entity tag.
    #[serde(rename = "weak-quotes")]
    WeakQuotes,
}

/// Post-extraction transform over a captured value; the grammar is closed.
///
/// `root-uid` and `creating-system-id` decompose an `OBJECT_VERSION_ID`, whose
/// lexical form ITS-REST `Resources.md` §Identifier types fixes as "the
/// lexical form of `object_id :: creating_system_id :: version_tree_id`".
/// `uppercase` lets a case author a case-variant of a captured identifier,
/// which the reference grammar cannot express (BASE `master05` §"Composite
/// Identifiers and Case": two identifiers "identical apart from case …
/// identify the same thing").
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
pub enum TransformRule {
    /// The leading `object_id` — the `VERSIONED_OBJECT` identifier.
    #[serde(rename = "root-uid")]
    RootUid,
    /// The MIDDLE segment — the identifier of the system that created the
    /// version. Yields nothing when the value carries no middle segment, so
    /// a truncated identifier leaves the capture unbound (loud downstream)
    /// rather than binding the whole value as if it were a system id.
    #[serde(rename = "creating-system-id")]
    CreatingSystemId,
    /// The captured value, ASCII-uppercased.
    #[serde(rename = "uppercase")]
    Uppercase,
}

impl TransformRule {
    /// Apply the transform, or `None` when the value has no such component.
    #[must_use]
    pub fn apply(self, value: &str) -> Option<String> {
        let mut segments = value.split("::");
        match self {
            Self::RootUid => segments.next().map(ToOwned::to_owned),
            Self::CreatingSystemId => {
                let _object_id = segments.next()?;
                segments
                    .next()
                    .filter(|s| !s.is_empty())
                    .map(ToOwned::to_owned)
            }
            Self::Uppercase => Some(value.to_ascii_uppercase()),
        }
    }

    /// All members, in grammar order (schema emission derives from this).
    pub const ALL: &[TransformRule] = &[
        TransformRule::RootUid,
        TransformRule::CreatingSystemId,
        TransformRule::Uppercase,
    ];
}

/// One logical-capture wire mapping with optional modifiers.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WireCapture {
    /// The wire location the value is read from.
    pub from: WireFrom,
    /// Wrapper removed from the extracted value, if any.
    #[serde(default)]
    pub strip: Option<StripRule>,
    /// Component/case transform applied to the extracted value, if any.
    #[serde(default)]
    pub transform: Option<TransformRule>,
    /// Tried when `from` yields nothing (e.g. body field under
    /// `Prefer: return=minimal`, falling back to `Location`).
    #[serde(default)]
    pub fallback: Option<WireFrom>,
}

/// The value-side of a header expectation (closed matcher vocabulary):
/// `present` · `present-with-body` · `absent` · `negotiated` ·
/// `latest-version-uid` · `pattern:<regex>` · a literal string.
///
/// `present?` is not a member: it is the authored shorthand for
/// [`HeaderExpectation`]'s `{ match: present, optional: true }`, which keeps
/// presence-optionality one modifier with one meaning.
#[derive(Debug, Clone, PartialEq)]
pub enum HeaderMatcher {
    /// The header must be present, with any value.
    Present,
    /// The header must be present with any value WHEN the response carries a
    /// content body, and carries no criterion when it does not — the exact
    /// shape of the ITS-REST `Resources.md` §JSON Format sentence "Proper
    /// header `Content-Type: application/json` MUST be present in the response
    /// of the service unless the response has no content body".
    PresentWithBody,
    /// The header must not be present.
    Absent,
    /// Equals the negotiated media type.
    Negotiated,
    /// The stale-precondition 412 rule: `ETag` carries the latest version uid.
    LatestVersionUid,
    /// A pattern; `<name>` placeholders resolve from case variables before
    /// matching (validated by compiling with placeholders wildcarded).
    Pattern(String),
    /// A literal value template.
    Literal(Template),
}

impl HeaderMatcher {
    /// Parse the closed matcher vocabulary.
    ///
    /// # Errors
    /// Returns a message when the pattern does not compile, when a literal
    /// template is malformed, or when the reserved `present?` shorthand is
    /// used where only a matcher belongs.
    pub fn parse(raw: &str) -> Result<Self, String> {
        Ok(match raw {
            "present" => Self::Present,
            "present?" => {
                return Err(
                    "`present?` is the shorthand for `{ match: present, optional: true }` — \
                     in the mapping form declare `optional: true` instead"
                        .to_owned(),
                );
            }
            "present-with-body" => Self::PresentWithBody,
            "absent" => Self::Absent,
            "negotiated" => Self::Negotiated,
            "latest-version-uid" => Self::LatestVersionUid,
            _ => {
                if let Some(pattern) = raw.strip_prefix("pattern:") {
                    let probe = placeholder_wildcarded(pattern);
                    regex::Regex::new(&probe)
                        .map_err(|e| format!("header pattern {pattern:?} does not compile: {e}"))?;
                    Self::Pattern(pattern.to_owned())
                } else {
                    Self::Literal(Template::parse(raw)?)
                }
            }
        })
    }
}

impl<'de> Deserialize<'de> for HeaderMatcher {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        Self::parse(&s).map_err(D::Error::custom)
    }
}

/// One declared header expectation on a wire outcome: a [`HeaderMatcher`]
/// plus the two modifiers a released spec sentence can put on it.
///
/// The authored short form is a bare matcher string (`ETag: present`,
/// `Location: absent`) — unconditional, presence-asserting. The mapping form
/// declares the modifiers:
///
/// ```yaml
/// ETag:
///   match: 'pattern:W/"[^"]+"'
///   optional: true                     # presence is a SHOULD; the form is a MUST
///   applies: { its_rest: ">=1.1.0" }   # the release the rule is dated to
/// ```
///
/// `optional` separates the strength of presence from the strength of form,
/// because ITS-REST `specifications/docs/overview/Requests_and_responses.md`
/// assigns them differently: §"`ETag` and Last-Modified" makes presence a
/// SHOULD ("Both `ETag` and `Last-Modified` SHOULD be included in responses for
/// VERSION, `VERSIONED_OBJECT`, or other resources that have versioning or
/// unique state identifiers"), while §"Deprecated headers" makes the form a
/// MUST ("all `ETag` headers that hold a resource identifier MUST include a
/// weakness indicator `W/`"). An optional expectation is skipped when the
/// header is absent or blank and judged in full when it is there.
///
/// `applies` carries a version floor for the rule, because a released
/// requirement can be dated by its own text. The same chapter dates the `W/`
/// indicator and the `Location` semantics to Release 1.1.0 ("DEPRECATION: Prior
/// to Release 1.1.0, the `ETag` header was used without a weakness indicator
/// `W/`"; "DEPRECATION: Prior to Release 1.1.0, the `Location` header was used
/// to indicate the canonical location of a representation in a response"). A
/// party declaring an earlier release conforms to the text of that release, so
/// the dated matcher is not applied while the operation is still driven. The
/// floor belongs on the matcher rather than the case or the binding: the
/// release dates the header rule, not the operation.
#[derive(Debug, Clone)]
pub struct HeaderExpectation {
    /// The value-side matcher.
    pub matcher: HeaderMatcher,
    /// Presence is not asserted: an absent (or blank) header satisfies the
    /// expectation, a present one is judged by `matcher`.
    pub optional: bool,
    /// The spec-version floor the RULE is dated to; unsatisfied ⇒ the
    /// expectation is out of scope for this party and not judged.
    pub applies: Option<Applies>,
}

impl HeaderExpectation {
    /// An unconditional, presence-asserting expectation around `matcher`.
    #[must_use]
    pub fn new(matcher: HeaderMatcher) -> Self {
        Self {
            matcher,
            optional: false,
            applies: None,
        }
    }
}

impl<'de> Deserialize<'de> for HeaderExpectation {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Mapping {
            #[serde(rename = "match")]
            matcher: HeaderMatcher,
            #[serde(default)]
            optional: bool,
            #[serde(default)]
            applies: Option<Applies>,
        }
        let value = serde_json::Value::deserialize(deserializer)?;
        match value {
            serde_json::Value::String(s) => {
                if s == "present?" {
                    return Ok(Self {
                        matcher: HeaderMatcher::Present,
                        optional: true,
                        applies: None,
                    });
                }
                HeaderMatcher::parse(&s)
                    .map(Self::new)
                    .map_err(D::Error::custom)
            }
            value @ serde_json::Value::Object(_) => {
                let mapping: Mapping = serde_json::from_value(value).map_err(D::Error::custom)?;
                Ok(Self {
                    matcher: mapping.matcher,
                    optional: mapping.optional,
                    applies: mapping.applies,
                })
            }
            other => Err(D::Error::custom(format!(
                "a header expectation is a matcher string or a \
                 {{ match, optional?, applies? }} mapping, got {other}"
            ))),
        }
    }
}

/// Every expectation declared for ONE response header, judged conjunctively.
///
/// The authored form is a single expectation (a bare matcher string or the
/// mapping form) or a sequence of them. A sequence exists because one
/// expectation carries one `optional` and one `applies`, while the released
/// text can date two rules on the same header differently: ITS-REST
/// `Requests_and_responses.md` §"If-Match and accidental overwrites" makes
/// `ETag` the latest `version_uid` for every release, while §"Deprecated
/// headers" makes the `W/` weakness indicator a MUST that §"`ETag` and
/// Last-Modified" dates to Release 1.1.0. Declared as two, each keeps its own
/// ground.
#[derive(Debug, Clone)]
pub struct HeaderExpectations(Vec<HeaderExpectation>);

impl HeaderExpectations {
    /// The declared expectations, in authored order.
    #[must_use]
    pub fn all(&self) -> &[HeaderExpectation] {
        &self.0
    }
}

impl From<Vec<HeaderExpectation>> for HeaderExpectations {
    fn from(expectations: Vec<HeaderExpectation>) -> Self {
        Self(expectations)
    }
}

impl<'de> Deserialize<'de> for HeaderExpectations {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let value = serde_json::Value::deserialize(deserializer)?;
        let declared = match value {
            serde_json::Value::Array(items) => {
                if items.is_empty() {
                    return Err(D::Error::custom(
                        "a header's expectation sequence declares at least one matcher — \
                         an empty sequence asserts nothing",
                    ));
                }
                items
                    .into_iter()
                    .map(|item| serde_json::from_value(item).map_err(D::Error::custom))
                    .collect::<Result<Vec<HeaderExpectation>, D::Error>>()?
            }
            single => vec![serde_json::from_value(single).map_err(D::Error::custom)?],
        };
        Ok(Self(declared))
    }
}

/// The `<name>` placeholders a matcher pattern declares, in order.
///
/// The compile probe below only proves the WILDCARDED form parses as a regex;
/// naming the placeholders is what lets a gate check they can ever resolve
/// (`crate::validate`).
#[must_use]
pub fn placeholder_names(pattern: &str) -> Vec<&str> {
    let mut names = Vec::new();
    let mut rest = pattern;
    while let Some(start) = rest.find('<') {
        let tail = rest.split_at(start).1;
        let Some(end) = tail.find('>') else { break };
        if let Some(name) = tail.get(1..end) {
            names.push(name);
        }
        rest = tail.get(end + 1..).unwrap_or_default();
    }
    names
}

/// Replace `<name>` placeholders with `.*` for the compile probe — the
/// pattern text is a regex (`pattern:<regex>`), so everything else is left
/// verbatim and must compile.
fn placeholder_wildcarded(pattern: &str) -> String {
    let mut out = String::new();
    let mut rest = pattern;
    while let Some(start) = rest.find('<') {
        let (head, tail) = rest.split_at(start);
        out.push_str(head);
        if let Some(end) = tail.find('>') {
            out.push_str(".*");
            rest = tail.get(end + 1..).unwrap_or_default();
        } else {
            out.push_str(tail);
            rest = "";
        }
    }
    out.push_str(rest);
    out
}

/// A response-body expectation (closed selector vocabulary).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
pub enum BodySelector {
    /// Full resource | `{uid}` | empty, per `Prefer`
    /// (ITS-REST `Requests_and_responses.md` §Prefer).
    #[serde(rename = "prefer_conditional")]
    PreferConditional,
    /// Register AMB-217: assert at most that a `message` string is present,
    /// the one member both published error-body shapes carry.
    #[serde(rename = "error_loose")]
    ErrorLoose,
    /// The `RESULT_SET` schema (named distinctly from the `result_set`
    /// assertion).
    #[serde(rename = "result_set_body")]
    ResultSetBody,
    /// Body media type equals the negotiated type.
    #[serde(rename = "negotiated")]
    Negotiated,
    /// A body must be present, of any shape.
    #[serde(rename = "present")]
    Present,
    /// The response must carry no body.
    #[serde(rename = "absent")]
    Absent,
}

/// One outcome kind's wire expectation.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WireExpectation {
    /// The status code the outcome is primarily served with.
    pub status: StatusCode,
    /// Additional non-conflicting status codes the overview permits beyond
    /// the operation's OAS enumeration (ITS-REST `Requests_and_responses.md`
    /// §HTTP status codes: "Additional status codes MAY be used as long as
    /// they do not conflict with the predefined codes"). Each entry's YAML
    /// carries the citation; an observed alt status classifies as this kind
    /// exactly like the primary.
    #[serde(default)]
    pub alt_status: Option<Vec<StatusCode>>,
    /// Per-header expectations, in declaration order.
    #[serde(default, deserialize_with = "crate::model::de::optional_ordered_map")]
    pub headers: Option<Vec<(String, HeaderExpectations)>>,
    /// The body shape the outcome must carry.
    #[serde(default)]
    pub body: Option<BodySelector>,
}

/// An HTTP status code, range-checked at parse.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StatusCode(u16);

impl StatusCode {
    /// The numeric code.
    #[must_use]
    pub fn value(self) -> u16 {
        self.0
    }
}

impl<'de> Deserialize<'de> for StatusCode {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = u16::deserialize(deserializer)?;
        if (100..=599).contains(&raw) {
            Ok(Self(raw))
        } else {
            Err(D::Error::custom(format!("status {raw} outside 100..=599")))
        }
    }
}

/// The request payload of a binding.
#[derive(Debug, Clone, PartialEq)]
pub enum RequestBody {
    /// A named payload role (`composition`, `opt_xml`), optionally optional
    /// (`ehr_status?`).
    Named {
        /// The payload role name the corpus resolves.
        name: String,
        /// The request is legal without this body.
        optional: bool,
    },
    /// A structured body template (the query binding's
    /// `{ q: ${q}, offset: ${offset?} … }`).
    Structured(crate::model::value::TemplatedValue),
    /// The read-modify-write realization of an SM field-setter (AMB-15): the
    /// body is a captured resource with the named fields overwritten.
    Patched {
        /// The case capture holding the current resource body.
        from_capture: CaptureName,
        /// Field overwrites (top-level attribute → literal value).
        set: Vec<(String, serde_json::Value)>,
    },
}

impl<'de> Deserialize<'de> for RequestBody {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let value = serde_json::Value::deserialize(deserializer)?;
        // The patched form: { from_capture: <name>, set: { field: value } }.
        if let serde_json::Value::Object(map) = &value
            && map.contains_key("from_capture")
        {
            let from = map
                .get("from_capture")
                .and_then(serde_json::Value::as_str)
                .ok_or_else(|| D::Error::custom("from_capture must be a capture name"))?;
            let from_capture = CaptureName::parse(from).map_err(D::Error::custom)?;
            let set = map
                .get("set")
                .and_then(serde_json::Value::as_object)
                .ok_or_else(|| D::Error::custom("patched body requires a set mapping"))?
                .iter()
                .map(|(k, v)| (k.clone(), v.clone()))
                .collect();
            if map.len() != 2 {
                return Err(D::Error::custom(
                    "patched body carries exactly from_capture + set",
                ));
            }
            return Ok(Self::Patched { from_capture, set });
        }
        match &value {
            serde_json::Value::String(s) => {
                let (name, optional) = match s.strip_suffix('?') {
                    Some(name) => (name, true),
                    None => (s.as_str(), false),
                };
                if name.is_empty() || name.contains(char::is_whitespace) {
                    return Err(D::Error::custom(format!(
                        "request body role {s:?} must be one token"
                    )));
                }
                Ok(Self::Named {
                    name: name.to_owned(),
                    optional,
                })
            }
            serde_json::Value::Object(_) => crate::model::value::TemplatedValue::from_value(&value)
                .map(Self::Structured)
                .map_err(D::Error::custom),
            _ => Err(D::Error::custom(
                "request body must be a role name or a structured template",
            )),
        }
    }
}

/// One query parameter's authored value.
///
/// A scalar template is the single-valued form: one `name=value` pair, or none
/// when its optional reference (`${x?}`) is unbound. A YAML sequence of
/// templates is the repeated (RFC 6570 exploded, `{?p*}`) form: each member
/// contributes its own pair in authored order, an unbound member is absent, and
/// a member resolving to a list capture expands element-wise.
///
/// Repeatability is declared here, in the wire layer, and never inferred from
/// what a case binds: a case core speaks SM operations and outcome kinds, so it
/// must not be able to change a request's serialization form by passing a list.
/// The one released use is the admin bulk delete's subset selector
/// (`/admin/ehr/all{?ehr_id*}`).
#[derive(Debug, Clone, PartialEq)]
pub enum QueryValue {
    /// One pair (the single-valued form).
    Single(Template),
    /// One pair per member (the repeated form).
    Repeated(Vec<Template>),
}

impl QueryValue {
    /// The authored templates, in order (one for [`Self::Single`]).
    #[must_use]
    pub fn templates(&self) -> &[Template] {
        match self {
            Self::Single(template) => std::slice::from_ref(template),
            Self::Repeated(templates) => templates,
        }
    }

    /// Whether the parameter is authored in the repeated form.
    #[must_use]
    pub fn is_repeated(&self) -> bool {
        matches!(self, Self::Repeated(_))
    }
}

impl<'de> Deserialize<'de> for QueryValue {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let value = serde_json::Value::deserialize(deserializer)?;
        match value {
            serde_json::Value::String(s) => Template::parse(&s)
                .map(Self::Single)
                .map_err(D::Error::custom),
            serde_json::Value::Array(items) => {
                if items.is_empty() {
                    return Err(D::Error::custom(
                        "a repeated query parameter declares at least one member",
                    ));
                }
                items
                    .iter()
                    .map(|item| match item {
                        serde_json::Value::String(s) => {
                            Template::parse(s).map_err(D::Error::custom)
                        }
                        _ => Err(D::Error::custom(
                            "a repeated query parameter's members are value templates",
                        )),
                    })
                    .collect::<Result<Vec<_>, _>>()
                    .map(Self::Repeated)
            }
            _ => Err(D::Error::custom(
                "a query parameter is a value template or a sequence of them",
            )),
        }
    }
}

/// A request path with `{param}` placeholders resolved from case variables.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PathTemplate {
    raw: String,
    params: Vec<CaptureName>,
}

impl PathTemplate {
    /// The authored path.
    #[must_use]
    pub fn raw(&self) -> &str {
        &self.raw
    }

    /// The `{param}` names, in order.
    #[must_use]
    pub fn params(&self) -> &[CaptureName] {
        &self.params
    }
}

impl<'de> Deserialize<'de> for PathTemplate {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = String::deserialize(deserializer)?;
        if !raw.starts_with('/') {
            return Err(D::Error::custom(format!("path {raw:?} must start with /")));
        }
        let mut params = Vec::new();
        let mut rest = raw.as_str();
        while let Some(start) = rest.find('{') {
            let tail = rest.get(start + 1..).unwrap_or_default();
            let end = tail
                .find('}')
                .ok_or_else(|| D::Error::custom(format!("path {raw:?}: unterminated {{param}}")))?;
            let name = tail.get(..end).unwrap_or_default();
            params.push(CaptureName::parse(name).map_err(D::Error::custom)?);
            rest = tail.get(end + 1..).unwrap_or_default();
        }
        Ok(Self { raw, params })
    }
}

/// Request construction.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RequestSpec {
    /// The HTTP method the operation is driven with.
    pub method: HttpMethod,
    /// The request path, with `${…}` placeholders resolved per step.
    pub path: PathTemplate,
    /// Query parameters (name → value; optional refs `${x?}` omit the
    /// parameter when unresolved, a sequence declares the repeated form —
    /// see [`QueryValue`]).
    #[serde(default, deserialize_with = "crate::model::de::optional_ordered_map")]
    pub query: Option<Vec<(String, QueryValue)>>,
    /// The request payload, when the operation carries one.
    #[serde(default)]
    pub body: Option<RequestBody>,
    /// Request headers, in declaration order.
    #[serde(default, deserialize_with = "crate::model::de::optional_ordered_map")]
    pub headers: Option<Vec<(String, Template)>>,
}

/// A per-format extra-header requirement (`openehr-template-id: required`).
#[derive(Debug, Clone, PartialEq)]
pub enum FormatHeaderReq {
    /// The header must be sent; its value comes from the case.
    Required,
    /// The header is sent with this fixed (templated) value.
    Literal(Template),
}

impl<'de> Deserialize<'de> for FormatHeaderReq {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        if s == "required" {
            Ok(Self::Required)
        } else {
            Template::parse(&s)
                .map(Self::Literal)
                .map_err(D::Error::custom)
        }
    }
}

/// An explicit unrealized-operation declaration.
///
/// The ITS surfaces no wire for this SM operation, so cases anchored to it are
/// `not-applicable` with this citation on this ITS (machine-readable, never
/// silent absence).
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct UnrealizedDecl {
    /// Why the ITS cannot carry the operation.
    pub reason: String,
    /// The spec citation for the gap.
    pub source: String,
    /// The ambiguity-register entry tracking the gap.
    pub ambiguity: crate::ids::AmbiguityId,
}

/// An EXTENSION realization: the operation is driven over a route no
/// openEHR specification governs — our own design/extension, declared as a
/// family of `vocab/wire_surface.yaml` `served_extensions`.
///
/// A binding carrying this block is a full wire realization (request +
/// outcomes, executed like any other) fenced off from every released-wire
/// judgement: the released-path claim check skips it, and the capabilities its
/// cases carry must be `realization: extension`, which may never be
/// `required`. Only the capability verdict rests on it.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExtensionDecl {
    /// The `served_extensions` family that declares the route (resolved).
    pub family: String,
    /// Why the released ITS surfaces no wire for the operation, and what
    /// this product serves instead.
    pub reason: String,
    /// The spec citation for the gap + the explicit spec-silence flag.
    pub source: String,
    /// The ambiguity-register entry adjudicating the boundary.
    pub ambiguity: crate::ids::AmbiguityId,
}

/// One binding file: a full wire realization (released or, with an
/// `extension` block, over a declared extension route), or an explicit
/// `unrealized` declaration.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OperationBinding {
    /// The SM operation this file realizes on the wire.
    pub sm_operation: SmOperationRef,
    /// The implementation technology specification the realization targets.
    pub its: ItsName,
    /// Realization discriminator when several bindings share one
    /// `sm_operation` (e.g. the plain `get_opt` OPT GET vs the `example`
    /// data-generation realization): a flow step's `variant` selects the
    /// matching binding; a variant-less step selects the variant-less
    /// binding. Absent for the sole realization of an operation.
    #[serde(default)]
    pub variant: Option<String>,
    /// The operation's spec-version floor: the releases on which this wire
    /// realization exists at all. Enforced at selection time (`crate::run`): a
    /// case driving a binding whose floor the party's declared versions do not
    /// satisfy is not-applicable with that citation.
    ///
    /// Distinct from [`HeaderExpectation::applies`], which dates one response
    /// expectation rather than the operation.
    #[serde(default)]
    pub applies: Option<Applies>,
    /// Present instead of `request` when the released ITS publishes no wire
    /// for the operation at all.
    #[serde(default)]
    pub unrealized: Option<UnrealizedDecl>,
    /// Present when the realization drives a declared extension route
    /// instead of a released ITS-REST operation ([`ExtensionDecl`]).
    #[serde(default)]
    pub extension: Option<ExtensionDecl>,
    /// How the request is constructed (absent only for an `unrealized` file).
    #[serde(default)]
    pub request: Option<RequestSpec>,
    /// The wire formats this operation is served in.
    #[serde(default)]
    pub formats: Vec<FormatName>,
    /// Extra headers a given format requires, keyed by format.
    #[serde(default, deserialize_with = "crate::model::de::optional_ordered_map")]
    pub format_headers: Option<Vec<(FormatKey, FormatHeaderMap)>>,
    /// The wire expectation per outcome kind, in declaration order.
    #[serde(default, deserialize_with = "crate::model::de::optional_ordered_map")]
    pub outcomes: Option<Vec<(OutcomeKey, WireExpectation)>>,
    /// Where each logical capture is read from on the wire.
    #[serde(default, deserialize_with = "crate::model::de::optional_ordered_map")]
    pub captures: Option<Vec<(CaptureName, WireCapture)>>,
    /// The operation's server-assigned ignore-set membership (the paths the
    /// `equivalent` assertion excludes as `server_assigned`).
    #[serde(default)]
    pub server_assigned: Vec<String>,
}

impl OperationBinding {
    /// Whether this binding declares the operation unrealized on its ITS.
    #[must_use]
    pub fn is_unrealized(&self) -> bool {
        self.unrealized.is_some()
    }

    /// Whether this binding realizes the operation over a declared EXTENSION
    /// route rather than a released ITS-REST operation.
    #[must_use]
    pub fn is_extension(&self) -> bool {
        self.extension.is_some()
    }

    /// Checks the realization-shape invariant: exactly one of `unrealized` or
    /// the full wire form (`request` + `outcomes`), with an `extension`
    /// declaration only on the realized form.
    ///
    /// # Errors
    /// Returns a message naming the violated invariant.
    pub fn check_invariants(&self) -> Result<(), String> {
        if self.unrealized.is_some() && self.extension.is_some() {
            return Err(
                "a binding is either unrealized or an extension realization, never both".to_owned(),
            );
        }
        match (&self.unrealized, &self.request, &self.outcomes) {
            (Some(_), None, None) | (None, Some(_), Some(_)) => Ok(()),
            (Some(_), _, _) => Err("unrealized binding must carry no request/outcomes".to_owned()),
            _ => Err("realized binding must carry request and outcomes".to_owned()),
        }
    }

    /// The wire expectation mapped for an outcome kind, if any.
    #[must_use]
    pub fn outcome(&self, kind: OutcomeKind) -> Option<&WireExpectation> {
        self.outcomes
            .as_deref()
            .unwrap_or_default()
            .iter()
            .find(|(k, _)| k.0 == kind)
            .map(|(_, e)| e)
    }

    /// Whether a logical capture has a wire source.
    #[must_use]
    pub fn maps_capture(&self, name: &CaptureName) -> bool {
        self.captures
            .as_deref()
            .unwrap_or_default()
            .iter()
            .any(|(n, _)| n == name)
    }
}

/// Newtype keys so the crate's `model::de::ordered_map` can parse them from
/// mapping keys.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OutcomeKey(pub OutcomeKind);

impl std::str::FromStr for OutcomeKey {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        OutcomeKind::from_token(s)
            .map(Self)
            .ok_or_else(|| format!("{s:?} is not an outcome kind"))
    }
}

impl std::fmt::Display for OutcomeKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.0.token())
    }
}

/// Format key of `format_headers`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FormatKey(pub FormatName);

impl std::str::FromStr for FormatKey {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        serde_json::from_value(serde_json::Value::String(s.to_owned()))
            .map(Self)
            .map_err(|error| format!("{s:?} is not a format name: {error}"))
    }
}

impl std::fmt::Display for FormatKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match serde_json::to_value(self.0) {
            Ok(serde_json::Value::String(s)) => f.write_str(&s),
            _ => f.write_str("?"),
        }
    }
}

/// The per-format header map.
#[derive(Debug, Clone)]
pub struct FormatHeaderMap(pub Vec<(String, FormatHeaderReq)>);

impl<'de> Deserialize<'de> for FormatHeaderMap {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        crate::model::de::ordered_map(deserializer).map(Self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::case::VersionRange;

    #[test]
    fn wire_from_grammar_is_closed() {
        assert_eq!(
            WireFrom::parse("header Location last-segment").unwrap(),
            WireFrom::Header {
                name: "Location".into(),
                last_segment: true
            }
        );
        assert_eq!(
            WireFrom::parse("body \"ehr_id.value\"").unwrap(),
            WireFrom::Body {
                path: "ehr_id.value".into()
            }
        );
        assert!(matches!(
            WireFrom::parse("capture version_uid").unwrap(),
            WireFrom::Capture(_)
        ));
        assert!(WireFrom::parse("body ehr_id.value").is_err());
        assert!(WireFrom::parse("body-or-location").is_err()); // express via fallback
        assert!(WireFrom::parse("jsonpath $.x").is_err());
    }

    #[test]
    fn header_matchers_parse() {
        let m: HeaderMatcher = serde_json::from_value(serde_json::json!(
            "pattern:W/\"<versioned_object_uid>::<system_id>::1\""
        ))
        .unwrap();
        assert!(matches!(m, HeaderMatcher::Pattern(_)));
        let m: HeaderMatcher =
            serde_json::from_value(serde_json::json!("\"${preceding_version_uid}\"")).unwrap();
        assert!(matches!(m, HeaderMatcher::Literal(_)));
        assert!(
            serde_json::from_value::<HeaderMatcher>(serde_json::json!("pattern:([unclosed"))
                .is_err()
        );
        // `present?` is the expectation-level shorthand, never a matcher.
        assert!(serde_json::from_value::<HeaderMatcher>(serde_json::json!("present?")).is_err());
    }

    #[test]
    fn header_expectations_carry_the_two_modifiers() {
        let short: HeaderExpectation =
            serde_json::from_value(serde_json::json!("present")).unwrap();
        assert_eq!(short.matcher, HeaderMatcher::Present);
        assert!(!short.optional);
        assert!(short.applies.is_none());

        let sugar: HeaderExpectation =
            serde_json::from_value(serde_json::json!("present?")).unwrap();
        assert_eq!(sugar.matcher, HeaderMatcher::Present);
        assert!(sugar.optional);

        let long: HeaderExpectation = serde_json::from_value(serde_json::json!({
            "match": "pattern:W/\"[^\"]+\"",
            "optional": true,
            "applies": { "its_rest": ">=1.1.0" }
        }))
        .unwrap();
        assert!(matches!(long.matcher, HeaderMatcher::Pattern(_)));
        assert!(long.optional);
        let applies = long.applies.unwrap();
        assert_eq!(applies.entries().len(), 1);
        assert_eq!(
            applies.its_rest.as_ref().map(VersionRange::raw),
            Some(">=1.1.0")
        );

        assert!(
            serde_json::from_value::<HeaderExpectation>(serde_json::json!({ "optional": true }))
                .is_err()
        );
        assert!(
            serde_json::from_value::<HeaderExpectation>(
                serde_json::json!({ "match": "present", "since": "1.1.0" })
            )
            .is_err()
        );
        assert!(serde_json::from_value::<HeaderExpectation>(serde_json::json!(7)).is_err());
    }

    /// `present-with-body` is a member of the closed vocabulary, so a typo of
    /// it is a literal-value expectation and never a silent presence pass.
    #[test]
    fn present_with_body_is_a_vocabulary_member() {
        let m: HeaderMatcher =
            serde_json::from_value(serde_json::json!("present-with-body")).unwrap();
        assert_eq!(m, HeaderMatcher::PresentWithBody);
        let typo: HeaderMatcher =
            serde_json::from_value(serde_json::json!("present-with-bodies")).unwrap();
        assert!(matches!(typo, HeaderMatcher::Literal(_)), "{typo:?}");
    }

    /// One header may declare a SEQUENCE of expectations, each with its own
    /// modifiers; an empty sequence is refused because it asserts nothing.
    #[test]
    fn a_header_declares_one_expectation_or_a_sequence() {
        let single: HeaderExpectations =
            serde_json::from_value(serde_json::json!("present")).unwrap();
        assert_eq!(single.all().len(), 1);

        let many: HeaderExpectations = serde_json::from_value(serde_json::json!([
            "latest-version-uid",
            { "match": "pattern:W/\"[^\"]+\"", "applies": { "its_rest": ">=1.1.0" } }
        ]))
        .unwrap();
        assert_eq!(many.all().len(), 2);
        assert_eq!(many.all()[0].matcher, HeaderMatcher::LatestVersionUid);
        assert!(many.all()[1].applies.is_some());

        assert!(
            serde_json::from_value::<HeaderExpectations>(serde_json::json!([])).is_err(),
            "an empty sequence asserts nothing"
        );
        assert!(
            serde_json::from_value::<HeaderExpectations>(serde_json::json!(["present", 7]))
                .is_err()
        );
    }

    #[test]
    fn binding_parses_the_create_ehr_shape() {
        let b: OperationBinding = serde_json::from_value(serde_json::json!({
            "sm_operation": "I_EHR_SERVICE.create_ehr",
            "its": "its-rest",
            "request": {
                "method": "POST",
                "path": "/ehr",
                "body": "ehr_status?",
                "headers": { "Prefer": "return=representation" }
            },
            "formats": ["canonical-json", "canonical-xml"],
            "outcomes": {
                "created": { "status": 201,
                             "headers": { "ETag": "present", "Location": "present" },
                             "body": "prefer_conditional" },
                "already_exists": { "status": 409 },
                "validation_failed": { "status": 400 }
            },
            "captures": {
                "ehr_id": { "from": "body \"ehr_id.value\"",
                            "fallback": "header Location last-segment" },
                "version_uid": { "from": "header ETag", "strip": "weak-quotes" }
            },
            "server_assigned": ["ehr_id", "system_id", "time_created"]
        }))
        .unwrap();
        assert_eq!(b.sm_operation.to_string(), "I_EHR_SERVICE.create_ehr");
        assert!(b.outcome(OutcomeKind::Created).is_some());
        assert!(b.outcome(OutcomeKind::NotFound).is_none());
        assert!(b.maps_capture(&CaptureName::parse("ehr_id").unwrap()));
        assert!(b.check_invariants().is_ok());
        let request = b.request.clone().unwrap();
        assert!(matches!(
            request.body,
            Some(RequestBody::Named { optional: true, .. })
        ));
        assert_eq!(request.path.params().len(), 0);
    }

    /// An `extension` realization is a full wire form fenced off from the
    /// released-wire judgements, and it is never also `unrealized`.
    #[test]
    fn extension_realization_is_a_realized_binding_and_never_unrealized() {
        let shape = |extra: serde_json::Value| {
            let mut v = serde_json::json!({
                "sm_operation": "I_PARTY_RELATIONSHIP.get_party_relationship",
                "its": "its-rest",
                "extension": {
                    "family": "party-relationship",
                    "reason": "the release surfaces no PARTY_RELATIONSHIP resource",
                    "source": "SM i_party_relationship.adoc vs ITS-REST demographic.openapi.yaml",
                    "ambiguity": "AMB-32"
                },
                "request": { "method": "GET", "path": "/demographic/party_relationship/{versioned_object_uid}" },
                "outcomes": { "ok": { "status": 200 }, "not_found": { "status": 404 } }
            });
            if let (Some(object), Some(extra)) = (v.as_object_mut(), extra.as_object()) {
                for (k, value) in extra {
                    object.insert(k.clone(), value.clone());
                }
            }
            v
        };

        let b: OperationBinding = serde_json::from_value(shape(serde_json::json!({}))).unwrap();
        assert!(b.is_extension());
        assert!(!b.is_unrealized());
        assert!(b.check_invariants().is_ok());

        let mut both: OperationBinding = serde_json::from_value(shape(serde_json::json!({
            "unrealized": {
                "reason": "r", "source": "s", "ambiguity": "AMB-32"
            }
        })))
        .unwrap();
        assert!(both.check_invariants().is_err());
        both.request = None;
        both.outcomes = None;
        assert!(both.check_invariants().is_err());
    }

    #[test]
    fn path_params_extract() {
        let r: RequestSpec = serde_json::from_value(serde_json::json!({
            "method": "PUT",
            "path": "/ehr/{ehr_id}/composition/{versioned_object_uid}"
        }))
        .unwrap();
        assert_eq!(r.path.params().len(), 2);
        assert!(
            serde_json::from_value::<RequestSpec>(serde_json::json!({
                "method": "GET", "path": "/ehr/{unclosed"
            }))
            .is_err()
        );
    }

    /// The closed transform grammar decomposes an `OBJECT_VERSION_ID` by its
    /// released lexical form `object_id :: creating_system_id ::
    /// version_tree_id` (ITS-REST Resources.md §Identifier types).
    #[test]
    fn transforms_address_object_version_id_components() {
        let uid = "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1";
        assert_eq!(
            TransformRule::RootUid.apply(uid).as_deref(),
            Some("8849182c-82ad-4088-a07f-48ead4180515")
        );
        assert_eq!(
            TransformRule::CreatingSystemId.apply(uid).as_deref(),
            Some("openEHRSys.example.com")
        );
        assert_eq!(
            TransformRule::Uppercase.apply("a::b::1").as_deref(),
            Some("A::B::1")
        );

        // A bare versioned_object_uid must never bind as a creating system id.
        assert_eq!(
            TransformRule::CreatingSystemId.apply("8849182c-82ad-4088-a07f-48ead4180515"),
            None
        );
        assert_eq!(TransformRule::CreatingSystemId.apply("uid::"), None);
        assert_eq!(TransformRule::RootUid.apply("uid").as_deref(), Some("uid"));

        let spec: WireCapture = serde_json::from_value(serde_json::json!({
            "from": "header ETag", "strip": "weak-quotes",
            "transform": "creating-system-id"
        }))
        .unwrap();
        assert_eq!(spec.transform, Some(TransformRule::CreatingSystemId));
        assert!(
            serde_json::from_value::<WireCapture>(serde_json::json!({
                "from": "header ETag", "transform": "middle-segment"
            }))
            .is_err()
        );
    }

    #[test]
    fn query_values_are_single_or_repeated() {
        let r: RequestSpec = serde_json::from_value(serde_json::json!({
            "method": "DELETE",
            "path": "/admin/ehr/all",
            "query": { "ehr_id": ["${ehr_id_subset?}", "${ehr_id_subset_2?}"],
                       "fetch": "${url_fetch?}" }
        }))
        .unwrap();
        let query = r.query.unwrap();
        let repeated = &query.iter().find(|(name, _)| name == "ehr_id").unwrap().1;
        assert!(repeated.is_repeated());
        assert_eq!(repeated.templates().len(), 2);
        let single = &query.iter().find(|(name, _)| name == "fetch").unwrap().1;
        assert!(!single.is_repeated());
        assert_eq!(single.templates().len(), 1);

        for bad in [
            serde_json::json!({ "method": "GET", "path": "/x", "query": { "p": [] } }),
            serde_json::json!({ "method": "GET", "path": "/x", "query": { "p": [1] } }),
            serde_json::json!({ "method": "GET", "path": "/x", "query": { "p": 1 } }),
            serde_json::json!({ "method": "GET", "path": "/x", "query": { "p": ["${step2.body}"] } }),
        ] {
            assert!(
                serde_json::from_value::<RequestSpec>(bad.clone()).is_err(),
                "{bad} must be rejected"
            );
        }
    }

    #[test]
    fn duplicate_outcome_keys_rejected() {
        // serde_json::Map deduplicates silently, so feed the YAML front-end.
        let yaml = "sm_operation: I_EHR_SERVICE.create_ehr\nits: its-rest\nrequest: { method: POST, path: /ehr }\noutcomes:\n  created: { status: 201 }\n  created: { status: 200 }\n";
        let result: Result<OperationBinding, _> = serde_saphyr::from_str(yaml);
        assert!(result.is_err());
    }
}