///| Minimal NRRD header parser for the G1 probe.
///| Field names are matched case-insensitively with spaces removed
///| (`data file` == `datafile`), per the NRRD format specification
///| (https://teem.sourceforge.net/nrrd/format.html).
///| Magic policy (spec §1.1): the first line must be exactly `NRRD0005`
///| (v1 supports that version only; other versions/suffixes/garbage are
///| rejected). Field-specification uniqueness (spec §1.2): every
///| `field: desc` line may appear at most once (alias/case folded);
///| `key:=value` custom pairs may repeat.

///|
pub(all) struct NrrdHeader {
  dimension : Int
  sizes : Array[Int]
  type_name : String
  encoding : String
  endian : String?
  data_file : String?
  space : String?
  space_dimension : Int?
  space_origin : Array[Double]?
  space_directions : Array[Array[Double]?]
  space_units : Array[String]?
  labels : Array[String]?
  kinds : Array[String]?
  content : String?
  line_skip : Int
  byte_skip : Int
}

///| Header text length budget (G2 v2 §7.2). Enforced both at the
///| split_header_body entry AND in parse_header itself so direct
///| callers cannot bypass it. 1 MiB is far above real headers
///| (typically < 64 KiB) and bounds malformed input.
fn max_header_bytes() -> Int {
  1048576
}

///| Dimension cap (G2 v2 §7.2).
fn max_dimension() -> Int {
  16
}

///|
fn char_at(s : String, i : Int) -> Char {
  match s.get_char(i) {
    Some(c) => c
    None => panic()
  }
}

///| Bytes -> String treating every byte as an ASCII code point.
///| (`Bytes::to_string` decodes UTF-16 on this toolchain and garbles
///| real file bytes; NRRD headers are ASCII by specification.)
pub fn bytes_to_ascii(b : Bytes) -> String {
  String::from_array(Array::makei(b.length(), i => b[i].to_int().unsafe_to_char()))
}

///| String -> Bytes treating every code unit as an ASCII code point.
///| v1 encoding contract: writable strings are ASCII only (NRRD
///| headers are ASCII by specification). Any code point outside
///| U+0000..U+007F is REJECTED with NrrdError — never silently
///| truncated to its low byte (U+010A would become 0x0A and inject
///| a newline into the header) and never panic on supplementary-plane
///| UTF-16 traversal (missing code units raise instead).
pub fn ascii_to_bytes(s : String) -> Bytes raise NrrdError {
  let n = s.length()
  let out : Array[Byte] = []
  let mut i = 0
  while i < n {
    match s.get_char(i) {
      Some(c) => {
        let v = c.to_int()
        if v > 127 {
          raise NrrdError(
            "ascii_to_bytes: non-ASCII code point \{v.to_string()} is not representable",
          )
        }
        out.push(v.to_byte())
      }
      None => raise NrrdError(
        "ascii_to_bytes: invalid UTF-16 code unit at index \{i.to_string()}",
      )
    }
    i = i + 1
  }
  Bytes::from_array(out)
}

///| `s[a:b]` slice as an owned String.
fn slice_str(s : String, a : Int, b : Int) -> String {
  s[a:b].to_owned()
}

///|
fn is_ws(c : Char) -> Bool {
  c == ' ' || c == '\t' || c == '\r' || c == '\n' || c.to_int() == 11 || c.to_int() == 12
}

///| Parse a decimal integer into Int64 with overflow checks.
///| Accumulates as a non-positive Int64 so the asymmetry of the
///| range is handled naturally: -2^63 is representable while +2^63
///| is not. Rejects BEFORE wraparound; handles '+'/'-' and the
///| Int64 minimum correctly; returns None on empty input, stray
///| characters, or out-of-range values. Used for data values that
///| must cover the full uint32 range (2^32-1 does not fit Int).
fn parse_int64_str(s : String) -> Int64? {
  let n = s.length()
  let mut i = 0
  let mut neg = false
  if n == 0 {
    return None
  }
  let c0 = char_at(s, 0)
  if c0 == '-' {
    neg = true
    i = 1
  } else if c0 == '+' {
    i = 1
  }
  let min_int64 = -9223372036854775807L - 1L
  let mut acc = 0L // running magnitude, stored negated (acc <= 0)
  let mut any = false
  while i < n {
    let c = char_at(s, i)
    if c.is_ascii_digit() {
      let d = (c.to_int() - 48).to_int64()
      // need acc * 10 - d >= min_int64 (truncating division rounds
      // toward zero on a negative numerator = ceil, which is safe)
      if acc < (min_int64 + d) / 10L {
        return None
      }
      acc = acc * 10L - d
      any = true
      i = i + 1
    } else {
      return None
    }
  }
  if !any {
    return None
  }
  if neg {
    Some(acc)
  } else {
    // positive magnitude must fit in Int64 max (= |min| - 1)
    if acc < -9223372036854775807L {
      return None
    }
    Some(0L - acc)
  }
}

///| Parse a decimal integer with overflow checks into Int (32-bit).
///| Accumulates in Int64 and rejects BEFORE wraparound
///| (regression: ASCII "4294967297" used to wrap to 1 and be
///| silently accepted — audit-overflow-int16.nrrd). Handles sign
///| and the Int minimum -2147483648 correctly; returns None on
///| empty input, stray characters, or values outside Int range.
fn parse_int_str(s : String) -> Int? {
  match parse_int64_str(s) {
    Some(v) =>
      if v >= -2147483648L && v <= 2147483647L {
        Some(v.to_int())
      } else {
        None
      }
    None => None
  }
}

///| Parse a decimal double using the core conversion (correctly
///| rounded, bounded work). The hand-rolled parser was replaced
///| after review: its exponent accumulated in Int without bounds
///| and scaled by a linear loop. Returns None on malformed input.
fn parse_double_str(s : String) -> Double? {
  try {
    Some(@string.parse_double(s))
  } catch {
    _ => None
  }
}

///|
fn split_ws_tokens(s : String) -> Array[String] {
  let out : Array[String] = []
  let n = s.length()
  let mut i = 0
  while i < n {
    while i < n && is_ws(char_at(s, i)) {
      i = i + 1
    }
    let start = i
    while i < n && !is_ws(char_at(s, i)) {
      i = i + 1
    }
    if i > start {
      out.push(slice_str(s, start, i))
    }
  }
  out
}

///| Tokens of quoted strings (`"a" "b"`) or bare words (kinds).
///| Inside double quotes the ONLY escape is `\"` (spec §1.6: "double
///| quotes may be included by escaping them (`\"`), but no other form
///| of escaping is supported") — a backslash before anything else is
///| a literal backslash. NOTE: pynrrd lexes quoted lists with POSIX
///| shlex rules, where `\\` collapses to one backslash; files whose
///| labels contain backslashes may therefore differ between readers.
///| The write path rejects backslashes in quoted strings (see
///| encode.mbt) so its output is unambiguous for every reader.
fn parse_quoted_tokens(s : String) -> Array[String] {
  let out : Array[String] = []
  let n = s.length()
  let mut i = 0
  while i < n {
    while i < n && is_ws(char_at(s, i)) {
      i = i + 1
    }
    if i >= n {
      break
    }
    if char_at(s, i) == '"' {
      i = i + 1
      let buf = StringBuilder()
      let mut closed = false
      while i < n && !closed {
        let c = char_at(s, i)
        if c == '\\' && i + 1 < n && char_at(s, i + 1) == '"' {
          buf.write_char('"')
          i = i + 2
        } else if c == '"' {
          closed = true
          i = i + 1
        } else {
          buf.write_char(c)
          i = i + 1
        }
      }
      out.push(buf.to_string())
    } else {
      let start = i
      while i < n && !is_ws(char_at(s, i)) {
        i = i + 1
      }
      out.push(slice_str(s, start, i))
    }
  }
  out
}

///| Parse `(1.5,0,0)` style vector.
fn parse_paren_vec(s : String, field : String) -> Array[Double] raise NrrdError {
  let n = s.length()
  let mut l = -1
  let mut r = -1
  let mut i = 0
  while i < n {
    if char_at(s, i) == '(' && l < 0 {
      l = i
    }
    if char_at(s, i) == ')' {
      r = i
    }
    i = i + 1
  }
  if l < 0 || r <= l {
    raise NrrdError("\{field}: cannot parse vector '\{s}'")
  }
  let inner = slice_str(s, l + 1, r)
  let parts = split_ws_tokens(inner.replace_all(old=",", new=" "))
  let out : Array[Double] = []
  for p in parts {
    match parse_double_str(p) {
      Some(v) => out.push(v)
      None => raise NrrdError("\{field}: cannot parse number '\{p}'")
    }
  }
  out
}

///| Parse `space directions` value: `none (1,0,0) (0,2,0)` etc.
fn parse_directions(s : String) -> Array[Array[Double]?] raise NrrdError {
  let compact = s.replace_all(old=" ", new="").replace_all(old="\t", new="")
  let out : Array[Array[Double]?] = []
  let n = compact.length()
  let mut i = 0
  while i < n {
    let c = char_at(compact, i)
    if c == 'n' {
      out.push(None) // "none"
      i = i + 4
    } else if c == '(' {
      let mut r = i
      while r < n && char_at(compact, r) != ')' {
        r = r + 1
      }
      if r >= n {
        raise NrrdError("space directions: unbalanced paren")
      }
      out.push(Some(parse_paren_vec(slice_str(compact, i, r + 1), "space directions")))
      i = r + 1
    } else {
      raise NrrdError("space directions: unexpected char '\{c}'")
    }
  }
  out
}

///| Field name normalization: lowercase with spaces removed.
fn normalize_field_name(s : String) -> String {
  let sb = StringBuilder()
  let n = s.length()
  let mut i = 0
  while i < n {
    let c = char_at(s, i)
    if c != ' ' && c != '\t' {
      sb.write_char(if c.to_int() >= 65 && c.to_int() <= 90 {
        (c.to_int() + 32).unsafe_to_char()
      } else {
        c
      })
    }
    i = i + 1
  }
  sb.to_string()
}

///| Alias collapse for field identifiers whose equivalent spelled forms
///| differ beyond whitespace/case (spec §1.2: "centers" is the same field
///| as "centerings"). All other documented aliases unify through
///| normalize_field_name's space-stripping ("data file" == "datafile",
///| "line skip" == "lineskip", ...).
fn canonical_field_id(s : String) -> String {
  match s {
    "centers" => "centerings"
    _ => s
  }
}

///| Normalize a type descriptor to its canonical short name.
pub fn normalize_type(t : String) -> String raise NrrdError {
  let x = normalize_field_name(t)
  match x {
    "signedchar" | "int8" | "int8_t" => "int8"
    "uchar" | "unsignedchar" | "uint8" | "uint8_t" => "uint8"
    "short" | "shortint" | "signedshort" | "int16" | "int16_t" => "int16"
    "ushort" | "unsignedshort" | "uint16" | "uint16_t" => "uint16"
    "int" | "signedint" | "int32" | "int32_t" => "int32"
    "uint" | "unsignedint" | "uint32" | "uint32_t" => "uint32"
    "longlong" | "int64" | "int64_t" => "int64"
    "ulonglong" | "uint64" | "uint64_t" => "uint64"
    "float" => "float"
    "double" => "double"
    "block" => "block"
    _ => raise NrrdError("unknown type '\{t}'")
  }
}

///| Normalize an encoding descriptor to its canonical short name.
pub fn normalize_encoding(e : String) -> String raise NrrdError {
  let x = normalize_field_name(e)
  match x {
    "raw" => "raw"
    "txt" | "text" | "ascii" => "ascii"
    "hex" => "hex"
    "gz" | "gzip" => "gzip"
    "bz2" | "bzip2" => "bzip2"
    _ => raise NrrdError("unknown encoding '\{e}'")
  }
}

///| Split file bytes into header text and body (attached data) at the
///| single blank line. Handles `\n`, `\r\n` and mixed terminators.
///| Enforces the header-length budget before returning (G2 v2 §7.2).
pub fn split_header_body(data : Bytes) -> (Bytes, Bytes) raise NrrdError {
  let n = data.length()
  let mut line_start = 0
  let mut i = 0
  while i < n {
    if data[i] == b'\n' {
      let mut end = i
      if end > line_start && data[end - 1] == b'\r' {
        end = end - 1
      }
      if end == line_start {
        // blank line: header ends at line_start, body after the newline
        if line_start > max_header_bytes() {
          raise NrrdError("header too large: \{line_start} bytes")
        }
        let header = Bytes::from_array(Array::makei(line_start, k => data[k]))
        let body = Bytes::from_array(Array::makei(n - (i + 1), k => data[i + 1 + k]))
        return (header, body)
      }
      line_start = i + 1
    }
    i = i + 1
  }
  raise NrrdError("no blank line separating header and data")
}

///| Implied dimension of a named space (spec §4 table).
///| Unknown names are rejected: v1 does not pass through names
///| whose space dimension cannot be interpreted (G2 v2 decision A).
fn named_space_dimension(name : String) -> Int raise NrrdError {
  match name.to_lower() {
    "right-anterior-superior" | "ras" | "left-anterior-superior" | "las" |
    "left-posterior-superior" | "lps" | "scanner-xyz" | "3d-right-handed" |
    "3d-left-handed" => 3
    "right-anterior-superior-time" | "rast" | "left-anterior-superior-time" |
    "last" | "left-posterior-superior-time" | "lpst" | "scanner-xyz-time" |
    "3d-right-handed-time" | "3d-left-handed-time" => 4
    _ => raise NrrdError("unknown named space '\{name}'")
  }
}

///| Structural + spatial legality validation for a (possibly
///| constructed) header. Called by parse_header and, independently,
///| by decode_data — callers cannot assume parse was ever involved.
///
///| Spatial conditions (unambiguous, G2 v2 §4.3 decision A):
///| - illegal: `space` and `space dimension` both present -> reject
///| - illegal: orientation fields (origin/directions/space units)
///|   present but neither `space` nor `space dimension` -> reject
///| - illegal: unknown named space -> reject
///| - consistency OF PRESENT optional fields only:
///|   labels/kinds count == dimension; directions rows == dimension;
///|   space units count == space dimension; origin length == space
///|   dimension; non-none direction vectors length == space dimension.
///| - NOT errors: missing space units / origin / directions / labels /
///|   kinds; absent spatial fields entirely (data ops have their own
///|   policy for incomplete spatial info — decision C).
pub fn validate_header(h : NrrdHeader) -> Unit raise NrrdError {
  if h.dimension < 1 {
    raise NrrdError("missing or invalid dimension")
  }
  if h.dimension > max_dimension() {
    raise NrrdError("dimension \{h.dimension} exceeds limit \{max_dimension()}")
  }
  if h.sizes.length() != h.dimension {
    raise NrrdError(
      "sizes count \{h.sizes.length()} does not match dimension \{h.dimension}",
    )
  }
  for s in h.sizes {
    if s <= 0 {
      raise NrrdError("sizes must be positive")
    }
  }
  // per-axis field counts (only validated when present)
  match h.labels {
    Some(ls) =>
      if ls.length() != h.dimension {
        raise NrrdError("labels count \{ls.length()} does not match dimension")
      }
    None => ()
  }
  match h.kinds {
    Some(ks) =>
      if ks.length() != h.dimension {
        raise NrrdError("kinds count \{ks.length()} does not match dimension")
      }
    None => ()
  }
  if !h.space_directions.is_empty() && h.space_directions.length() != h.dimension {
    raise NrrdError(
      "space directions count \{h.space_directions.length()} does not match dimension",
    )
  }
  // spatial identity (decision A)
  match (h.space, h.space_dimension) {
    (Some(_), Some(_)) => raise NrrdError(
      "space and space dimension are mutually exclusive",
    )
    (None, None) => {
      let has_orient = h.space_origin is Some(_) ||
        !h.space_directions.is_empty() ||
        h.space_units is Some(_)
      if has_orient {
        raise NrrdError(
          "orientation fields require space or space dimension",
        )
      }
    }
    _ => ()
  }
  // effective space dimension (identity present in exactly one form)
  let sd_opt : Int? = match h.space_dimension {
    Some(sd) => {
      if sd < 1 {
        raise NrrdError("space dimension must be positive")
      }
      Some(sd)
    }
    None => match h.space {
      Some(name) => Some(named_space_dimension(name))
      None => None
    }
  }
  match sd_opt {
    Some(sd) => {
      match h.space_units {
        Some(us) =>
          if us.length() != sd {
            raise NrrdError(
              "space units count \{us.length()} does not match space dimension \{sd}",
            )
          }
        None => ()
      }
      match h.space_origin {
        Some(o) =>
          if o.length() != sd {
            raise NrrdError(
              "space origin length \{o.length()} does not match space dimension \{sd}",
            )
          }
        None => ()
      }
      for row in h.space_directions {
        match row {
          Some(v) =>
            if v.length() != sd {
              raise NrrdError(
                "space direction vector length \{v.length()} does not match space dimension \{sd}",
              )
            }
          None => ()
        }
      }
    }
    None => ()
  }
}

///| Parse an NRRD header text (without the data payload).
///| Enforces the header-length budget directly (G2 v2 §7.2: not
///| only at the split_header_body entry).
pub fn parse_header(text : String) -> NrrdHeader raise NrrdError {
  if text.length() > max_header_bytes() {
    raise NrrdError("header too large: \{text.length()} bytes")
  }
  let mut dimension = 0
  let mut sizes : Array[Int] = []
  let mut type_name = ""
  let mut encoding = ""
  let mut endian : String? = None
  let mut data_file : String? = None
  let mut space : String? = None
  let mut space_dimension : Int? = None
  let mut space_origin : Array[Double]? = None
  let mut space_directions : Array[Array[Double]?] = []
  let mut space_units : Array[String]? = None
  let mut labels : Array[String]? = None
  let mut kinds : Array[String]? = None
  let mut content : String? = None
  let mut line_skip = 0
  let mut byte_skip = 0
  let n = text.length()
  let mut i = 0
  let mut first = true
  let seen_fields : Array[String] = []
  while i <= n {
    let mut j = i
    while j < n && char_at(text, j) != '\n' {
      j = j + 1
    }
    let mut line = slice_str(text, i, j)
    if line.length() > 0 && char_at(line, line.length() - 1) == '\r' {
      line = slice_str(line, 0, line.length() - 1)
    }
    i = j + 1
    if first {
      first = false
      // Magic (spec §1.1: "The very first line contains nothing but the
      // NRRD magic"). Strict whole-line comparison: v1 supports NRRD0005
      // only. Unknown versions (NRRD0001-0004, NRRD00.01), suffixes
      // ("NRRD0005x", "NRRD0005 extra") and garbage ("NRRDgarbage") are
      // explicitly rejected.
      if line != "NRRD0005" {
        if line.has_prefix("NRRD") {
          raise NrrdError(
            "unsupported NRRD magic '\{line}': this reader supports NRRD0005 only",
          )
        } else {
          raise NrrdError("invalid NRRD magic in first line: '\{line}'")
        }
      }
      continue
    }
    if line.is_empty() {
      break
    }
    if line.has_prefix("#") {
      continue
    }
    let mut colon = -1
    let mut k = 0
    while k < line.length() {
      if char_at(line, k) == ':' {
        colon = k
        k = line.length()
      } else {
        k = k + 1
      }
    }
    if colon < 0 {
      raise NrrdError("header line without ':': '\{line}'")
    }
    if colon + 1 < line.length() && char_at(line, colon + 1) == '=' {
      continue // custom key:=value pair: repeats ARE allowed (spec §1.2,
      // last value wins when stored); the field-specification uniqueness
      // rule below does NOT apply to key:=value lines
    }
    // Field-specification uniqueness (spec §1.2: "Each field specification
    // may appear no more than once in the nrrd header"). Enforced after
    // case-folding, space-stripping and alias normalization; a repeated
    // field is rejected even when its content is identical. Applies to
    // every `field: desc` line (standard fields and unknown fields alike);
    // `key:=value` custom pairs are exempt (handled above).
    let fname = canonical_field_id(normalize_field_name(slice_str(line, 0, colon)))
    for s in seen_fields {
      if s == fname {
        raise NrrdError(
          "duplicate field '\{fname}': field specifications may appear at most once",
        )
      }
    }
    seen_fields.push(fname)
    let desc = slice_str(line, colon + 1, line.length()).trim().to_owned()
    match fname {
      "dimension" => match parse_int_str(desc) {
        Some(v) => dimension = v
        None => raise NrrdError("dimension: cannot parse '\{desc}'")
      }
      "sizes" => {
        sizes = []
        for t in split_ws_tokens(desc) {
          match parse_int_str(t) {
            Some(v) => sizes.push(v)
            None => raise NrrdError("sizes: cannot parse '\{t}'")
          }
        }
      }
      "type" => type_name = desc
      "encoding" => encoding = desc
      "endian" => endian = Some(desc.to_lower())
      "datafile" => data_file = Some(desc)
      "space" => space = Some(desc)
      "spacedimension" => match parse_int_str(desc) {
        Some(v) => space_dimension = Some(v)
        None => raise NrrdError("space dimension: cannot parse '\{desc}'")
      }
      "spaceorigin" => space_origin = Some(parse_paren_vec(desc, "space origin"))
      "spacedirections" => space_directions = parse_directions(desc)
      "spaceunits" => space_units = Some(parse_quoted_tokens(desc))
      "labels" => labels = Some(parse_quoted_tokens(desc))
      "kinds" => kinds = Some(parse_quoted_tokens(desc))
      "content" => content = Some(desc)
      "lineskip" => match parse_int_str(desc) {
        Some(v) => line_skip = v
        None => raise NrrdError("line skip: cannot parse '\{desc}'")
      }
      "byteskip" => match parse_int_str(desc) {
        Some(v) => byte_skip = v
        None => raise NrrdError("byte skip: cannot parse '\{desc}'")
      }
      _ => continue // unknown/harmless fields are ignored
    }
  }
  if type_name.is_empty() || encoding.is_empty() {
    raise NrrdError("missing type or encoding")
  }
  let h = {
    dimension,
    sizes,
    type_name: normalize_type(type_name),
    encoding: normalize_encoding(encoding),
    endian,
    data_file,
    space,
    space_dimension,
    space_origin,
    space_directions,
    space_units,
    labels,
    kinds,
    content,
    line_skip,
    byte_skip,
  }
  validate_header(h)
  h
}