R/forestsearch_helpers.R

Defines functions .assert_admission_resolution_complete .fs_format_admission .fs_resolve_admission .fs_admission_applies .assert_sg_focus_dispatch_complete .find_switch_branches .fs_family_status .validate_mr_configuration .forestsearch_grf_select .grf_reselect_on_effect .forestsearch_dina_select .dina_assert_ratio_estimand .dina_tau_sign .coerce_covariates_numeric .dina_reselect_on_effect .resolve_dina_args .fs_c2_inert_note .map_dina_family .announce_sg_focus .sg_focus_aliases_of .normalize_sg_focus reset_workers collect_results filter_valid_args safe_subset safe_eval_expr get_param .label_to_expr evaluate_comparison get_dfpred add_id_column

Documented in add_id_column collect_results evaluate_comparison filter_valid_args get_dfpred get_param reset_workers safe_eval_expr safe_subset

# =============================================================================
# forestsearch_helpers.R - Utility Functions for ForestSearch
# =============================================================================
#
# Helper functions used across the ForestSearch package:
#   - add_id_column()          : Ensure data frame has a unique ID column
#   - get_dfpred()             : Apply subgroup definition to new data
#   - evaluate_comparison()    : Safe operator-dispatch expression evaluator
#   - get_param()              : Extract parameter with default fallback
#   - collect_results()        : Post-hoc error/result separation for foreach
#   - reset_workers()          : Reset parallel worker pool between sim phases
# =============================================================================


#' Add ID Column to Data Frame
#'
#' Ensures that a data frame has a unique ID column. If \code{id.name} is not
#' provided, a column named \code{"id"} is added. If \code{id.name} is provided
#' but does not exist in the data frame, it is created with unique integer
#' values.
#'
#' @param df.analysis Data frame to which the ID column will be added.
#' @param id.name Character. Name of the ID column to add (default is
#'   \code{NULL}, which uses \code{"id"}).
#'
#' @return Data frame with the ID column added if necessary.
#' @keywords internal
add_id_column <- function(df.analysis, id.name = NULL) {
  if (is.null(id.name)) {
    df.analysis$id <- seq_len(nrow(df.analysis))
    id.name <- "id"
  } else if (!(id.name %in% names(df.analysis))) {
    df.analysis[[id.name]] <- seq_len(nrow(df.analysis))
  }
  return(df.analysis)
}


# =============================================================================
# SUBGROUP APPLICATION
# =============================================================================

#' Generate Prediction Dataset with Subgroup Treatment Recommendation
#'
#' Creates a prediction dataset with a treatment recommendation flag based
#' on the subgroup definition. Supports both label expressions
#' (e.g., \code{"\{er <= 0\}"}) and bare column names (e.g., \code{"q3.1"}).
#'
#' Each element of \code{sg.harm} is processed as follows:
#' \enumerate{
#'   \item Outer braces and leading \code{!} are stripped.
#'   \item If the result matches \code{"var op value"} (where \code{op} is
#'     one of \code{<=}, \code{<}, \code{>=}, \code{>}, \code{==},
#'     \code{!=}), the comparison is executed directly on
#'     \code{df.predict[[var]]}.
#'   \item Otherwise the expression is treated as a column name and
#'     membership is \code{df.predict[[name]] == 1}.
#' }
#'
#' @param df.predict Data frame for prediction (test or validation set).
#' @param sg.harm Character vector of subgroup-defining labels. Values may
#'   be wrapped in braces and optionally negated, e.g. \code{"\{er <= 0\}"}
#'   or \code{"!\{size <= 35\}"}. Plain column names (e.g., \code{"q3.1"})
#'   are treated as binary indicators that must equal 1.
#' @param version Integer; encoding version (maintained for backward
#'   compatibility). Default: 1.
#'
#' @return Data frame with treatment recommendation flag
#'   (\code{treat.recommend}): 0 for harm subgroup, 1 for complement.
#'
#' @seealso \code{\link{evaluate_comparison}} for the operator-dispatch
#'   logic, \code{\link{forestsearch}} for the main analysis function.
#'
#' @examples
#' \dontrun{
#' # With brace-wrapped label expressions
#' sg <- c("{er <= 0}", "{size <= 35}")
#' df_out <- get_dfpred(df.predict = test_data, sg.harm = sg)
#'
#' # With negation
#' sg_neg <- c("{er <= 0}", "!{size <= 35}")
#' df_neg <- get_dfpred(df.predict = test_data, sg.harm = sg_neg)
#'
#' # With bare column names (binary indicators)
#' sg_col <- c("q1.1", "q3.1")
#' df_col <- get_dfpred(df.predict = encoded_data, sg.harm = sg_col)
#' }
#'
#' @export
get_dfpred <- function(df.predict, sg.harm, version = 1) {

  df.pred <- df.predict
  labels <- if (!is.null(names(sg.harm))) unname(sg.harm) else sg.harm

  # GRF union-of-leaves subgroups are carried as a single disjunctive
  # definition string, e.g. "(x1 > 0 & x2 <= 1) | (x1 <= 0 & x3 > 0)", which
  # is NOT an AND-composed factor vector.  Detect that form and evaluate it as
  # a disjunction of conjunctions (each conjunction an AND of "var op value"
  # comparisons) so membership matches the GRF policy tree.  All other inputs
  # fall through to the standard AND-composition below.
  if (length(labels) == 1L && grepl("|", labels, fixed = TRUE)) {
    conj_strings <- strsplit(labels, "\\s*\\|\\s*")[[1]]
    in_any <- rep(FALSE, nrow(df.pred))
    for (cs in conj_strings) {
      cs_clean <- gsub("^\\s*\\(|\\)\\s*$", "", cs)          # strip parens
      comps    <- strsplit(cs_clean, "\\s*&\\s*")[[1]]
      in_cj    <- rep(TRUE, nrow(df.pred))
      for (cmp in comps) {
        cmp_clean  <- gsub("^!?\\{(.*)\\}$", "\\1", trimws(cmp))
        is_negated <- grepl("^!", trimws(cmp))
        member     <- evaluate_comparison(cmp_clean, df.pred)
        if (is_negated) member <- !member
        in_cj <- in_cj & member
      }
      in_any <- in_any | in_cj
    }
    df.pred$treat.recommend <- ifelse(in_any, 0L, 1L)
    return(df.pred)
  }

  # Build membership indicator for each factor
  in_harm <- rep(TRUE, nrow(df.pred))

  for (lab in labels) {
    # Strip braces: "{er <= 0}" -> "er <= 0"
    clean <- gsub("^!?\\{(.*)\\}$", "\\1", lab)
    is_negated <- grepl("^!", lab)

    member <- evaluate_comparison(clean, df.pred)

    # Apply negation if needed
    if (is_negated) member <- !member

    in_harm <- in_harm & member
  }

  df.pred$treat.recommend <- ifelse(in_harm, 0L, 1L)
  df.pred
}


#' Evaluate a Comparison Expression Without eval(parse())
#'
#' Parses a string of the form \code{"var op value"} and evaluates it
#' directly against a data frame column using operator dispatch. Falls back
#' to column-name lookup for bare names.
#'
#' @param expr Character. An expression like \code{"er <= 0"},
#'   \code{"size > 35"}, \code{"grade3 == 1"}, or a bare column name
#'   like \code{"q3.1"}.
#' @param df Data frame whose columns are referenced by \code{expr}.
#'
#' @return Logical vector of length \code{nrow(df)}.
#'
#' @details
#' Supported operators (matched longest-first to avoid partial-match
#' ambiguity): \code{<=}, \code{>=}, \code{!=}, \code{==}, \code{<},
#' \code{>}.
#'
#' If no operator is found, \code{expr} is treated as a column name and
#' the result is \code{df[[expr]] == 1}.
#'
#' The value on the right-hand side is coerced to numeric when possible,
#' otherwise kept as character for string comparisons.
#'
#' @examples
#' \dontrun{
#' df <- data.frame(er = c(-1, 0, 1, 2), size = c(10, 20, 30, 40))
#' evaluate_comparison("er <= 0", df)
#' # [1]  TRUE  TRUE FALSE FALSE
#'
#' evaluate_comparison("size > 25", df)
#' # [1] FALSE FALSE  TRUE  TRUE
#' }
#'
#' @export
evaluate_comparison <- function(expr, df) {

  expr <- trimws(expr)

  # Operators ordered longest-first to avoid partial matching
  # (e.g., "<=" must be tried before "<")
  ops <- c("<=", ">=", "!=", "==", "<", ">")

  for (op in ops) {
    if (grepl(op, expr, fixed = TRUE)) {
      parts <- strsplit(expr, op, fixed = TRUE)[[1L]]
      if (length(parts) != 2L) next

      var_name <- trimws(parts[1L])
      value <- trimws(parts[2L])

      if (!var_name %in% names(df)) {
        warning("Column '", var_name, "' not found in data frame",
                call. = FALSE)
        return(rep(NA, nrow(df)))
      }

      col <- df[[var_name]]
      # Coerce factors with all-numeric levels to numeric so that
      # numeric comparisons (<=, >=, <, >) are meaningful.
      if (is.factor(col)) {
        lvls <- levels(col)
        if (!anyNA(suppressWarnings(as.numeric(lvls))))
          col <- as.numeric(as.character(col))
      }
      val <- suppressWarnings(as.numeric(value))
      if (is.na(val)) val <- value # keep as character for string comparisons

      result <- switch(
        op,
        "<=" = col <= val,
        ">=" = col >= val,
        "!=" = col != val,
        "==" = col == val,
        "<"  = col <  val,
        ">"  = col >  val
      )

      return(result)
    }
  }

  # No operator found - treat as a column name (binary indicator)
  if (expr %in% names(df)) {
    return(df[[expr]] == 1)
  }

  warning("Could not parse expression and column '", expr,
          "' not found in data frame", call. = FALSE)
  rep(NA, nrow(df))
}


#' Translate a Subgroup Label into an Evaluable Expression String
#'
#' Internal helper used by \code{compute_frontier_cis()} and
#' \code{compute_frontier_member_flags()} to turn the human-readable
#' subgroup-cut labels produced by \code{FS_labels()} into expression
#' strings safe to pass to \code{eval(parse(text = .))} against the
#' analysis data frame.
#'
#' Input is a single \code{c_label} of one of two recognised forms:
#' \itemize{
#'   \item \code{"\{<expr>\}"}      -- subgroup member  (action = 1)
#'   \item \code{"!\{<expr>\}"}     -- subgroup complement (action = 0)
#' }
#' The \code{<expr>} inside the braces is either a comparison
#' (\code{"wtkg <= 86.6"}) or a bare identifier naming a binary
#' indicator factor (\code{"symptom"}).
#'
#' Translation rules:
#' \itemize{
#'   \item \code{"\{<cmp>\}"}    -> \code{"<cmp>"}
#'   \item \code{"!\{<cmp>\}"}   -> \code{"!(<cmp>)"} (parenthesised so '!'
#'                                   binds to the whole comparison rather
#'                                   than to the left operand alone)
#'   \item \code{"\{<id>\}"}     -> \code{"<id> == 1"}
#'   \item \code{"!\{<id>\}"}    -> \code{"<id> == 0"} (the operationally
#'                                   correct complement of a binary 0/1
#'                                   indicator factor; \code{!factor} is
#'                                   not well-defined in base R and emits
#'                                   the \code{Ops.factor} warning while
#'                                   silently producing an all-NA mask)
#' }
#'
#' Malformed input -- non-character, NA, empty string, missing braces,
#' empty braces, or a bare-name path whose content is not a valid R
#' identifier -- raises a loud \code{stop()}.  Subgroup labels are
#' load-bearing for inferential output, so any deviation from the
#' expected forms must surface as an error rather than degrade silently
#' to a wrong-but-quiet result.
#'
#' @param c_label Character scalar.  A single cut label from a frontier
#'   row's \code{m_cols} entries.
#'
#' @return Character scalar suitable for \code{eval(parse(text = .))}
#'   against the analysis data frame.
#'
#' @keywords internal
#' @noRd
.label_to_expr <- function(c_label) {
  # Hard validation: helper input must be a single non-NA non-empty string.
  if (!is.character(c_label) || length(c_label) != 1L ||
      is.na(c_label) || nchar(c_label) == 0L) {
    stop(".label_to_expr(): 'c_label' must be a single non-empty character ",
         "string; got: ",
         paste(utils::capture.output(utils::str(c_label)), collapse = " "),
         call. = FALSE)
  }

  # Detect leading "!" (complement marker) and extract the inner content
  # of {...}.  The full label must match one of the two recognised forms;
  # anything else is a malformed label and we error loudly rather than
  # silently mangling it.
  negate <- startsWith(c_label, "!")
  if (negate) {
    m <- regmatches(c_label, regexec("^!\\{(.+)\\}$", c_label))[[1L]]
  } else {
    m <- regmatches(c_label, regexec("^\\{(.+)\\}$",  c_label))[[1L]]
  }
  if (length(m) != 2L || nchar(m[2L]) == 0L) {
    stop(".label_to_expr(): unrecognised subgroup label form: '", c_label,
         "'. Expected '{<expr>}' or '!{<expr>}' (FS_labels() output).",
         call. = FALSE)
  }
  inner <- m[2L]

  # Bare column name (no comparison operator) => factor-equality semantics.
  is_bare <- !grepl("[<>=!]", inner)
  if (is_bare) {
    # Inner must look like a single R identifier; reject anything weirder
    # (e.g. embedded spaces or operators we missed) so labels can't quietly
    # become wrong code.
    if (!grepl("^[.A-Za-z_][.A-Za-z0-9_]*$", inner)) {
      stop(".label_to_expr(): bare-name label '", c_label,
           "' does not contain a valid R identifier (got: '", inner, "').",
           call. = FALSE)
    }
    return(if (negate) paste0(inner, " == 0") else paste0(inner, " == 1"))
  }

  # Comparison form: wrap in parens when negating so '!' binds to the
  # whole comparison rather than to the left operand.
  if (negate) paste0("!(", inner, ")") else inner
}


# =============================================================================
# PARAMETER HELPERS
# =============================================================================

#' Get Parameter with Default Fallback
#'
#' Safely retrieves a named element from a list, returning a default value
#' if the element is missing or \code{NULL}.
#'
#' @param args_list List to extract from.
#' @param param_name Character. Name of the element to retrieve.
#' @param default_value Default value to return if element is missing or
#'   \code{NULL}.
#'
#' @return The value of \code{args_list[[param_name]]} if present and
#'   non-\code{NULL}, otherwise \code{default_value}.
#'
#' @keywords internal
get_param <- function(args_list, param_name, default_value) {
  if (hasName(args_list, param_name) && !is.null(args_list[[param_name]])) {
    return(args_list[[param_name]])
  }
  return(default_value)
}


#' Evaluate an expression string in a data-frame scope
#'
#' Parses and evaluates \code{expr} in a restricted environment
#' containing only the columns of \code{df} (parent: \code{baseenv()}).
#' This isolates evaluation from the global environment, reducing
#' scope for unintended side effects.
#'
#' @param df Data frame providing column names as variables.
#' @param expr Character. Expression to evaluate
#'   (e.g., \code{"BM > 1 & tmrsize > 19"}).
#'
#' @return Result of evaluating \code{expr}, or \code{NULL} on failure.
#'
#' @note
#'   \code{eval(parse())} is used intentionally here.
#'   \code{\link{evaluate_comparison}} handles only single comparisons
#'   (e.g., \code{"er <= 0"}); this function is needed for the compound
#'   logical expressions produced by the ForestSearch subgroup enumeration
#'   algorithm (e.g., \code{"er <= 0 & nodes > 3"}).  Evaluation is
#'   sandboxed: the environment contains only the columns of \code{df}
#'   with \code{baseenv()} as parent, so neither the global environment
#'   nor any package namespace is in scope.  No user-supplied strings are
#'   evaluated; only internally-constructed subgroup definition strings
#'   reach this function.
#'
#' @seealso \code{\link{evaluate_comparison}} for the single-comparison
#'   operator-dispatch alternative that avoids \code{eval(parse())}.
#'
#' @keywords internal
safe_eval_expr <- function(df, expr) {
  tryCatch({
    env <- list2env(as.list(df), parent = baseenv())
    eval(parse(text = expr), envir = env)
  }, error = function(e) {
    warning(
      "Failed to evaluate expression: '", expr, "' - ", e$message,
      call. = FALSE
    )
    NULL
  })
}


# ─────────────────────────────────────────────────────────────────────
# Convenience wrapper: subset rows using an expression string
# ─────────────────────────────────────────────────────────────────────

#' Subset a data frame using an expression string
#'
#' Thin wrapper around \code{\link{safe_eval_expr}} that uses the
#' logical result to subset rows.
#'
#' @param df Data frame.
#' @param expr Character. Subset expression
#'   (e.g., \code{"BM > 1 & tmrsize > 19"}).
#'
#' @return Subset of \code{df}, or \code{NULL} on failure.
#'
#' @keywords internal
safe_subset <- function(df, expr) {
  idx <- safe_eval_expr(df, expr)
  if (is.null(idx)) return(NULL)
  df[idx, , drop = FALSE]
}


# =============================================================================
# ARGUMENT FILTERING
# =============================================================================

#' Filter a Parameter List to a Function's Formals
#'
#' Given a named list of user-supplied parameters and a target function,
#' returns only the parameter entries whose names appear in the target's
#' \code{\link[base]{formals}}.  Entries with names that do not match any
#' formal (typos, renamed parameters, parameters from a different function)
#' are either silently dropped (default) or reported via \code{warning()}.
#'
#' This replaces the older "hand-maintained \code{valid_pnames} whitelist"
#' pattern in \code{.run_fs_analysis_gen()} and \code{.run_grf_analysis_gen()}.
#' New \code{forestsearch()} or \code{grf.subg.harm.*()} arguments flow
#' through automatically; authors of new parameters no longer need to
#' update a whitelist in a separate file to make the new parameter
#' reachable from user-level \code{fs_params} / \code{grf_params} lists.
#'
#' @param params Named list of user-supplied parameter values.
#' @param target_fun A function (not its name).  Its \code{\link{formals}}
#'   determine the set of valid parameter names.
#' @param exclude Character vector of formal-argument names to explicitly
#'   \emph{exclude} from the allowlist, even though they appear in
#'   \code{formals(target_fun)}.  Useful for arguments the caller manages
#'   internally (e.g., \code{df.analysis}, \code{confounders.name},
#'   \code{details}, \code{plot.sg}, \code{quiet}) and does not want users
#'   to override via the params list.
#' @param warn_unknown Logical.  If \code{TRUE}, emit a \code{warning()}
#'   listing any \code{params} names that were dropped because they do not
#'   appear in \code{formals(target_fun)} (typo-detection aid).  Default
#'   \code{FALSE} (silent drop, matching legacy behavior).
#'
#' @return A named list, the subset of \code{params} whose names are in
#'   \code{formals(target_fun)} and not in \code{exclude}.
#'
#' @keywords internal
# Typical call sites inside the package:
#
#   # In .run_fs_analysis_gen(), params = user's fs_params list:
#   user_fs_args <- filter_valid_args(
#     params       = params,
#     target_fun   = forestsearch,
#     exclude      = c("df.analysis", "confounders.name",
#                      "details", "plot.sg", "quiet"),
#     warn_unknown = FALSE
#   )
#
# Return value for a params list with a typo:
#   params = list(hr.threshold = 2.0, sg_focus = "maxSG", my_typo = "x")
#   filter_valid_args(params, forestsearch) -> list(hr.threshold = 2.0,
#                                                    sg_focus = "maxSG")
filter_valid_args <- function(params,
                              target_fun,
                              exclude = character(0),
                              warn_unknown = FALSE) {
  if (is.null(params) || length(params) == 0L) return(list())
  if (!is.function(target_fun))
    stop("'target_fun' must be a function.", call. = FALSE)

  allowed <- setdiff(names(formals(target_fun)), exclude)
  # Exclude '...' — passing arbitrary extras via ... creates its own
  # silent-failure risks and is not how fs_params is intended to be used.
  allowed <- setdiff(allowed, "...")

  param_names <- names(params)
  if (is.null(param_names)) return(list())

  keep_mask <- param_names %in% allowed
  dropped   <- param_names[!keep_mask]

  if (warn_unknown && length(dropped) > 0L) {
    warning(sprintf(
      "filter_valid_args: dropped %d unknown parameter(s): %s",
      length(dropped),
      paste(shQuote(dropped), collapse = ", ")
    ), call. = FALSE)
  }

  params[keep_mask]
}


# =============================================================================
# PARALLEL RESULT HELPERS
# =============================================================================

#' Collect Results from foreach with Error Handling
#'
#' Separates successful results from errors in the output of a
#' \code{\link[foreach]{foreach}} loop run with
#' \code{.errorhandling = "pass"}.  Successful results are combined via
#' \code{\link[data.table]{rbindlist}} (with an \code{rbind} fallback
#' if \pkg{data.table} is not available) and failed tasks are counted,
#' reported, and optionally escalated to a hard error.
#'
#' This replaces the fragile pattern of calling \code{nrow()} or
#' \code{rbind()} directly on a raw \code{foreach} result list, which
#' fails silently when error objects are mixed in with data-frame rows.
#'
#' @details
#' Design rationale for the reporting strategy:
#' \itemize{
#'   \item A \code{\link{warning}} is emitted so that calling code
#'     (and \code{tryCatch} / \code{withCallingHandlers} blocks) can
#'     capture the failure condition programmatically.
#'   \item The error summary is also printed with \code{\link{cat}} to
#'     \code{stderr}, because \code{\link{warning}} and
#'     \code{\link{message}} output is sometimes buffered or
#'     suppressed inside future/foreach parallel workers or when
#'     \code{options(warn = -1)} is set by user code upstream.  The
#'     \code{cat()} output is the visible-no-matter-what fallback.
#'   \item When \code{stop_on_all_fail = TRUE} (the default), a
#'     completely empty result list is escalated to an error rather
#'     than silently returning an empty data frame.  This avoids
#'     downstream code proceeding with zero rows and producing
#'     misleading summaries.  Calibration code that may legitimately
#'     tolerate some failures (e.g. Monte Carlo FPR estimation) can
#'     set \code{stop_on_all_fail = FALSE}.
#' }
#'
#' The returned object is always a data frame -- never \code{NULL} --
#' because attributes (\code{n_failed}, \code{n_total}) attached to
#' \code{NULL} are silently discarded by R, whereas attributes on an
#' empty data frame are preserved and inspectable by the caller.
#'
#' @param raw_list List returned by \code{foreach(...,
#'   .errorhandling = "pass")}.  Each element is either a data frame,
#'   data.table, or row-bindable object (success) or a condition
#'   object (failure).
#' @param label Character.  Optional label included in the warning
#'   message to identify which simulation phase produced the errors
#'   (e.g. \code{"H1 alt"}, \code{"Bootstrap"}).  Default \code{""}.
#' @param stop_on_all_fail Logical.  If \code{TRUE} (default),
#'   raise an error when every task in \code{raw_list} failed.  If
#'   \code{FALSE}, return an empty data frame and only emit a
#'   warning.  Default \code{TRUE}.
#' @param max_error_messages Integer.  Maximum number of distinct
#'   error messages to print in the diagnostic output.  Default
#'   \code{3L}.
#' @param keep_diagnostics Logical.  If \code{TRUE}, scan each
#'   successful element for a \code{"diagnostics"} attribute and
#'   collect them into a list attached to the returned object as
#'   \code{attr(result, "diagnostics")}.  Used with
#'   \code{\link{run_simulation_analysis}}'s \code{keep} / 
#'   \code{keep_first_n} mechanism to retain per-replicate heavy
#'   objects (FS or GRF result objects, candidate tables) that
#'   \code{data.table::rbindlist()} would otherwise drop.
#'   Default \code{FALSE} (preserves minimal-memory behavior).
#'
#' @return A data frame of row-bound successful results.  Always a
#'   data frame; \strong{never} \code{NULL} -- an empty data frame is
#'   returned when every task failed and \code{stop_on_all_fail = FALSE}.
#'   Two attributes are always attached:
#'   \describe{
#'     \item{\code{n_failed}}{Integer.
#'       Number of tasks that returned errors.}
#'     \item{\code{n_total}}{Integer.
#'       Total number of tasks (successes + failures).}
#'   }
#'   When \code{keep_diagnostics = TRUE}, a third attribute
#'   \code{"diagnostics"} may be attached -- a named list of
#'   per-replicate diagnostic objects, keyed by \code{"sim<ID>"}
#'   when the source element carries an \code{"sim_id"} attribute
#'   (\code{\link{run_simulation_analysis}} sets this automatically).
#'
#' @section Preserving per-replicate diagnostics:
#' \code{data.table::rbindlist()} drops per-element attributes during
#' row-binding.  When the caller has populated each replicate with
#' heavy diagnostic objects (e.g. via
#' \code{\link{run_simulation_analysis}} with a non-empty
#' \code{keep} argument), set \code{keep_diagnostics = TRUE} to
#' retain them.  The diagnostics attribute on each input element
#' must carry \code{attr(..., "sim_id")} for stable keying; that is
#' set automatically by \code{run_simulation_analysis()}.
#'
#' @examples
#' \donttest{
#' library(foreach)
#' library(doFuture)
#' future::plan("sequential")
#'
#' raw <- foreach(i = 1:5, .errorhandling = "pass") %dofuture% {
#'   if (i == 3L) stop("simulated failure")
#'   data.frame(task = i, value = rnorm(1))
#' }
#' res <- collect_results(raw, label = "demo")
#' # Warning: demo: 1 of 5 tasks failed.
#' nrow(res)
#' # [1] 4
#' attr(res, "n_failed")
#' # [1] 1
#' }
#'
#' @seealso \code{\link{reset_workers}} for resetting the
#'   \pkg{future} plan and releasing worker memory between
#'   simulation phases.
#'
#' @export
collect_results <- function(raw_list,
                            label = "",
                            stop_on_all_fail = TRUE,
                            max_error_messages = 3L,
                            keep_diagnostics = FALSE) {

  if (!is.list(raw_list)) {
    stop("'raw_list' must be a list returned by foreach().", call. = FALSE)
  }
  n_total <- length(raw_list)

  if (n_total == 0L) {
    result <- data.frame()
    attr(result, "n_failed") <- 0L
    attr(result, "n_total")  <- 0L
    return(result)
  }

  is_err   <- vapply(raw_list, inherits, logical(1), "error")
  n_failed <- sum(is_err)

  prefix <- if (nzchar(label)) paste0(label, ": ") else ""

  # --------------------------------------------------------------------
  # Report failures via BOTH cat() (always visible) and warning()
  # (programmatically catchable).  warning() is sometimes buffered or
  # swallowed inside future/foreach workers, so cat() is the belt-and-
  # braces visible fallback.
  # --------------------------------------------------------------------
  if (n_failed > 0L) {
    err_msgs  <- vapply(raw_list[is_err], conditionMessage, character(1))
    uniq_msgs <- utils::head(unique(err_msgs),
                             max(1L, as.integer(max_error_messages)))

    cat(sprintf("*** %s%d of %d tasks failed ***\n",
                prefix, n_failed, n_total),
        file = stderr())
    cat("  First error message(s):\n", file = stderr())
    for (msg in uniq_msgs) cat("    ", msg, "\n", file = stderr())

    warning(sprintf("%s%d of %d tasks failed. First error: %s",
                    prefix, n_failed, n_total, uniq_msgs[1L]),
            call. = FALSE)
  }

  # --------------------------------------------------------------------
  # Harvest per-replicate diagnostics BEFORE rbindlist (which drops
  # element-level attributes).  Only non-NULL "diagnostics" attributes
  # are collected.  See run_simulation_analysis(keep = ..., keep_first_n = ...)
  # for the producer side.
  # --------------------------------------------------------------------
  diag_list <- NULL
  if (isTRUE(keep_diagnostics)) {
    diag_list <- list()
    good_idx  <- which(!is_err)
    for (i in good_idx) {
      d <- attr(raw_list[[i]], "diagnostics")
      if (!is.null(d)) {
        sim_id <- attr(d, "sim_id")
        nm <- if (!is.null(sim_id) && length(sim_id) == 1L)
          sprintf("sim%d", as.integer(sim_id)) else sprintf("i%d", i)
        diag_list[[nm]] <- d
      }
    }
  }

  # --------------------------------------------------------------------
  # Row-bind successful results.  Prefer data.table::rbindlist for
  # fill = TRUE semantics (column-union across heterogeneous rows);
  # fall back to do.call(rbind, ...) if data.table is unavailable.
  # --------------------------------------------------------------------
  good <- raw_list[!is_err]

  if (length(good) == 0L) {
    if (isTRUE(stop_on_all_fail)) {
      stop(sprintf(
        "%sAll %d tasks failed; see warning() for first error.",
        prefix, n_total),
        call. = FALSE)
    }
    result <- data.frame()
  } else if (requireNamespace("data.table", quietly = TRUE)) {
    result <- data.table::rbindlist(good, use.names = TRUE, fill = TRUE)
    result <- as.data.frame(result)
  } else {
    result <- tryCatch(
      do.call(rbind, good),
      error = function(e) {
        stop(sprintf(
          "%sCould not rbind() successful results; install 'data.table' ",
          "for heterogeneous-column support. Original error: %s",
          prefix, conditionMessage(e)),
          call. = FALSE)
      }
    )
    result <- as.data.frame(result)
  }

  attr(result, "n_failed") <- as.integer(n_failed)
  attr(result, "n_total")  <- as.integer(n_total)
  if (isTRUE(keep_diagnostics) && length(diag_list) > 0L) {
    attr(result, "diagnostics") <- diag_list
  }
  result
}


#' Reset a Parallel Worker Pool
#'
#' Tears down the current \pkg{future} plan, forces garbage
#' collection, optionally pauses, and spins up a fresh worker pool.
#' Used to release worker-side memory between simulation phases
#' (e.g. between alternative and null Monte Carlo runs) so that
#' accumulated R-session state in long-running workers does not
#' bloat memory or cause sporadic failures.
#'
#' @details
#' The worker reset sequence is:
#' \enumerate{
#'   \item \code{future::plan("sequential")} -- dismantles the
#'     existing worker pool; R processes terminate and their memory
#'     is returned to the OS.
#'   \item \code{gc(verbose = FALSE)} -- reclaims main-process memory
#'     holding references to now-defunct futures.
#'   \item \code{Sys.sleep(sleep)} -- brief pause to let the OS
#'     reclaim sockets / pipes before the new pool is requested.
#'     A small non-zero sleep (the default \code{1}) materially
#'     reduces \code{multisession} setup failures observed on busy
#'     Linux servers; set to \code{0} to skip.
#'   \item \code{future::plan(strategy, workers = workers)} -- starts
#'     a fresh pool.
#' }
#'
#' This function is a no-op if \code{future} is not installed or if
#' the requested strategy cannot be initialised; a warning is emitted
#' and the previous plan is left in place.
#'
#' @param workers Integer.  Number of workers for the new pool.
#'   Default \code{NULL} leaves the current plan's worker count
#'   unchanged (useful if a reset without resize is wanted; this
#'   requires \code{future} to be installed).
#' @param strategy Character.  The \pkg{future} strategy to
#'   reinstate.  Default \code{"multisession"}.  Other reasonable
#'   choices are \code{"multicore"} (Linux/macOS only) and
#'   \code{"sequential"} (to disable parallelism entirely).
#' @param sleep Numeric.  Seconds to pause between teardown and
#'   setup.  Default \code{1}.  Set to \code{0} to skip.
#' @param gc Logical.  Whether to force garbage collection between
#'   teardown and setup.  Default \code{TRUE}.
#' @param quiet Logical.  Suppress informational \code{message()}
#'   output.  Default \code{FALSE}.
#'
#' @return Invisibly, a list with the previous and current plan
#'   class names: \code{list(previous = <chr>, current = <chr>)}.
#'
#' @examples
#' \donttest{
#' if (requireNamespace("future", quietly = TRUE)) {
#'   future::plan("multisession", workers = 2L)
#'   # ... run alternative simulations ...
#'   reset_workers(workers = 2L)
#'   # ... run null simulations ...
#'   future::plan("sequential")
#' }
#' }
#'
#' @seealso \code{\link{collect_results}} for error-tolerant
#'   collection of \code{foreach} output.
#'
#' @export
reset_workers <- function(workers   = NULL,
                          strategy  = "multisession",
                          sleep     = 1,
                          gc        = TRUE,
                          quiet     = FALSE) {

  if (!requireNamespace("future", quietly = TRUE)) {
    warning("'future' is not installed; reset_workers() is a no-op.",
            call. = FALSE)
    return(invisible(list(previous = NA_character_, current = NA_character_)))
  }

  prev_class <- class(future::plan())[1L]

  # -- Teardown ---------------------------------------------------------
  tryCatch(
    future::plan("sequential"),
    error = function(e) {
      warning(sprintf("Could not tear down existing plan: %s",
                      conditionMessage(e)),
              call. = FALSE)
    }
  )

  if (isTRUE(gc)) {
    gc(verbose = FALSE)
  }

  if (is.numeric(sleep) && length(sleep) == 1L && sleep > 0) {
    Sys.sleep(sleep)
  }

  # -- Setup ------------------------------------------------------------
  # If the caller wants sequential, we're already there -- skip the setup.
  if (identical(strategy, "sequential")) {
    if (!isTRUE(quiet)) {
      message(sprintf("reset_workers: plan reset to sequential (was %s).",
                      prev_class))
    }
    return(invisible(list(previous = prev_class, current = "sequential")))
  }

  new_plan <- tryCatch({
    if (is.null(workers)) {
      future::plan(strategy)
    } else {
      future::plan(strategy, workers = as.integer(workers))
    }
    class(future::plan())[1L]
  }, error = function(e) {
    warning(sprintf("Could not start '%s' plan: %s. Leaving plan as sequential.",
                    strategy, conditionMessage(e)),
            call. = FALSE)
    "sequential"
  })

  if (!isTRUE(quiet)) {
    if (is.null(workers)) {
      message(sprintf("reset_workers: plan reset to %s (was %s).",
                      new_plan, prev_class))
    } else {
      message(sprintf("reset_workers: plan reset to %s with %d worker(s) (was %s).",
                      new_plan, as.integer(workers), prev_class))
    }
  }

  invisible(list(previous = prev_class, current = new_plan))
}


# ============================================================================
# .normalize_sg_focus() -- internal vocabulary alias
# ============================================================================
# The package's `sg_focus` argument originally used a Cox / hazard-ratio
# vocabulary ("hr", "hrMaxSG", "hrMinSG") that pre-dates the GLM extension
# (continuous MD, binary OR/RR/RD, count IRR).  The GLM-natural vocabulary
# uses "eff*" prefixes -- "effMaxSG", "effMinSG", "eff" -- which read
# correctly regardless of effect measure.
#
# Both vocabularies are accepted throughout the user-facing API; this
# helper translates the new names to the canonical internal "hr*" form
# at entry points so that downstream code (which is keyed on the
# canonical form) needs no changes.
#
# Aliases (case-sensitive, matches `match.arg` conventions):
#   "effMaxSG" -> "hrMaxSG"
#   "effMinSG" -> "hrMinSG"
#   "eff"      -> "hr"
#   "maxcons"  -> "hr"      (says what the rule does: consistency argmax)
#
# NOT aliases -- these are distinct canonical foci, returned unchanged:
#   "maxSG"      keys (-N, -Pcons, K); takes no effect band; rejects any
#                selection_rule other than "neighborhood".  It is NOT a
#                spelling of hrMaxSG, whose key is (-in_band, -N, -Pcons,
#                -hr, K).
#   "minSG"      keys (N, -Pcons, K); same relationship to hrMinSG.
#   "maxeff"     keys (-hr, K) over ALL candidates, ungated.
#   "maxeffCons" keys (-hr, K) among consistency-qualifying candidates.
#
# Any other value is returned unchanged so the downstream whitelist
# check produces its usual error message.
# ----------------------------------------------------------------------------

#' The alias -> canonical map, as data
#'
#' Single source of truth for the alias relation.  \code{.normalize_sg_focus()}
#' reads it forwards; \code{.sg_focus_aliases_of()} reads it backwards to name
#' the full alias class in the run-time announcement.  Keeping one table
#' instead of two switch()es is what stops the announcement from claiming an
#' alias set the normalizer does not actually implement.
#'
#' Order matters only cosmetically: \code{.sg_focus_aliases_of()} preserves it,
#' so \code{"hr"} reports \code{"eff, maxcons"}.
#'
#' @noRd
.FS_SG_FOCUS_ALIASES <- c(effMaxSG = "hrMaxSG",
                          effMinSG = "hrMinSG",
                          eff      = "hr",
                          maxcons  = "hr")


#' Translate the new effect-vocabulary `sg_focus` aliases to canonical form
#'
#' Accepts the GLM-natural vocabulary (\code{"effMaxSG"},
#' \code{"effMinSG"}, \code{"eff"}) and the descriptive alias
#' \code{"maxcons"}, and translates to the canonical Cox-flavored internal
#' names (\code{"hrMaxSG"}, \code{"hrMinSG"}, \code{"hr"}).  Unrecognized
#' values pass through unchanged so the caller's own whitelist check fires.
#'
#' Because every entry point (\code{\link{forestsearch}},
#' \code{\link{subgroup.consistency}}, \code{dina_subgroup()},
#' \code{dina_subgroup_bootstrap()}) normalizes before whitelisting, an alias
#' added here is accepted by all of them without further change.
#'
#' This is an internal helper.  User code does not call it directly;
#' \code{\link{forestsearch}} and \code{\link{subgroup.consistency}}
#' invoke it on entry.
#'
#' @param sg_focus Character scalar.
#'
#' @return Character scalar in canonical form.
#'
#' @keywords internal
#' @noRd
.normalize_sg_focus <- function(sg_focus) {
  if (!is.character(sg_focus) || length(sg_focus) != 1L) {
    return(sg_focus)  # downstream whitelist will reject
  }
  i <- match(sg_focus, names(.FS_SG_FOCUS_ALIASES))
  if (is.na(i)) sg_focus else unname(.FS_SG_FOCUS_ALIASES[[i]])
}

#' Every alias that resolves to a given canonical focus
#'
#' @param canonical Character scalar, a canonical focus name.
#' @return Character vector of alias spellings, possibly empty.
#' @noRd
.sg_focus_aliases_of <- function(canonical) {
  names(.FS_SG_FOCUS_ALIASES)[.FS_SG_FOCUS_ALIASES == canonical]
}

#' Announce sg_focus alias resolution and effect-argmax collapse (run time)
#'
#' Five spellings resolve to one rule and, on the DINA/GRF paths, two more
#' collapse onto the effect argmax.  Before this, all of that was silent: a run
#' requested as \code{sg_focus = "eff"} ranked by a rule the caller never named
#' and left no trace of the substitution in the transcript.
#'
#' At most one message fires -- no alias resolves to \code{"maxeff"} or
#' \code{"maxeffCons"}, so the two conditions are disjoint.
#'
#' \code{message()}, never \code{cat()}: the simulation cells run with
#' \code{quiet = TRUE} and must stay silent, and stderr is suppressible with
#' \code{suppressMessages()}.
#'
#' @param sg_focus_user The spelling the caller passed.
#' @param sg_focus The canonical form after \code{.normalize_sg_focus()}.
#' @param subgroup_method One of "consistency", "dina", "grf".
#' @param quiet Logical. When TRUE nothing is emitted.
#' @return `NULL`, invisibly. Called for its side effect.
#' @noRd
.announce_sg_focus <- function(sg_focus_user, sg_focus, subgroup_method,
                               quiet = FALSE) {
  if (isTRUE(quiet)) return(invisible(NULL))
  if (!is.character(sg_focus_user) || length(sg_focus_user) != 1L) {
    return(invisible(NULL))
  }

  if (!identical(sg_focus_user, sg_focus)) {
    message(sprintf(
      "sg_focus '%s' resolves to canonical rule '%s' (aliases: %s).",
      sg_focus_user, sg_focus,
      paste(.sg_focus_aliases_of(sg_focus), collapse = ", ")))
  }

  # DINA and GRF compute no Pcons, so the "Cons" qualifier has nothing to bind
  # to and both spellings rank as the plain effect argmax.  Deliberate -- see
  # the DELIBERATE SYNONYMS blocks in dina_subgroup() and forestsearch()'s
  # frontier_rule switch -- but not something a caller can infer from the name.
  if (identical(subgroup_method, "dina") || identical(subgroup_method, "grf")) {
    if (sg_focus %in% c("maxeff", "maxeffCons")) {
      message(sprintf(
        paste0("sg_focus '%s' ranks as the effect argmax on the %s path ",
               "(no Pcons is computed)."),
        sg_focus_user, subgroup_method))
    }
  }

  invisible(NULL)
}


# =============================================================================
# DINA screening-stage helpers (Phase 2: use_dina)
# =============================================================================

#' Map a forestsearch outcome_type to a DINA family
#'
#' @param outcome_type One of "survival", "binary", "continuous", "count".
#' @return The corresponding DINA family string.
#' @noRd
.map_dina_family <- function(outcome_type) {
  switch(outcome_type,
    survival   = "cox",
    binary     = "binomial",
    continuous = "gaussian",
    count      = "poisson",
    stop(".map_dina_family(): unrecognised outcome_type '", outcome_type, "'.")
  )
}

#' Annotate a c2 / p* echo that the running path never consults
#'
#' \code{subgroup_method = "dina"} selects through \code{dina_subgroup()} and
#' \code{"grf"} through the GRF policy tree / DR-candidate frontier; both
#' return before the consistency stage, so the consistency threshold
#' (\code{consistency.threshold} / \code{hr.consistency}, "c2") and the
#' consistency RATE threshold (\code{pconsistency.threshold}, "p*") are never
#' read.  Output that echoes them back said nothing about that -- the
#' motivating case is \code{quarto/simulations/gbsg_020/summary_grfmr.qmd},
#' which runs \code{hr.threshold = 0.90} against the inert default c2 = 1.0
#' under \code{grf} with nothing in its output saying c2 was never consulted.
#'
#' Display only: no value changes, no warning, no error.
#'
#' @param subgroup_method The resolved \code{subgroup_method}, or \code{NULL}.
#' @return A short suffix to append to the echoed value, or \code{""} on the
#'   consistency path.
#' @noRd
.fs_c2_inert_note <- function(subgroup_method) {
  if (is.null(subgroup_method) || length(subgroup_method) != 1L) return("")
  sm <- as.character(subgroup_method)[1L]
  if (is.na(sm) || !sm %in% c("dina", "grf")) return("")
  sprintf("  [not used on this path: subgroup_method = \"%s\"]", sm)
}


#' The seven \code{dina_frontier()} keys \code{dina_args} recognises
#'
#' \code{scope}, \code{m_diff}, \code{n_min}, \code{direction},
#' \code{max_per_covariate}, \code{max_subgroups} and \code{digits} tune the
#' frontier EXTRACTION.  All seven are inert under
#' \code{subgroup_method = "dina"}, which selects through
#' \code{dina_subgroup()} and never consults \code{da$frontier}.
#' @noRd
.DINA_FRONTIER_KEYS <- c("scope", "m_diff", "n_min", "direction",
                         "max_per_covariate", "max_subgroups", "digits")


#' Resolve and validate the \code{dina_args} list for \code{forestsearch()}
#'
#' Fills defaults (several inherited from the enclosing \code{forestsearch()}
#' call) and rejects unknown keys with a loud error.  Splits the result into
#' the keys destined for \code{dina()} (the fit) and those destined for
#' \code{dina_frontier()} (the extraction).
#'
#' @param dina_args User-supplied list (possibly empty).
#' @param outcome_type forestsearch outcome_type, for the family default.
#' @param n_min_default forestsearch \code{n.min}, the default frontier
#'   \code{n_min}.
#' @param seed_default forestsearch \code{seedit}, the default DINA seed.
#' @return A list with elements \code{fit} (named list of \code{dina()}
#'   arguments) and \code{frontier} (named list of \code{dina_frontier()}
#'   arguments).
#' @noRd
.resolve_dina_args <- function(dina_args, outcome_type, n_min_default,
                               seed_default) {
  if (is.null(dina_args)) dina_args <- list()
  if (!is.list(dina_args)) {
    stop("`dina_args` must be a list.", call. = FALSE)
  }
  fit_keys      <- c("family", "seed", "n_folds", "cens_type", "cens_params")
  frontier_keys <- .DINA_FRONTIER_KEYS
  # screening-behavior keys: control HOW use_dina screening turns the DINA
  # fit into candidate cuts (frontier vs. single selected cut) and how deep
  # the selected-cut search runs.  Not passed to dina() or dina_frontier();
  # max_depth / grid_probs are forwarded to dina_subgroup() at the selection
  # sites, selected_only is consumed directly by forestsearch().
  behavior_keys <- c("selected_only", "max_depth", "grid_probs",
                     "select_statistic")
  recognised    <- c(fit_keys, frontier_keys, behavior_keys)

  nms <- names(dina_args)
  if (length(dina_args) > 0L && (is.null(nms) || any(nms == ""))) {
    stop("`dina_args` must be a fully named list.", call. = FALSE)
  }
  unknown <- setdiff(nms, recognised)
  if (length(unknown) > 0L) {
    stop("`dina_args` has unrecognised key(s): ",
         paste(shQuote(unknown), collapse = ", "),
         ".  Recognised keys: ",
         paste(shQuote(recognised), collapse = ", "), ".",
         call. = FALSE)
  }

  get_arg <- function(key, default) if (key %in% nms) dina_args[[key]] else default

  # selected_only: when TRUE (the default, matching GRF's
  # return_selected_cuts_only), use_dina screening contributes the SINGLE cut
  # dina_subgroup() selects (using forestsearch's own sg_focus /
  # selection_rule / etc.); set FALSE to contribute the full dina_frontier()
  # candidate set instead.
  selected_only <- get_arg("selected_only", TRUE)
  if (!is.logical(selected_only) || length(selected_only) != 1L ||
      is.na(selected_only)) {
    stop("`dina_args$selected_only` must be a single TRUE/FALSE.",
         call. = FALSE)
  }

  # max_depth / grid_probs: forwarded to dina_subgroup() at the selected-cut
  # and subgroup_method = "dina" sites.  Default max_depth = 2L aligns DINA with
  # the consistency search (maxk = 2) and GRF (grf_depth = 2): the selected cut
  # may be an AND-conjunction of two covariates, whose component cuts are then
  # composed by the consistency search as usual.  Set 1L for depth-1
  # (single-covariate) candidates only.
  max_depth <- get_arg("max_depth", 2L)
  max_depth <- suppressWarnings(as.integer(max_depth))
  if (length(max_depth) != 1L || is.na(max_depth) ||
      !max_depth %in% c(1L, 2L)) {
    stop("`dina_args$max_depth` must be 1 or 2.", call. = FALSE)
  }
  grid_probs <- get_arg("grid_probs", seq(0.1, 0.9, by = 0.1))
  if (!is.numeric(grid_probs) || length(grid_probs) < 1L ||
      anyNA(grid_probs) || any(grid_probs < 0) || any(grid_probs > 1)) {
    stop("`dina_args$grid_probs` must be a numeric vector in [0, 1] ",
         "with no NAs.", call. = FALSE)
  }

  # select_statistic: which statistic ranks the qualifying candidate family.
  # "dina" (default) ranks on DINA's native subgroup-mean tau-hat -- the
  # legacy behaviour, unchanged.  "effect" ranks on the inferential effect
  # measure (Cox HR for survival; OR/MD/IRR under the GLM extension), computed
  # with the SAME per-candidate estimator multiplier resampling (MR) uses, so
  # the realized selection is the exact event MR then de-biases.
  select_statistic <- get_arg("select_statistic", "dina")
  if (!is.character(select_statistic) || length(select_statistic) != 1L ||
      !select_statistic %in% c("dina", "effect")) {
    stop("`dina_args$select_statistic` must be \"dina\" or \"effect\".",
         call. = FALSE)
  }

  # Fit arguments: family + seed always set; the remaining fit keys are
  # forwarded to dina() ONLY when the user supplied them, so dina()'s own
  # defaults otherwise apply (no silently invented values).
  fit <- list(
    family = get_arg("family", .map_dina_family(outcome_type)),
    seed   = get_arg("seed", seed_default)
  )
  for (k in c("n_folds", "cens_type", "cens_params")) {
    if (k %in% nms) fit[[k]] <- dina_args[[k]]
  }

  # Frontier arguments: explicit defaults, n_min inherits forestsearch n.min.
  frontier <- list(
    scope             = get_arg("scope", "wide"),
    m_diff            = get_arg("m_diff", NULL),
    n_min             = get_arg("n_min", n_min_default),
    direction         = get_arg("direction", "both"),
    max_per_covariate = get_arg("max_per_covariate", 3L),
    max_subgroups     = get_arg("max_subgroups", 10L),
    digits            = get_arg("digits", 3L)
  )

  list(fit = fit, frontier = frontier, selected_only = selected_only,
       select = list(max_depth = max_depth, grid_probs = grid_probs,
                     select_statistic = select_statistic))
}


#' Re-rank DINA's qualifying family on the inferential effect measure
#'
#' Replaces DINA's native tau-hat winner with the candidate that maximises the
#' effect measure multiplier resampling (MR) de-biases (Cox HR for survival; the
#' resolved GLM effect otherwise), scored with MR's own per-candidate estimator
#' (`.fs_mr_pieces`) so the realized selection is the exact event MR
#' corrects.  Ranking honours the same `sg_focus` / `selection_rule` /
#' `effect_neighborhood` band logic as `dina_subgroup()`.  Returns `sg` with the
#' winner fields overwritten and a `sel_effect` (link-scale) column attached to
#' `sg$candidates`; if no candidate is scorable it returns `sg` unchanged.
#'
#' Selection is over the ADMITTED set, \eqn{\{g : \hat\beta(g) \ge t_g\}}
#' (manuscript Section 2.4).  DINA has no consistency screen, so
#' \eqn{t_g = c_{screen}}, supplied here as the resolved \code{admission}
#' object rather than re-derived -- the same object, from the same
#' \code{.fs_resolve_admission()} call, that MR re-selects over.  Ranking on
#' \eqn{\hat\beta} while admitting on DINA's native \eqn{\bar\tau} alone was
#' the misalignment: the identifier could select a candidate MR's competition
#' excluded, so the two linearized different selection events.
#'
#' @param admission Resolved admission set from \code{.fs_resolve_admission()}.
#'   \code{effect_floor} is on the comparison scale, which is the scale
#'   \code{sel_effect} is on, so no conversion is needed here.
#' @keywords internal
#' @noRd
.dina_reselect_on_effect <- function(sg, df, outcome_type, effect_measure,
                                     treat.name, outcome.name, event.name,
                                     offset.name, adjust_covariates,
                                     adverse_outcome, sg_focus,
                                     selection_rule, effect_neighborhood,
                                     admission = NULL) {
  tab <- sg$candidates
  if (is.null(tab) || !nrow(tab)) return(sg)

  # Effect measure / spec, mirroring the DINA MR branch: survival uses
  # "HR" on the log scale; GLM uses the resolved effect_measure.
  em   <- if (identical(outcome_type, "survival")) "HR" else effect_measure
  adv  <- if (identical(outcome_type, "survival")) TRUE else adverse_outcome
  spec <- .fs_mr_spec(outcome_type, em, treat.name, outcome.name, event.name,
                      offset.name, adjust_covariates, adverse_outcome = adv,
                      df = df)

  # Per-candidate effect on the SAME statistic MR uses (.fs_mr_pieces),
  # row-aligned to `tab`; skip rows with < 6 members exactly as MR does.
  nr        <- nrow(tab)
  eff_link  <- rep(NA_real_, nr)
  sz        <- rep(NA_integer_, nr)
  log_scale <- TRUE
  for (i in seq_len(nr)) {
    op1   <- if (identical(as.character(tab$d1[i]), "left")) "<=" else ">="
    comps <- list(data.frame(variable = as.character(tab$v1[i]), op = op1,
                             value = as.numeric(tab$c1[i]),
                             stringsAsFactors = FALSE))
    if (!is.na(tab$v2[i])) {
      op2 <- if (identical(as.character(tab$d2[i]), "left")) "<=" else ">="
      comps[[2L]] <- data.frame(variable = as.character(tab$v2[i]), op = op2,
                                value = as.numeric(tab$c2[i]),
                                stringsAsFactors = FALSE)
    }
    cj  <- do.call(rbind, comps)
    mem <- tryCatch(.fs_mr_members_from_conj(df, cj),
                    error = function(e) integer(0))
    if (length(mem) < 6L) next
    pc <- tryCatch(.fs_mr_pieces(df[mem, , drop = FALSE], spec),
                   error = function(e) NULL)
    if (is.null(pc) || !is.finite(pc$beta_hat)) next
    eff_link[i] <- pc$beta_hat
    sz[i]       <- length(mem)
    log_scale   <- isTRUE(pc$log_scale)
  }
  sg$candidates$sel_effect <- eff_link  # link scale; consumed by the MR branch

  scorable <- which(is.finite(eff_link) & !is.na(sz))
  if (!length(scorable)) return(sg)     # nothing scorable -> keep native winner

  # ADMISSION -- manuscript Section 2.4: rank among {g : beta-hat(g) >= t_g}.
  # Taken from the resolved admission set, NOT re-derived from hr.threshold
  # here: one resolution, carried, is the whole point of
  # .fs_resolve_admission().  effect_floor is on the comparison scale and so is
  # eff_link, so the comparison is direct.
  floor_cmp <- if (is.null(admission)) NULL else admission$effect_floor
  ok <- if (is.null(floor_cmp)) scorable
        else scorable[eff_link[scorable] >= floor_cmp]

  if (!length(ok)) {
    # The admitted set is EMPTY: no candidate clears the harm floor on the
    # inferential effect.  That is a selection outcome, not a failure, and the
    # native tau-hat winner must not stand in for it -- doing so would report a
    # subgroup chosen on a statistic the analysis does not report, which is the
    # misalignment the floor exists to remove.  found = FALSE routes into
    # .forestsearch_dina_select()'s unified no-subgroup contract.
    sg$found            <- FALSE
    sg$select_statistic <- "effect"
    sg$admitted_n       <- 0L
    return(sg)
  }
  sg$admitted_n <- length(ok)

  # Natural-scale effect for ordering / band (ratio families exponentiated; the
  # monotone transform leaves non-band foci unaffected).  Match dina_subgroup()'s
  # canonical sg_focus and its order() switch, with row index as a stable
  # insertion-order tiebreak.
  sgf <- .normalize_sg_focus(sg_focus)
  eff <- if (log_scale) exp(eff_link) else eff_link
  ord <- switch(
    sgf,
    maxSG   = ok[order(-sz[ok], -eff[ok], ok)],
    minSG   = ok[order( sz[ok], -eff[ok], ok)],
    hr      = ok[order(-eff[ok], ok)],
    hrMaxSG = {
      band <- .compute_inclusion_band(hr_vec = eff[ok], n_vec = sz[ok],
                                      selection_rule = selection_rule,
                                      effect_neighborhood = effect_neighborhood)
      ok[order(-band, -sz[ok], -eff[ok], ok)]
    },
    hrMinSG = {
      band <- .compute_inclusion_band(hr_vec = eff[ok], n_vec = sz[ok],
                                      selection_rule = selection_rule,
                                      effect_neighborhood = effect_neighborhood)
      ok[order(-band, sz[ok], -eff[ok], ok)]
    },
    ok[order(-eff[ok], ok)]             # fallback: plain effect argmax
  )
  w <- ord[1L]

  # Overwrite the winner fields from the winning candidate row, rebuild the AND
  # mask so the stored out_sg is internally consistent.  The caller builds
  # sg.harm / membership from sg$covariate/direction/threshold.
  win_v <- c(as.character(tab$v1[w]), as.character(tab$v2[w]))
  win_d <- c(as.character(tab$d1[w]), as.character(tab$d2[w]))
  win_c <- c(as.numeric(tab$c1[w]),  as.numeric(tab$c2[w]))
  keep  <- !is.na(win_v)
  sg$covariate  <- win_v[keep]
  sg$direction  <- win_d[keep]
  sg$threshold  <- win_c[keep]
  sg$depth      <- sum(keep)
  sg$n_subgroup <- sz[w]
  if ("tau_hat" %in% names(tab)) sg$mean_tau_hat <- as.numeric(tab$tau_hat[w])

  mask <- rep(TRUE, nrow(df))
  for (t in seq_len(sg$depth)) {
    x_t <- df[[sg$covariate[t]]]
    mask <- mask & (if (identical(sg$direction[t], "left"))
      x_t <= sg$threshold[t] else x_t >= sg$threshold[t])
  }
  sg$mask <- mask
  sg$select_statistic <- "effect"
  sg
}


#' Coerce candidate covariates to numeric for the DINA paths
#'
#' DINA fits a linear-in-covariates working model and therefore requires
#' numeric predictors: \code{dina()} rejects factor/character covariates.
#' \code{forestsearch()}'s GRF and consistency paths already coerce
#' all-numeric-level factors internally (\code{.build_grf_X()} and
#' \code{evaluate_comparison()} respectively); this helper supplies the same
#' coercion for every DINA entry point -- the \code{subgroup_method = "dina"}
#' selection path, the \code{use_dina} screening path, and
#' \code{dina_subgroup_bootstrap()} -- so all engines behave consistently.
#'
#' Coercion rule (a deliberate hybrid):
#' \itemize{
#'   \item Numeric columns are returned unchanged.
#'   \item Factor/character columns whose levels are all numeric strings
#'     (e.g. "0"/"1") are coerced with \code{as.numeric(as.character())},
#'     preserving the actual level values -- identical to the GRF and
#'     consistency paths.
#'   \item Genuinely categorical columns (non-numeric levels) are NOT
#'     silently integer-coded, which would mis-encode them as an ordered
#'     numeric predictor in the DINA linear model.  Instead the function
#'     stops with an actionable error naming them (callers where DINA is
#'     optional, such as \code{use_dina} screening, may catch this and
#'     degrade to no DINA contribution).
#' }
#'
#' \code{NULL} data (an optional df.predict/df.test) passes through unchanged.
#'
#' @param data A data frame, or \code{NULL}.
#' @param covariates Character vector of candidate covariate names.  Names not
#'   present in \code{data} are ignored.
#' @return \code{data} with any all-numeric-level factor/character covariate
#'   coerced to numeric (or \code{NULL} when \code{data} is \code{NULL}).
#' @noRd
.coerce_covariates_numeric <- function(data, covariates) {
  if (is.null(data)) return(NULL)
  present   <- intersect(covariates, names(data))
  offenders <- character(0)
  for (v in present) {
    col <- data[[v]]
    if (is.factor(col) || is.character(col)) {
      lvls <- if (is.factor(col)) levels(col) else unique(col)
      if (!anyNA(suppressWarnings(as.numeric(lvls)))) {
        # All-numeric levels: preserve the actual values (level "1" -> 1),
        # matching .build_grf_X() and evaluate_comparison().
        data[[v]] <- as.numeric(as.character(col))
      } else {
        offenders <- c(offenders, v)
      }
    }
  }
  if (length(offenders) > 0L) {
    stop(
      "DINA requires numeric candidate covariates, but the following are ",
      "categorical with non-numeric levels: ",
      paste(offenders, collapse = ", "), ".\n",
      "  DINA fits a linear-in-covariates working model, so categorical ",
      "predictors must be supplied as numeric dummy indicators (0/1) before ",
      "the call.  Factors whose levels are already numeric (e.g. \"0\"/\"1\") ",
      "are coerced automatically; genuinely categorical variables are not, ",
      "to avoid silently mis-encoding them as ordered integer codes.",
      call. = FALSE
    )
  }
  data
}


#' Orientation of DINA's tau-hat for the proposal floor
#'
#' DINA is fit on the raw outcome, so its tau-hat is on the outcome's own
#' scale.  The admission floor scores candidates with the effect estimator,
#' which flips the outcome when `adverse_outcome = FALSE`: `-Y` for continuous
#' and `1 - Y` for binary outcomes (`.consistency_glm_pieces()`,
#' `R/consistency_resample.R`).  Both flips negate the link-scale treatment
#' effect (identity and logit), so the proposal floor is applied to `-tau-hat`
#' for exactly those outcomes.  Survival, count, and `adverse_outcome = TRUE`
#' keep `1`.
#'
#' @param outcome_type Character outcome type.
#' @param adverse_outcome Logical, as resolved by `forestsearch()`.
#' @return `-1` or `1`.
#' @noRd
.dina_tau_sign <- function(outcome_type, adverse_outcome) {
  if (!isTRUE(adverse_outcome) &&
      outcome_type %in% c("continuous", "binary")) {
    -1
  } else {
    1
  }
}


#' Refuse DINA's harm floor for identity-scale estimands
#'
#' DINA scores candidates on the family LINK scale, so its admission floor
#' `m_diff` is derived as `log(hr.threshold)` for the ratio families
#' (cox / binomial / poisson) and as the identity threshold for `gaussian`.
#' There is no correct derivation for an identity-scale estimand on a
#' non-gaussian family: `effect_measure = "RD"` with a threshold of 0.07 would
#' yield a log-odds floor of `log(0.07) = -2.66`, which admits nearly every
#' candidate, silently.  The only honest answer is a refusal -- no RD- or
#' IRD-scale number exists that DINA could apply on the link scale.
#'
#' Called at BOTH derivation sites (`.forestsearch_dina_select()` here, and the
#' `use_dina` + `selected_only = TRUE` screening branch in
#' `forestsearch_main.R`), not at the `subgroup_method` dispatch, so every
#' route to the derivation is covered.
#'
#' Gaussian is untouched: `MD` on `family = "gaussian"` IS a correct
#' identity-scale floor, and the guard cannot fire there.
#'
#' @param family The resolved DINA family (`da$fit$family`).
#' @param effect_measure The resolved effect measure, or `NULL` on survival.
#' @return `invisible(TRUE)` when the derivation may proceed; otherwise stops.
#' @noRd
.dina_assert_ratio_estimand <- function(family, effect_measure) {
  if (!is.null(effect_measure) && length(effect_measure) == 1L &&
      !is.na(effect_measure) && effect_measure %in% c("RD", "IRD") &&
      !identical(family, "gaussian")) {
    stop(
      "subgroup_method = \"dina\" does not support identity-scale estimands ",
      "(RD, IRD):\n",
      "DINA's admission floor operates on the family link scale.  Use a ",
      "ratio estimand\n",
      "(e.g. effect_measure = \"OR\") with dina, or subgroup_method = ",
      "\"consistency\" or\n",
      "\"grf\" for ", effect_measure, ".",
      call. = FALSE
    )
  }
  invisible(TRUE)
}


#' DINA-selection mode for forestsearch (subgroup_method = "dina")
#'
#' Fits a DINA model and delegates subgroup selection to
#' \code{dina_subgroup()}, bypassing GRF/LASSO/consistency.  Returns the
#' selected subgroup as a forestsearch cut label plus the membership
#' (\code{treat.recommend}) tables the estimation/bootstrap machinery
#' consumes.  Selection criteria come from the enclosing forestsearch()
#' call; \code{dina_args} supplies only the DINA fit tuning.
#'
#' @return A list with \code{found}, \code{sg.harm} (label vector or NULL),
#'   \code{grp.consistency} (a consistency-shaped list), \code{dina_res},
#'   and \code{df.est}/\code{df.predict}/\code{df.test} carrying
#'   \code{treat.recommend} (0 = selected subgroup).
#' @noRd
.forestsearch_dina_select <- function(df, df.predict, df.test,
                                      confounders.name, outcome.name, event.name,
                                      treat.name, id.name, outcome_type,
                                      hr.threshold, n.min, sg_focus,
                                      selection_rule, effect_neighborhood,
                                      dina_args, dina_res, seedit, details,
                                      effect_measure = NULL, offset.name = NULL,
                                      adjust_covariates = NULL,
                                      adverse_outcome = TRUE,
                                      admission = NULL,
                                      effect.threshold = hr.threshold) {
  da <- .resolve_dina_args(dina_args, outcome_type,
                           n_min_default = n.min, seed_default = seedit)

  # Frontier keys are inert on this path: selection runs through
  # dina_subgroup(), and the only dina_frontier() call here is the details-time
  # display, which passes its own scope / n_min.  Say so once per fit, naming
  # every offending key -- never one warning per key.
  .dina_frontier_keys_supplied <- intersect(names(dina_args),
                                            .DINA_FRONTIER_KEYS)
  if (length(.dina_frontier_keys_supplied) > 0L) {
    warning(
      "`dina_args` frontier key(s) ",
      paste(shQuote(.dina_frontier_keys_supplied), collapse = ", "),
      " are ignored under `subgroup_method = \"dina\"`: this path selects ",
      "through dina_subgroup() and never calls dina_frontier() with them.  ",
      "They act only on the `use_dina` screening path.",
      call. = FALSE
    )
  }

  # DINA requires numeric covariates (dina() rejects factors/characters).
  # Coerce all-numeric-level factor/character candidates to numeric -- the
  # same coercion the GRF (.build_grf_X) and consistency (evaluate_comparison)
  # paths already apply -- so subgroup_method = "dina" is robust to 0/1
  # indicators stored as factors.  Genuinely categorical covariates raise a
  # clear error via .coerce_covariates_numeric() rather than the previous
  # silent no-detection.  Applied to all three frames so the returned
  # df.est / df.predict / df.test carry a consistent numeric encoding.
  df         <- .coerce_covariates_numeric(df, confounders.name)
  df.predict <- .coerce_covariates_numeric(df.predict, confounders.name)
  df.test    <- .coerce_covariates_numeric(df.test, confounders.name)

  # Harm floor on the link scale: log(hr.threshold) for ratio families
  # (cox/binomial/poisson), identity (mean difference) for gaussian.
  # Derived BEFORE the fit so the identity-scale refusal costs no model run.
  # The gaussian floor is the resolved threshold forestsearch() records and a
  # bootstrap / CV replay re-uses (effect.threshold), not the raw hr.threshold.
  .dina_assert_ratio_estimand(da$fit$family, effect_measure)
  m_diff <- if (identical(da$fit$family, "gaussian")) effect.threshold
            else log(hr.threshold)

  # Fit DINA unless a fit was supplied.
  if (is.null(dina_res)) {
    status_arg <- if (identical(da$fit$family, "cox")) event.name else NULL
    fit_call <- c(list(df = df, outcome = outcome.name, treatment = treat.name,
                       covariates = confounders.name, status = status_arg),
                  da$fit)
    dina_res <- do.call(dina, fit_call)
  }
  # ...applied to tau-hat in the orientation the admission floor uses: DINA is
  # fit on the raw outcome, while the admission scores candidates with the
  # effect estimator, which flips the outcome for these outcome types.
  tau_sign <- .dina_tau_sign(outcome_type, adverse_outcome)

  if (isTRUE(details)) {
    lines <- c(
      "",
      "[forestsearch] DINA selection (subgroup_method = \"dina\")",
      paste0("  Family:              ", da$fit$family),
      paste0("  sg_focus:            ", sg_focus),
      paste0("  selection_rule:      ", selection_rule),
      paste0("  effect_neighborhood: ", effect_neighborhood),
      paste0("  Harm floor:          ", sprintf("m_diff = %.4f", m_diff),
             if (!identical(da$fit$family, "gaussian"))
               sprintf("  (hr.threshold = %.4g)", hr.threshold) else "",
             if (tau_sign < 0)
               "  on -tau-hat (harm-oriented; adverse_outcome = FALSE)" else ""),
      paste0("  n.min:               ", n.min)
    )

    # DINA frontier: the per-covariate cuts DINA proposes.  A DISPLAY, shown
    # beside the family counts printed below -- it is not the family
    # dina_subgroup() searches, and nothing here selects.
    fr <- tryCatch(
      dina_frontier(fit = dina_res, df = df, covariates = confounders.name,
                    scope = "wide", n_min = n.min),
      error = function(e) {
        lines <<- c(lines, paste0("  (frontier unavailable: ",
                                  conditionMessage(e), ")"))
        NULL
      }
    )
    if (!is.null(fr) && nrow(fr) > 0L) {
      lines <- c(lines,
                 paste0("  DINA frontier -- proposed single cuts ",
                        "(per-covariate non-dominated); display only, ",
                        "not the searched family:"))
      fr_show <- fr[, intersect(c("covariate", "direction", "threshold",
                                  "n_subgroup", "effect", "cut_expr"),
                                names(fr)), drop = FALSE]
      lines <- c(lines,
                 paste0("    ",
                        utils::capture.output(print(fr_show, row.names = FALSE))))
    } else if (!is.null(fr)) {
      lines <- c(lines,
                 paste0("  DINA frontier -- proposed single cuts: none met ",
                        "the size constraint."))
    }
    # Single message() call: stderr is forwarded by doFuture workers, whereas
    # cat() (stdout) is captured by the future and never reaches the document.
    message(paste(lines, collapse = "\n"))
  }

  sg <- dina_subgroup(
    fit                 = dina_res,
    df                  = df,
    covariates          = confounders.name,
    m_diff              = m_diff,
    n_min               = n.min,
    max_depth           = da$select$max_depth,
    grid_probs          = da$select$grid_probs,
    sg_focus            = sg_focus,
    selection_rule      = selection_rule,
    effect_neighborhood = effect_neighborhood,
    tau_sign            = tau_sign
  )

  # Effect-based re-selection (dina_args$select_statistic = "effect"): re-rank
  # DINA's qualifying family on the inferential effect measure MR
  # de-biases, overriding the native tau-hat winner.  The default "dina" path
  # leaves `sg` untouched.  Any failure falls back to the native winner.
  if (identical(da$select$select_statistic, "effect") && isTRUE(sg$found) &&
      !is.null(sg$candidates) && nrow(sg$candidates) > 0L) {
    sg <- tryCatch(
      .dina_reselect_on_effect(
        sg = sg, df = df, outcome_type = outcome_type,
        effect_measure = effect_measure, treat.name = treat.name,
        outcome.name = outcome.name, event.name = event.name,
        offset.name = offset.name, adjust_covariates = adjust_covariates,
        adverse_outcome = adverse_outcome, sg_focus = sg_focus,
        selection_rule = selection_rule,
        effect_neighborhood = effect_neighborhood,
        admission = admission),
      error = function(e) sg)
  }

  if (isTRUE(details)) {
    lines2 <- c(
      paste0("  Candidates searched:  ",
             if (!is.null(sg$n_candidates_searched)) sg$n_candidates_searched else NA),
      paste0("  Candidates qualifying (>= floor, >= n.min): ",
             if (!is.null(sg$n_candidates_qualifying)) sg$n_candidates_qualifying else NA)
    )
    if (isTRUE(sg$found)) {
      op_d    <- ifelse(sg$direction == "left", "<=", ">=")
      sel_lbl <- paste(sprintf("{%s %s %s}", sg$covariate, op_d,
                               format(sg$threshold)),
                       collapse = " & ")
      lines2 <- c(lines2,
                  paste0("  SELECTED: ", sel_lbl,
                         sprintf("  (n = %d, mean tau-hat = %.4f)",
                                 sg$n_subgroup, sg$mean_tau_hat)))
    } else {
      lines2 <- c(lines2,
                  "  SELECTED: none -- no candidate met the harm floor and size constraint.")
    }
    message(paste(lines2, collapse = "\n"))
  }

  if (!isTRUE(sg$found)) {
    # Unified no-subgroup contract: df.est / df.predict / df.test = NULL, matching
    # the consistency path (forestsearch_main.R).  Downstream detection keys on
    # sg.harm (NULL here); returning a populated frame WITHOUT treat.recommend
    # was the DINA/GRF-only divergence that forced per-identifier consumer guards.
    return(list(found = FALSE, sg.harm = NULL, grp.consistency = NULL,
                dina_res = dina_res, df.est = NULL,
                df.predict = NULL, df.test = NULL))
  }

  # Cut label(s): direction "left" => {x <= q}, "right" => {x >= q}.  For a
  # depth-2 conjunction sg$covariate/direction/threshold are length-2, so
  # sg.harm becomes a two-element label vector that get_dfpred() AND-composes
  # -- the same representation a 2-factor consistency subgroup uses.
  op      <- ifelse(sg$direction == "left", "<=", ">=")
  sg.harm <- sprintf("{%s %s %s}", sg$covariate, op,
                     formatC(sg$threshold, format = "g", digits = 17, width = 1L))

  # Membership via the standard label evaluator (treat.recommend == 0 = harm).
  df.est         <- get_dfpred(df, sg.harm, version = 2)
  df.predict_out <- if (!is.null(df.predict)) get_dfpred(df.predict, sg.harm, version = 2) else NULL
  df.test_out    <- if (!is.null(df.test))    get_dfpred(df.test,    sg.harm, version = 2) else NULL

  id_vals <- if (id.name %in% names(df)) df[[id.name]]
             else if ("id" %in% names(df)) df[["id"]]
             else seq_len(nrow(df))
  df_flag <- data.frame(id = id_vals,
                        treat.recommend = df.est$treat.recommend)

  grp.consistency <- list(
    out_sg     = sg,
    sg.harm    = sg.harm,
    sg.harm.id = as.integer(df.est$treat.recommend == 0L),
    df_flag    = df_flag,
    algorithm  = "dina"
  )

  list(found = TRUE, sg.harm = sg.harm, grp.consistency = grp.consistency,
       dina_res = dina_res, df.est = df.est,
       df.predict = df.predict_out, df.test = df.test_out,
       candidates = sg$candidates,    # qualifying family for MR
       select_statistic = da$select$select_statistic)
}


#' Re-rank GRF's DR-candidate frontier on the inferential effect measure
#'
#' The GRF analogue of \code{.dina_reselect_on_effect()}, for
#' \code{grf_selection = "frontier"}.  Re-scores the DR-candidate family
#' (\code{grf_res$candidates}) on the effect measure multiplier resampling (MR)
#' de-biases (Cox HR for survival; the resolved GLM effect otherwise), using MR's
#' own per-candidate estimator (\code{.fs_mr_pieces}), then re-selects the winner
#' with GRF's own \code{.grf_frontier_select()} logic on those scores.  The
#' winning row is turned back into the standard
#' \code{sg_def} via \code{.grf_sg_def_from_candidate()}, so all downstream
#' membership/labelling is unchanged.  Attaches a \code{sel_effect} (link-scale)
#' column to \code{grf_res$candidates}; if no candidate is scorable it returns
#' \code{grf_res} unchanged.  Tree-mode selection has no enumerated family to
#' rank, so the caller applies this only in frontier mode.
#'
#' The harm floor is the resolved admission set's \code{effect_floor}
#' (manuscript Section 2.4: rank among \eqn{\{g : \hat\beta(g) \ge t_g\}}; GRF
#' has no consistency screen, so \eqn{t_g = c_{screen}}).  It was previously a
#' hard-coded \code{dmin = 1} -- the floor at the null -- so the identifier
#' admitted every candidate with HR >= 1 while MR admitted only those with
#' \eqn{\hat\beta \ge \log(\texttt{hr.threshold})}, and the two linearized
#' different selection events.  A side effect of the literal was that a
#' user-supplied \code{dmin.grf} was honoured on the native DR path and silently
#' ignored here.
#'
#' @param admission Resolved admission set from \code{.fs_resolve_admission()}.
#'   \code{effect_floor} is on the comparison scale;
#'   \code{.grf_frontier_select()} compares against the NATURAL-scale effect, so
#'   it is converted here using the same \code{log_scale} flag that produced
#'   that column -- the flag \code{.fs_mr_pieces()} returns, so the scale
#'   decision is not made twice.
#' @keywords internal
#' @noRd
.grf_reselect_on_effect <- function(grf_res, df, outcome_type, effect_measure,
                                    treat.name, outcome.name, event.name,
                                    offset.name, adjust_covariates,
                                    adverse_outcome, frontier_rule,
                                    effect_neighborhood,
                                    selection_rule = "neighborhood",
                                    admission = NULL) {
  cand <- grf_res$candidates
  if (is.null(cand) || !nrow(cand)) return(grf_res)

  em   <- if (identical(outcome_type, "survival")) "HR" else effect_measure
  adv  <- if (identical(outcome_type, "survival")) TRUE else adverse_outcome
  spec <- .fs_mr_spec(outcome_type, em, treat.name, outcome.name, event.name,
                      offset.name, adjust_covariates, adverse_outcome = adv,
                      df = df)

  # Per-candidate effect on the SAME statistic MR uses, with GRF-native
  # membership (sg_def -> .grf_evaluate_subgroup); skip < 6-member candidates.
  nr        <- nrow(cand)
  eff_link  <- rep(NA_real_, nr)
  log_scale <- TRUE
  for (i in seq_len(nr)) {
    sgd_i <- tryCatch(.grf_sg_def_from_candidate(cand[i, , drop = FALSE]),
                      error = function(e) NULL)
    if (is.null(sgd_i)) next
    mem <- tryCatch(which(.grf_evaluate_subgroup(sgd_i, df) == 0L),
                    error = function(e) integer(0))
    if (length(mem) < 6L) next
    pc <- tryCatch(.fs_mr_pieces(df[mem, , drop = FALSE], spec),
                   error = function(e) NULL)
    if (is.null(pc) || !is.finite(pc$beta_hat)) next
    eff_link[i] <- pc$beta_hat
    log_scale   <- isTRUE(pc$log_scale)
  }
  grf_res$candidates$sel_effect <- eff_link  # link scale; consumed by MR branch
  if (!any(is.finite(eff_link))) return(grf_res)  # nothing scorable -> keep native

  # Re-select via GRF's own frontier logic, scoring on the natural-scale effect.
  cand_hr <- grf_res$candidates
  cand_hr$effect <- if (log_scale) exp(eff_link) else eff_link
  cand_hr <- cand_hr[is.finite(cand_hr$effect), , drop = FALSE]

  # ADMISSION -- from the resolved admission set, not a literal.  cand_hr$effect
  # is natural scale and effect_floor is comparison scale, so convert with the
  # same log_scale flag that built the column.
  floor_cmp <- if (is.null(admission)) NULL else admission$effect_floor
  dmin_eff  <- if (is.null(floor_cmp)) {
    if (log_scale) 1 else 0       # no floor resolved: the null, as before
  } else if (log_scale) exp(floor_cmp) else floor_cmp

  win <- tryCatch(
    .grf_frontier_select(cand_hr, dmin = dmin_eff, rule = frontier_rule,
                         nbhd = effect_neighborhood,
                         selection_rule = selection_rule),
    error = function(e) NULL)
  if (is.null(win) || !nrow(win)) {
    # The admitted set is EMPTY: no candidate clears the harm floor on the
    # inferential effect.  Keeping the native DR-score winner here would report
    # a subgroup selected on a statistic the analysis does not report -- the
    # misalignment this floor removes -- so the selection returns nothing.
    # NULLing sg_def makes .forestsearch_grf_select()'s `found` FALSE, which
    # routes into the unified no-subgroup contract.
    grf_res$sg_def           <- NULL
    grf_res$select_statistic <- "effect"
    grf_res$admitted_n       <- 0L
    return(grf_res)
  }
  grf_res$admitted_n <- sum(cand_hr$effect >= dmin_eff, na.rm = TRUE)

  grf_res$sg_def <- .grf_sg_def_from_candidate(win)
  grf_res$select_statistic <- "effect"
  grf_res
}


#' GRF-selection mode for forestsearch (subgroup_method = "grf")
#'
#' Delegates subgroup *selection* to the GRF subgroup-identification routine
#' (\code{grf.subg.harm.survival()} for survival, \code{grf.subg.harm.glm()}
#' for GLM outcomes), bypassing the LASSO/DINA screening and the consistency
#' search.  This is the GRF analogue of \code{\link{.forestsearch_dina_select}}:
#' the policy-tree harm leaf is returned as a forestsearch cut-label vector
#' plus the membership (\code{treat.recommend}) tables that the
#' estimation/bootstrap machinery consumes.
#'
#' The GRF run is configured from the enclosing \code{forestsearch()} call's
#' existing GRF arguments (\code{frac.tau}, \code{dmin.grf}, \code{grf_depth},
#' \code{is.RCT}, \code{seedit}, and the GLM extras), built through the same
#' \code{.build_grf_survival_args()} / \code{.build_grf_glm_args()} helpers the
#' screening path uses, so a GRF-selection run is identical to the GRF screening
#' fit -- only the consumption differs.  \code{return_selected_cuts_only} is
#' forced to \code{TRUE} here: the selected harm leaf is the subgroup, so the
#' single root-to-leaf cut set (not the full per-depth cut pool) is what defines
#' it.
#'
#' GRF emits each split as a \code{"var <= value"} expression, and a depth-d
#' harm leaf is the AND-intersection of its d ancestor splits, so
#' \code{grf_res$sg.harm.id} is a length-d character vector that maps directly
#' onto a d-element forestsearch label vector (wrapped in braces for
#' \code{get_dfpred()}).  Membership is then re-derived from those labels via
#' \code{get_dfpred()}, exactly as the DINA path does, which makes it apply
#' cleanly to \code{df.predict}/\code{df.test} and is verified to reproduce
#' GRF's own tree-node assignment.
#'
#' @return A list with \code{found}, \code{sg.harm} (label vector or NULL),
#'   \code{grp.consistency} (a consistency-shaped list), \code{grf_res} (the
#'   raw GRF result object), and \code{df.est}/\code{df.predict}/\code{df.test}
#'   carrying \code{treat.recommend} (0 = selected subgroup).
#' @noRd
.forestsearch_grf_select <- function(df, df.predict, df.test,
                                     confounders.name, outcome.name,
                                     event.name, treat.name, id.name,
                                     outcome_type, n.min,
                                     frac.tau, dmin.grf, grf_depth, is.RCT,
                                     adverse_outcome = FALSE,
                                     offset.name = NULL,
                                     overdispersion = "none",
                                     grf_count_transform = "log",
                                     grf_res = NULL, seedit = 8316951L,
                                     grf_selection = "tree",
                                     frontier_rule = "effMaxSG",
                                     effect_neighborhood = 0.10,
                                     selection_rule = "neighborhood",
                                     details = FALSE,
                                     grf_select_statistic = "dr",
                                     effect_measure = NULL,
                                     adjust_covariates = NULL,
                                     admission = NULL) {

  # Fit GRF unless a fit was supplied.  Build args through the same helpers the
  # screening path uses so the GRF-selection fit cannot drift from GRF
  # screening.  return_selected_cuts_only = TRUE: the harm leaf IS the subgroup.
  if (is.null(grf_res)) {
    if (identical(outcome_type, "survival")) {
      surv_args <- .build_grf_survival_args(
        data                      = df,
        confounders.name          = confounders.name,
        outcome.name              = outcome.name,
        event.name                = event.name,
        id.name                   = id.name,
        treat.name                = treat.name,
        frac.tau                  = frac.tau,
        n.min                     = n.min,
        dmin.grf                  = dmin.grf,
        is.RCT                    = is.RCT,
        grf_depth                 = grf_depth,
        seedit                    = seedit,
        return_selected_cuts_only = TRUE,
        grf_selection             = grf_selection,
        frontier_rule             = frontier_rule,
        effect_neighborhood       = effect_neighborhood,
        selection_rule            = selection_rule
      )
      grf_res <- do.call(grf.subg.harm.survival, surv_args)
    } else {
      glm_args <- .build_grf_glm_args(
        data                      = df,
        confounders.name          = confounders.name,
        outcome.name              = outcome.name,
        treat.name                = treat.name,
        id.name                   = id.name,
        outcome_type              = outcome_type,
        n.min                     = n.min,
        dmin.grf                  = dmin.grf,
        is.RCT                    = is.RCT,
        grf_depth                 = grf_depth,
        seedit                    = seedit,
        return_selected_cuts_only = TRUE,
        adverse_outcome           = adverse_outcome,
        offset.name               = offset.name,
        overdispersion            = overdispersion,
        grf_count_transform       = grf_count_transform,
        grf_selection             = grf_selection,
        frontier_rule             = frontier_rule,
        effect_neighborhood       = effect_neighborhood,
        selection_rule            = selection_rule
      )
      grf_res <- do.call(grf.subg.harm.glm, glm_args)
    }
  }

  # Effect-based re-selection (grf_select_statistic = "effect"): re-rank GRF's
  # DR-candidate frontier on the inferential effect MR de-biases,
  # overriding the native DR-score winner.  Frontier-only: tree-mode selection
  # is the policy-tree leaf, which has no enumerated family to rank, so the leaf
  # stands.  Default "dr" leaves grf_res untouched.  Failures fall back to native.
  if (identical(grf_select_statistic, "effect") &&
      identical(grf_selection, "frontier") &&
      !is.null(grf_res) && !inherits(grf_res, "try-error") &&
      !is.null(grf_res$candidates) && nrow(grf_res$candidates) > 0L) {
    grf_res <- tryCatch(
      .grf_reselect_on_effect(
        grf_res = grf_res, df = df, outcome_type = outcome_type,
        effect_measure = effect_measure, treat.name = treat.name,
        outcome.name = outcome.name, event.name = event.name,
        offset.name = offset.name, adjust_covariates = adjust_covariates,
        adverse_outcome = adverse_outcome, frontier_rule = frontier_rule,
        effect_neighborhood = effect_neighborhood,
        selection_rule = selection_rule,
        admission = admission),
      error = function(e) grf_res)
  } else if (identical(grf_select_statistic, "effect") &&
             identical(grf_selection, "tree") && isTRUE(details)) {
    message("[forestsearch] grf_select_statistic = \"effect\" is ignored for ",
            "grf_selection = \"tree\" (the policy-tree leaf is the selection); ",
            "use grf_selection = \"frontier\" for effect-based re-ranking.")
  }

  # Structured, path-based subgroup definition (correct directions; a
  # disjunction of conjunctions when the GRF subgroup spans multiple leaves).
  # Built inside grf.subg.harm.* and returned as $sg_def.  Membership is
  # derived from this definition via .grf_evaluate_subgroup(), which reproduces
  # predict(tree, X) exactly and applies cleanly to df.predict / df.test.
  sg_def <- grf_res$sg_def
  found  <- !is.null(grf_res) && !inherits(grf_res, "try-error") &&
            !is.null(sg_def) && length(sg_def$conjunctions) > 0L

  if (isTRUE(details)) {
    lines <- c(
      "",
      "[forestsearch] GRF selection (subgroup_method = \"grf\")",
      paste0("  Outcome type:   ", outcome_type),
      paste0("  grf_depth:      ", grf_depth),
      paste0("  dmin.grf:       ", dmin.grf),
      paste0("  frac.tau:       ", frac.tau),
      paste0("  n.min:          ", n.min)
    )
    if (found) {
      lines <- c(lines,
                 paste0("  SELECTED (depth ",
                        if (!is.null(grf_res$selected_depth))
                          grf_res$selected_depth
                        else if (!is.null(grf_res$best_depth))
                          grf_res$best_depth else NA,
                        if (isTRUE(sg_def$is_disjunction))
                          ", union of leaves" else "",
                        "): ", sg_def$definition))
    } else {
      lines <- c(lines, "  SELECTED: none -- GRF identified no harm subgroup.")
    }
    message(paste(lines, collapse = "\n"))
  }

  if (!found) {
    # Unified no-subgroup contract: df.est / df.predict / df.test = NULL, matching
    # the consistency path (forestsearch_main.R).  Downstream detection keys on
    # sg.harm (NULL here); returning a populated frame WITHOUT treat.recommend
    # was the DINA/GRF-only divergence that forced per-identifier consumer guards.
    return(list(found = FALSE, sg.harm = NULL, grp.consistency = NULL,
                grf_res = grf_res, df.est = NULL,
                df.predict = NULL, df.test = NULL))
  }

  # sg.harm representation:
  #   * single conjunction -> brace-label vector ("{var op val}"), the same
  #     AND-composed representation a DINA/consistency subgroup uses;
  #   * union of leaves     -> a single disjunctive definition string
  #     "(a & b) | (c & d)", which get_dfpred() cannot evaluate, so membership
  #     for ALL cases is computed from the structured definition instead.
  sg.harm <- if (!is.null(sg_def$labels)) sg_def$labels else sg_def$definition

  # Membership from the structured definition (reproduces predict(tree, X);
  # valid on df / df.predict / df.test).
  tr_est  <- .grf_evaluate_subgroup(sg_def, df)
  # A missing value in a covariate of the definition can leave a subject with
  # no assignment (NA; e.g. a GLM GRF fit on complete cases, applied here to
  # every subject).  Say so once, naming the defining covariates; the
  # membership is returned as it is.
  if (anyNA(tr_est)) {
    sg_vars <- unique(unlist(lapply(sg_def$conjunctions,
                                    function(cj) as.character(cj$variable)),
                             use.names = FALSE))
    warning(sprintf(paste0("%d of %d subjects have no subgroup assignment ",
                           "(treat.recommend is NA): a covariate that defines ",
                           "the GRF-selected subgroup (%s) has missing values."),
                    sum(is.na(tr_est)), length(tr_est),
                    paste(sg_vars, collapse = ", ")),
            call. = FALSE)
  }
  df.est  <- df; df.est$treat.recommend <- tr_est
  df.predict_out <- if (!is.null(df.predict)) {
    o <- df.predict; o$treat.recommend <- .grf_evaluate_subgroup(sg_def, df.predict); o
  } else NULL
  df.test_out <- if (!is.null(df.test)) {
    o <- df.test; o$treat.recommend <- .grf_evaluate_subgroup(sg_def, df.test); o
  } else NULL

  id_vals <- if (id.name %in% names(df)) df[[id.name]]
             else if ("id" %in% names(df)) df[["id"]]
             else seq_len(nrow(df))
  df_flag <- data.frame(id = id_vals,
                        treat.recommend = df.est$treat.recommend)

  grp.consistency <- list(
    out_sg     = grf_res,
    sg.harm    = sg.harm,
    sg.harm.id = as.integer(df.est$treat.recommend == 0L),
    df_flag    = df_flag,
    algorithm  = "grf"
  )

  list(found = TRUE, sg.harm = sg.harm, grp.consistency = grp.consistency,
       grf_res = grf_res, df.est = df.est,
       df.predict = df.predict_out, df.test = df.test_out,
       candidates = grf_res$candidates,   # DR-candidate family for MR
       select_statistic = grf_select_statistic)
}


# =============================================================================
# Multiplier-resampling (MR) configuration validation
# =============================================================================

#' Validate an identifier configuration for multiplier resampling
#'
#' Multiplier resampling (MR) linearizes the selection event, so it is valid
#' only for identifier configurations that satisfy the two alignment
#' conditions:
#'
#' \enumerate{
#'   \item \strong{Selection ranks on the inferential coefficient.} The
#'     statistic the identifier maximizes must be the same within-subgroup
#'     effect \eqn{\hat\beta(g)} that is subsequently reported. DINA's native
#'     \eqn{\bar\tau}, GRF's mean doubly-robust score, and the GRF policy-tree
#'     objective all rank on something else.
#'   \item \strong{The candidate family is fixed.} The family enumerated on the
#'     observed data must not itself be a function of the data. For
#'     \code{subgroup_method = "consistency"} this is attained by disabling the
#'     model-based front ends (\code{use_lasso}, \code{use_grf},
#'     \code{use_dina}); it is checked here because it is trivially fixable.
#' }
#'
#' Condition 2 is deliberately \strong{not} checked for
#' \code{subgroup_method \%in\% c("dina", "grf")}. Those families regenerate
#' under resampling by construction, which is a property of the methods rather
#' than a configuration error, and erroring (or warning) would fire on every
#' DINA and GRF replicate.
#'
#' The three front-end flags are also \strong{not} checked on the DINA and GRF
#' paths, where they are inert: they are consumed downstream of those branches'
#' returns.
#'
#' Errors only -- never a warning, never a silent coercion. Each message names
#' the offending argument and the exact setting that resolves it.
#'
#' @param config Named list of resolved \code{forestsearch()} arguments -- in
#'   practice either \code{args_call_all} or an \code{mget()} of the relevant
#'   formals. Recognized names: \code{subgroup_method},
#'   \code{dina_select_statistic}, \code{grf_selection},
#'   \code{grf_select_statistic}, \code{use_lasso}, \code{use_grf},
#'   \code{use_dina}. Missing names are treated as absent rather than invalid,
#'   so a configuration that cannot fail a given check is not penalized for
#'   omitting the argument. Values may be unresolved \code{match.arg} vectors;
#'   the first element is taken, matching \code{match.arg()}.
#' @param context Character scalar naming the call site that requires MR
#'   alignment, e.g. \code{"forestsearch(mr_inference = TRUE)"}. Prefixed to
#'   the error message so the user can see which entry point objected.
#'
#' @return Invisibly \code{TRUE} if the configuration is valid; otherwise
#'   \code{stop()}s.
#' @noRd
.validate_mr_configuration <- function(config, context = "mr_inference = TRUE") {

  .first <- function(nm, default = NULL) {
    v <- config[[nm]]
    if (is.null(v) || length(v) == 0L) return(default)
    v[[1L]]
  }

  method <- .first("subgroup_method")
  if (is.null(method) || is.na(method)) return(invisible(TRUE))
  method <- as.character(method)

  fail <- function(msg) {
    stop(sprintf("%s requires an identifier aligned with the reported effect.\n  %s",
                 context, msg), call. = FALSE)
  }

  # ---------------------------------------------------------------------------
  # Condition 1: selection must rank on the inferential coefficient
  # ---------------------------------------------------------------------------
  if (identical(method, "dina")) {
    if (identical(as.character(.first("dina_select_statistic", "effect")), "dina")) {
      fail(paste0(
        "dina_select_statistic = \"dina\" ranks the qualifying family on DINA's ",
        "native subgroup-mean tau-hat, not on the effect the analysis reports.\n",
        "  Set dina_select_statistic = \"effect\", or run without MR ",
        "(mr_inference = FALSE)."))
    }
  }

  if (identical(method, "grf")) {
    if (identical(as.character(.first("grf_selection", "frontier")), "tree")) {
      fail(paste0(
        "grf_selection = \"tree\" selects by the policy-tree objective and ",
        "enumerates no candidate family to rank on the reported effect; the ",
        "misalignment is structural, not a tuning choice.\n",
        "  Set grf_selection = \"frontier\", or run without MR ",
        "(mr_inference = FALSE)."))
    }
    if (identical(as.character(.first("grf_select_statistic", "effect")), "dr")) {
      fail(paste0(
        "grf_select_statistic = \"dr\" ranks the frontier on GRF's native mean ",
        "doubly-robust score, not on the effect the analysis reports.\n",
        "  Set grf_select_statistic = \"effect\", or run without MR ",
        "(mr_inference = FALSE)."))
    }
  }

  # ---------------------------------------------------------------------------
  # Condition 2: fixed candidate family (consistency / FS only)
  # ---------------------------------------------------------------------------
  if (identical(method, "consistency")) {
    front_ends <- c(use_lasso = isTRUE(.first("use_lasso", FALSE)),
                    use_grf   = isTRUE(.first("use_grf",   FALSE)),
                    use_dina  = isTRUE(.first("use_dina",  FALSE)))
    on <- names(front_ends)[front_ends]
    if (length(on)) {
      fail(sprintf(paste0(
        "The model-based front end%s %s set TRUE, so the candidate family is ",
        "estimated from the same data the search runs on and is not fixed.\n",
        "  Set %s and re-run."),
        if (length(on) > 1L) "s" else "",
        paste(paste(on, collapse = " and "),
              if (length(on) > 1L) "are" else "is"),
        paste(sprintf("%s = FALSE", on), collapse = ", ")))
    }
  }

  invisible(TRUE)
}


#' Classify the candidate-family status of a forestsearch configuration
#'
#' Records, as a machine-readable field on the returned object, whether the
#' candidate family the identifier ranked over is fixed:
#'
#' \describe{
#'   \item{\code{"no-front-end"}}{\code{subgroup_method = "consistency"} with
#'     all three model-based front ends off, so no fitted model shapes the
#'     family on the observed data.  Deliberately NOT called "fixed": the
#'     manuscript's Section 2.1 fixed family additionally requires the cut
#'     locations to be resample-invariant, which quantile-derived cuts
#'     (\code{cut_type = "default"}) are not.  This level reports the weaker,
#'     checkable property.}
#'   \item{\code{"conditional-removable"}}{\code{subgroup_method =
#'     "consistency"} with at least one of \code{use_lasso}, \code{use_grf},
#'     \code{use_dina} on. The family is data-dependent, but becomes fixed by
#'     turning those flags off.}
#'   \item{\code{"conditional-inherent"}}{\code{subgroup_method} of
#'     \code{"dina"} or \code{"grf"}. The family is generated by fitting a
#'     model to the same data, which is intrinsic to the method and cannot be
#'     switched off.}
#' }
#'
#' Purely descriptive: it never raises a condition, so a sweep can tabulate it
#' across configurations without any message volume. Enforcement lives in
#' \code{.validate_mr_configuration()}.
#'
#' @param config Named list of resolved \code{forestsearch()} arguments
#'   (typically \code{args_call_all}).
#' @return Character scalar, one of \code{"no-front-end"},
#'   \code{"conditional-removable"}, \code{"conditional-inherent"}.
#' @noRd
.fs_family_status <- function(config) {
  .first <- function(nm, default = NULL) {
    v <- config[[nm]]
    if (is.null(v) || length(v) == 0L) return(default)
    v[[1L]]
  }
  method <- as.character(.first("subgroup_method", "consistency"))
  if (!identical(method, "consistency")) return("conditional-inherent")
  any_front_end <- isTRUE(.first("use_lasso", FALSE)) ||
                   isTRUE(.first("use_grf",   FALSE)) ||
                   isTRUE(.first("use_dina",  FALSE))
  if (any_front_end) "conditional-removable" else "no-front-end"
}


# =============================================================================
# sg_focus dispatch completeness
# =============================================================================

#' Canonical sg_focus values (post-normalization)
#'
#' The single source of truth for which selection foci exist, after
#' \code{.normalize_sg_focus()} has folded the GLM-natural aliases
#' (\code{"eff"}, \code{"effMaxSG"}, \code{"effMinSG"}, \code{"maxcons"}) onto
#' their canonical spellings.
#'
#' Every entry here must have an explicit branch at each focus dispatch site.
#' Historically this vector was duplicated as a literal in \code{forestsearch()}
#' and \code{dina_subgroup()}, and the two drifted: \code{"maxeff"} and
#' \code{"maxeffCons"} were whitelisted by \code{forestsearch()} but had no
#' branch in the GRF frontier rule map, so they fell through to the
#' \code{"effMaxSG"} default silently, and \code{dina_subgroup()} rejected them
#' outright. \code{.assert_sg_focus_dispatch_complete()} exists to make that
#' class of drift impossible.
#'
#' @noRd
.FS_SG_FOCUS_CANONICAL <- c("hr", "hrMaxSG", "maxSG", "hrMinSG", "minSG",
                            "maxeff", "maxeffCons")


#' Extract the branch names of a \code{switch()} assigned to a given variable
#'
#' Walks a function's body looking for \code{<var> <- switch(...)} and returns
#' the names of that call's branches. Used by
#' \code{.assert_sg_focus_dispatch_complete()} so the check reads the dispatch
#' sites themselves rather than a hand-maintained copy of what they support --
#' a copy would be one more thing to drift.
#'
#' @param fn Function to inspect.
#' @param target_var Character scalar; the assignment target.
#' @return Character vector of branch names (possibly empty).
#' @noRd
.find_switch_branches <- function(fn, target_var) {
  found <- character(0)
  walk <- function(e) {
    if (!is.call(e)) return(invisible(NULL))
    if (length(e) == 3L &&
        is.symbol(e[[1L]]) &&
        as.character(e[[1L]]) %in% c("<-", "=", "<<-") &&
        is.symbol(e[[2L]]) &&
        identical(as.character(e[[2L]]), target_var) &&
        is.call(e[[3L]]) && is.symbol(e[[3L]][[1L]]) &&
        identical(as.character(e[[3L]][[1L]]), "switch")) {
      nm <- names(e[[3L]])
      if (!is.null(nm)) found <<- c(found, nm[nzchar(nm)])
    }
    # Recurse element-wise.  A call can hold the empty symbol (e.g. the blank
    # index in `x[, 1]`); forcing it raises "argument is missing", so each
    # descent is guarded rather than pre-tested -- testing would have to force
    # it too.
    for (i in seq_along(e)) tryCatch(walk(e[[i]]), error = function(err) NULL)
    invisible(NULL)
  }
  walk(body(fn))
  unique(found)
}


#' Assert that every canonical sg_focus has a branch at every dispatch site
#'
#' Five sites decide behaviour from \code{sg_focus} after normalization:
#'
#' \enumerate{
#'   \item \code{forestsearch()}'s GRF \code{frontier_rule} map;
#'   \item \code{dina_subgroup()}'s ordering-key map (\code{ord});
#'   \item \code{.dina_reselect_on_effect()}'s ordering-key map (\code{ord}),
#'     which is \strong{deliberately incomplete} -- see below;
#'   \item \code{dina_subgroup()}'s whitelist, and
#'   \item \code{subgroup.consistency()}'s whitelist, both of which must be
#'     assigned from \code{.FS_SG_FOCUS_CANONICAL} rather than re-inlined as a
#'     literal.
#' }
#'
#' A focus added to a whitelist without branches at the ordering maps does not
#' error -- it falls through to a default and silently selects under a rule
#' the caller did not ask for. This assertion is what turns that into a
#' failure. It is a developer-facing check with no runtime cost on any
#' analysis path; it is exercised by the test suite.
#'
#' Site (3) is the exception and is checked for an exact shape rather than for
#' completeness. DINA has no consistency screen, so \code{"maxeff"} and
#' \code{"maxeffCons"} name the same rule there and both must fall through to
#' the effect-argmax fallback; \code{selection_criteria.qmd} (\code{@sec-vocab})
#' documents that synonymy. The assertion therefore requires the five gated
#' foci to be present \emph{and} the two ungated ones to be absent, so that
#' adding a branch for either is caught as the documentation contradiction it
#' would be.
#'
#' Previously this read only sites (1), (2) and (4). A check that appears to
#' cover five sites and covers three is worse than one that covers three and
#' says so.
#'
#' @return Invisibly \code{TRUE}; otherwise \code{stop()}s naming the site and
#'   the missing values.
#' @noRd
.assert_sg_focus_dispatch_complete <- function() {
  canonical <- .FS_SG_FOCUS_CANONICAL
  problems  <- character(0)

  sites <- list(
    "forestsearch(): GRF frontier_rule map" =
      .find_switch_branches(forestsearch, "frontier_rule"),
    "dina_subgroup(): ordering-key map (ord)" =
      .find_switch_branches(dina_subgroup, "ord")
  )
  for (nm in names(sites)) {
    missing <- setdiff(canonical, sites[[nm]])
    if (length(missing)) {
      problems <- c(problems, sprintf(
        "  %s\n    no branch for: %s",
        nm, paste(sprintf("\"%s\"", missing), collapse = ", ")))
    }
  }

  # Site: .dina_reselect_on_effect()'s ordering map.
  #
  # THIS SITE IS DELIBERATELY INCOMPLETE and the assert must not demand
  # otherwise.  DINA has no consistency screen, so "maxeff" and "maxeffCons"
  # name the same rule there and both fall through the switch() to its plain
  # effect-argmax fallback.  quarto/methodology/selection_criteria.qmd
  # (@sec-vocab) documents that synonymy and validates it.  Adding branches for
  # the two would break the documented behaviour, so what is checked is the
  # exact shape: the five gated foci present, the two ungated ones ABSENT.
  dre_branches <- .find_switch_branches(.dina_reselect_on_effect, "ord")
  dre_expected <- setdiff(canonical, c("maxeff", "maxeffCons"))
  dre_missing  <- setdiff(dre_expected, dre_branches)
  if (length(dre_missing)) {
    problems <- c(problems, sprintf(
      "  .dina_reselect_on_effect(): ordering-key map (ord)\n    no branch for: %s",
      paste(sprintf("\"%s\"", dre_missing), collapse = ", ")))
  }
  dre_unexpected <- intersect(c("maxeff", "maxeffCons"), dre_branches)
  if (length(dre_unexpected)) {
    problems <- c(problems, paste0(
      "  .dina_reselect_on_effect(): ordering-key map (ord)\n",
      sprintf("    unexpected branch for: %s\n",
              paste(sprintf("\"%s\"", dre_unexpected), collapse = ", ")),
      "    These must fall through to the effect-argmax fallback: DINA has no\n",
      "    consistency screen, so the two are synonyms there.  A branch here\n",
      "    contradicts selection_criteria.qmd (@sec-vocab)."))
  }

  # Whitelist sites: `valid_sg_focus` must be ASSIGNED FROM the shared
  # constant.  A re-inlined literal would compile and pass every functional
  # test while reintroducing exactly the drift this guard exists to prevent.
  .assigns_constant <- function(fn_body) {
    ok <- FALSE
    walk <- function(e) {
      if (!is.call(e)) return(invisible(NULL))
      if (length(e) == 3L && is.symbol(e[[1L]]) &&
          as.character(e[[1L]]) %in% c("<-", "=") &&
          is.symbol(e[[2L]]) &&
          identical(as.character(e[[2L]]), "valid_sg_focus") &&
          is.symbol(e[[3L]]) &&
          identical(as.character(e[[3L]]), ".FS_SG_FOCUS_CANONICAL")) ok <<- TRUE
      # Guarded descent -- see the note in .find_switch_branches().
      for (i in seq_along(e)) tryCatch(walk(e[[i]]), error = function(err) NULL)
      invisible(NULL)
    }
    walk(fn_body)
    ok
  }

  whitelists <- list(
    "dina_subgroup(): whitelist"        = body(dina_subgroup),
    "subgroup.consistency(): whitelist" = body(subgroup.consistency),
    # Added after this site was found holding a five-element literal subset:
    # `maxeff` / `maxeffCons` were accepted by the two above and rejected
    # here, so a DINA bootstrap under either focus stopped at the check.
    "dina_subgroup_bootstrap(): whitelist" =
      body(dina_subgroup_bootstrap))
  for (nm in names(whitelists)) {
    if (!.assigns_constant(whitelists[[nm]])) {
      problems <- c(problems, sprintf(paste0(
        "  %s\n",
        "    `valid_sg_focus` is not assigned from .FS_SG_FOCUS_CANONICAL; a\n",
        "    re-inlined literal can drift from the canonical set."), nm))
    }
  }

  if (length(problems)) {
    stop("sg_focus dispatch is incomplete.\n",
         paste(problems, collapse = "\n"),
         "\n\n  Every value in .FS_SG_FOCUS_CANONICAL must have an explicit\n",
         "  branch at every dispatch site.  Without one it falls through to a\n",
         "  default and selects under a rule the caller did not request, with\n",
         "  no condition raised.",
         call. = FALSE)
  }
  invisible(TRUE)
}


# =============================================================================
# MR admission set
# =============================================================================

#' Which admission floors apply, as a structural fact
#'
#' The presence pattern is a function of \code{(sg_focus, subgroup_method)}
#' alone -- it does not depend on any threshold value. Kept separate from
#' \code{.fs_resolve_admission()} so the identifier's own floor-disabling sites
#' can read the same decision without needing resolved numerics, which are not
#' available at the point in \code{forestsearch()} where those overrides are
#' applied.
#'
#' @param sg_focus Selection focus (any spelling; normalized here).
#' @param subgroup_method One of \code{"consistency"}, \code{"dina"},
#'   \code{"grf"}.
#' @return Named logical vector \code{c(effect = , consistency = )}.
#' @noRd
.fs_admission_applies <- function(sg_focus, subgroup_method = "consistency") {
  sgf <- tryCatch(.normalize_sg_focus(sg_focus), error = function(e) sg_focus)
  method <- as.character(subgroup_method)[1L]

  # sg_focus = "maxeff" on the consistency engine is Guo and He's argmax
  # primitive: the effect maximiser over the enumerated family subject to NO
  # auxiliary selection condition.  The identifier disables both floors, so MR
  # must admit the whole family too.
  if (identical(method, "consistency") && identical(as.character(sgf), "maxeff")) {
    return(c(effect = FALSE, consistency = FALSE))
  }
  # DINA and GRF have no consistency screen -- neither computes Pcons, and no
  # DINA or GRF sort key contains one -- so no consistency term may enter their
  # admission set.  They do apply an effect (harm) floor.
  if (method %in% c("dina", "grf")) {
    return(c(effect = TRUE, consistency = FALSE))
  }
  c(effect = TRUE, consistency = TRUE)
}


#' Resolve the admission set once, for the identifier and MR alike
#'
#' Multiplier resampling is a linearization of the identifier's selection
#' \emph{map}, which is a ranking \strong{and} a domain. MR is therefore valid
#' only if the set it re-selects over is the set the identifier selected over.
#' Previously MR reconstructed that domain from raw parameters at its own call
#' site (\code{t_g <- pmax(c_screen, c_consistency + z * sigma_D)}), which is
#' the defect this function exists to remove: the identifier decided its floors
#' in one place and MR re-derived them in another, and the two drifted.
#'
#' \code{sg_focus = "maxeff"} is where the drift showed up -- the identifier
#' disables both floors while MR kept applying the effect floor -- but nothing
#' about that was specific to \code{maxeff}. Any future focus could diverge the
#' same way. Resolving admission once and carrying the result to MR makes the
#' two equal by construction rather than by coincidence.
#'
#' Absence is represented as \code{NULL}, never as \code{-Inf} or any other
#' sentinel: a floor that does not apply is not a floor set very low, and
#' arithmetic through a sentinel is exactly how a "no filter" case comes to be
#' silently filtered.
#'
#' Expected resolutions:
#' \tabular{lll}{
#'   \strong{method} \tab \strong{focus} \tab \strong{result} \cr
#'   consistency \tab maxeff \tab both \code{NULL} \cr
#'   consistency \tab any other \tab both present \cr
#'   dina, grf \tab any \tab effect floor only \cr
#' }
#'
#' @param sg_focus Selection focus (any spelling; normalized internally).
#' @param subgroup_method One of \code{"consistency"}, \code{"dina"},
#'   \code{"grf"}.
#' @param hr.threshold Screening threshold \strong{on the comparison scale}
#'   (log for ratio measures, identity for differences) -- i.e. the caller has
#'   already applied \code{log()} where appropriate. Ignored when no effect
#'   floor applies.
#' @param hr.consistency Consistency threshold on the comparison scale.
#'   Ignored when no consistency floor applies.
#' @param pconsistency.threshold Consistency-rate cutoff. Ignored when no
#'   consistency floor applies.
#' @return List with \code{effect_floor} (numeric scalar or \code{NULL}) and
#'   \code{consistency} (list with \code{c_cons} and \code{p_star}, or
#'   \code{NULL}).
#' @noRd
.fs_resolve_admission <- function(sg_focus, subgroup_method = "consistency",
                                  hr.threshold = NULL, hr.consistency = NULL,
                                  pconsistency.threshold = NULL) {
  applies <- .fs_admission_applies(sg_focus, subgroup_method)

  effect_floor <- NULL
  if (isTRUE(unname(applies[["effect"]]))) {
    if (is.null(hr.threshold) || !is.finite(hr.threshold)) {
      stop("An effect floor applies to sg_focus = '", sg_focus, "' under ",
           "subgroup_method = '", subgroup_method, "', but hr.threshold is ",
           "not a finite value.", call. = FALSE)
    }
    effect_floor <- as.numeric(hr.threshold)
  }

  consistency <- NULL
  if (isTRUE(unname(applies[["consistency"]]))) {
    if (is.null(hr.consistency) || !is.finite(hr.consistency) ||
        is.null(pconsistency.threshold) || !is.finite(pconsistency.threshold)) {
      stop("A consistency floor applies to sg_focus = '", sg_focus, "' under ",
           "subgroup_method = '", subgroup_method, "', but hr.consistency / ",
           "pconsistency.threshold are not finite values.", call. = FALSE)
    }
    consistency <- list(c_cons = as.numeric(hr.consistency),
                        p_star = as.numeric(pconsistency.threshold))
  }

  list(effect_floor = effect_floor, consistency = consistency)
}


#' Describe a resolved admission set in one line
#'
#' Used by \code{print()}/\code{summary()} so a run's admission set is
#' auditable rather than inferable from the focus and method.
#' @noRd
.fs_format_admission <- function(admission) {
  # NULL in, NULL out: summary()'s .print_param() skips NULL, so an object
  # predating this field prints nothing rather than "admission set: NA".
  if (is.null(admission)) return(NULL)
  has_e <- !is.null(admission$effect_floor)
  has_c <- !is.null(admission$consistency)
  if (!has_e && !has_c) return("unrestricted (no effect floor, no consistency floor)")
  parts <- character(0)
  if (has_e) parts <- c(parts, sprintf("effect floor %.4g", admission$effect_floor))
  if (has_c) parts <- c(parts, sprintf("consistency floor %.4g at p* = %.3g",
                                       admission$consistency$c_cons,
                                       admission$consistency$p_star))
  paste(parts, collapse = "; ")
}


#' Assert that every (focus, engine) pair resolves to the intended admission
#'
#' Companion to \code{.assert_sg_focus_dispatch_complete()}. That one checks
#' every canonical focus has a \emph{dispatch branch}; this one checks every
#' \code{(focus, subgroup_method)} pair resolves to the admission set the
#' identifier actually applies. A focus can have branches everywhere and still
#' be given the wrong domain, which is the failure this fix removes.
#'
#' The expected pattern is a property of the engines, not of any focus:
#' \itemize{
#'   \item \code{consistency} + \code{maxeff} -- neither floor. The identifier
#'     applies no auxiliary selection condition (Guo and He's argmax
#'     primitive), so MR must re-select over the whole family.
#'   \item \code{consistency} + any other focus -- both floors.
#'   \item \code{dina}, \code{grf} -- effect floor only. Neither engine has a
#'     consistency screen, so no consistency term may enter their admission
#'     set.
#' }
#'
#' @return Invisibly \code{TRUE}; otherwise \code{stop()}s.
#' @noRd
.assert_admission_resolution_complete <- function() {
  foci    <- .FS_SG_FOCUS_CANONICAL
  engines <- c("consistency", "dina", "grf")
  bad <- character(0)

  for (m in engines) for (f in foci) {
    want_effect <- !(identical(m, "consistency") && identical(f, "maxeff"))
    want_cons   <- identical(m, "consistency") && !identical(f, "maxeff")

    a <- tryCatch(
      .fs_resolve_admission(f, m, hr.threshold = 0.25,
                            hr.consistency = 0, pconsistency.threshold = 0.9),
      error = function(e) e)
    if (inherits(a, "error")) {
      bad <- c(bad, sprintf("  %s / %s: resolver errored: %s",
                            m, f, conditionMessage(a)))
      next
    }
    got_effect <- !is.null(a$effect_floor)
    got_cons   <- !is.null(a$consistency)
    if (!identical(got_effect, want_effect) || !identical(got_cons, want_cons)) {
      bad <- c(bad, sprintf(
        "  %s / %s: got (effect=%s, consistency=%s), expected (effect=%s, consistency=%s)",
        m, f, got_effect, got_cons, want_effect, want_cons))
    }
    # Absence must be absence, never a permissive sentinel.
    if (!got_effect && !is.null(a$effect_floor)) {
      bad <- c(bad, sprintf("  %s / %s: effect_floor is not NULL when absent", m, f))
    }
    if (got_effect && !is.finite(a$effect_floor)) {
      bad <- c(bad, sprintf(
        "  %s / %s: effect_floor is %s -- a sentinel, not a floor",
        m, f, format(a$effect_floor)))
    }
  }

  # The identifier's own floor sites must agree with the resolver.
  for (m in engines) for (f in foci) {
    ap <- .fs_admission_applies(f, m)
    a  <- .fs_resolve_admission(f, m, hr.threshold = 0.25,
                                hr.consistency = 0, pconsistency.threshold = 0.9)
    if (!identical(unname(ap[["effect"]]), !is.null(a$effect_floor)) ||
        !identical(unname(ap[["consistency"]]), !is.null(a$consistency))) {
      bad <- c(bad, sprintf(
        "  %s / %s: .fs_admission_applies() disagrees with .fs_resolve_admission()",
        m, f))
    }
  }

  if (length(bad)) {
    stop("Admission resolution is wrong for ", length(bad), " case(s):\n",
         paste(bad, collapse = "\n"),
         "\n\n  MR re-selects over the admission set; if it differs from the\n",
         "  identifier's, MR corrects a selection event that did not occur.",
         call. = FALSE)
  }
  invisible(TRUE)
}

Try the forestsearch package in your browser

Any scripts or data that you put into this service are public.

forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.