DecisionPoint: Construct a DecisionPoint specification
In fluxCore: Probabilistic Simulation of Single-Entity Systems in Irregular Time

DecisionPoint

R Documentation

Construct a DecisionPoint specification

Description

Declares a point in the simulation where a policy may be consulted. Decision points are declared in the Schema (schema$decision_points), not inferred at runtime.

Usage

DecisionPoint(
  id,
  trigger,
  allowed_actions = NULL,
  action_handlers = NULL,
  condition = NULL,
  audit = FALSE,
  observation_fn = NULL,
  label = NULL,
  on_pending_action = c("warn", "replace", "keep", "error")
)

Arguments

`id`	Character scalar; unique identifier (e.g., `"post_dropoff"`).
`trigger`	Character vector of event types and/or a predicate function `⁠function(event)⁠` that returns `TRUE` when the decision point fires. Evaluated pre-transition on the raw event object; entity state is not yet updated at this point. An explicitly supplied `NULL` declares a group-only leaf that cannot fire directly and must be referenced by a `GroupedDecisionPoint()` in the full schema. Omitting `trigger` is an error.
`allowed_actions`	Optional character vector of named action types. If `NULL`, the policy is unconstrained.
`action_handlers`	Optional named list of functions, keyed by action type. Each function has signature `⁠function(entity, event)⁠` (with optional `param_ctx`) and returns a named list of state updates, or `NULL` for no change. When present, the engine calls the matching handler directly when an ActionEvent of that type fires — bypassing `bundle$transition()`. Names must be a subset of `allowed_actions`.
`condition`	Optional function `⁠function(entity)⁠` evaluated post-transition on the updated entity. If it returns `FALSE`, the policy is not consulted for this event cycle. Use `condition` to gate on entity state (e.g., `function(entity) entity$current$battery_pct < 25`). When `NULL` (default), the policy is always consulted when `trigger` fires.
`audit`	Logical scalar (default `FALSE`). When `TRUE`, a `TrajectoryRecord` with `condition_met = FALSE` is emitted even for cycles where `condition` vetoed the policy call. Useful for auditing why a decision point did not fire.
`observation_fn`	Optional function `⁠function(entity)⁠` that computes the observable state presented to the policy. Defaults to a full entity snapshot when `NULL`.
`label`	Optional human-readable description.
`on_pending_action`	What to do when the policy proposes an action at this decision point while a previously proposed action from the same decision point is still waiting to be realized. A decision point holds at most one pending action at a time. `"warn"` (default) – replace the pending action and emit a warning. `"replace"` – replace the pending action silently. Use this to state explicitly that superseding is the intended behavior, as for a decision point whose job is to reschedule something. `"keep"` – keep the pending action and discard the new proposal. `"error"` – stop with an error.