TrajectoryRecord: Construct a TrajectoryRecord

In fluxCore: Probabilistic Simulation of Single-Entity Systems in Irregular Time

Construct a TrajectoryRecord

Description

Engine-owned audit record emitted at each decision point when a TrajectoryLogger is configured. This is the canonical surface for policy evaluation, audit, and RL reward computation.

Usage

TrajectoryRecord(
  run_id,
  entity_id,
  t,
  decision_point_id,
  observation,
  realized_event,
  candidate_actions = NULL,
  proposed_actions = NULL,
  selected_action = NULL,
  state_before = NULL,
  state_after = NULL,
  condition_met = NULL,
  reward = NULL,
  grouped_decision_point_id = NULL,
  group_activation_id = NULL,
  decision_plan_metadata = NULL
)

Arguments

run_id	Character scalar; run identifier (from SimContext).
entity_id	Character scalar; entity identifier.
t	Numeric scalar; time at which the decision point fired.
decision_point_id	Character scalar; which decision point produced this record.
observation	Named list; output of the decision point's observation_fn.
realized_event	The event record that triggered the decision point.
candidate_actions	Optional character vector of actions presented to the policy.
proposed_actions	Optional list of actions proposed by the policy.
selected_action	Optional ActionEvent; the action selected by the policy for this decision, recorded before pending-action resolution. It does not by itself establish that the action was retained or realized.
state_before	Optional named list; entity state before the event. NULL unless the TrajectoryLogger is configured to capture it.
state_after	Optional named list; entity state after the transition. NULL unless the TrajectoryLogger is configured to capture it.
condition_met	Logical scalar or NULL; whether the condition predicate was satisfied. TRUE when condition passed or was absent, FALSE for audit records emitted when condition vetoed the policy call.
reward	Optional numeric or named list; reward signal(s).
grouped_decision_point_id	Optional non-empty character scalar naming the grouped decision point that activated this leaf. Must be supplied with group_activation_id.
group_activation_id	Optional non-empty character scalar identifying one grouped firing within a run. Must be supplied with grouped_decision_point_id.
decision_plan_metadata	Optional named list copied from the accepted DecisionPlan() for grouped audit only. It requires both grouped identity fields, remains available only on raw records, and is never an execution input.

Details

state_before and state_after are NULL by default. Supply a summary_fn to the TrajectoryLogger to enable summary-level or full capture.

Consult the entity's event history to determine which selected actions actually realized. For example, a later policy selection can be discarded when its decision point uses on_pending_action = "keep" and an earlier action is still pending.

Grouped leaf records carry the static group id and one deterministic, run-local activation id shared by every emitted leaf row from that firing. Ordinary records leave both fields NULL. These fields correlate the grouped consultation; they do not provide proposal-to-realization lineage. decision_plan_metadata is copied unchanged for raw audit and is intentionally omitted from trajectory_table().

Value

A list of class "TrajectoryRecord".

fluxCore documentation built on Sept. 22, 2026, 5:07 p.m.