Owns and runs the engine's step loop and reports how the run ended. More...

#include <driver.hpp>

Public Types
enum	exitReason_t { winStateFound = 0 , winCollectionFull = 7 , outOfStates = 1 , maximumStepReached = 2 , bestBelowReference = 3 , inputHistoryNearCapacity = 4 , referenceBelowWorst = 5 , exceededReferenceFrames = 6 }
	Reason the run loop terminated, returned by run. More...

Public Member Functions
	Driver (const std::string &configFilePath, const nlohmann::json &config)
	Constructs the driver and its engine/runner from the parsed configuration.

	~Driver ()
	Destroys the driver.

void	initialize ()
	Resets the execution back to the starting point.

int	run ()
	Runs the engine's step loop until a termination condition is met.

void	storeManualSaveSolution ()
	Saves a solution explicitly requested by the engine, if any.

void	saveBestStateInformation ()
	Writes the current best solution to file, under the mutex.

void	saveWorstStateInformation ()
	Writes the current worst solution to file, under the mutex.

void	intermediateResultSaveLoop ()
	Background loop that periodically saves best and worst solutions to file.

void	updateWorstState ()
	Refreshes the tracked worst state, its solution, and its reward.

void	updateBestState ()
	Refreshes the tracked best state, its solution, and its reward.

void	printInfo ()
	Prints the current state of execution to the logger.

size_t	getCurrentStep ()
	Returns the current step counter.

Static Public Member Functions
static std::unique_ptr< Driver >	getDriver (const std::string &configFilePath, const nlohmann::json &config)
	Factory that constructs a driver from configuration.

Private Attributes
const std::string	_configFilePath
	Path to the config file, kept for reference.

std::unique_ptr< Engine >	_engine
	Pointer to the internal Jaffar engine.

std::unique_ptr< Runner >	_runner
	Runner used for printing information and saving partial results.

size_t	_jobId
	Job identifier (derived from system time) distinguishing intermediate values between jobs.

size_t	_maxSteps
	Maximum number of steps (zero = not established).

size_t	_currentStep
	Counter for the number of steps performed; the initial state counts as step zero.

ssize_t	_stopFramesAfterFirstWin = -1
	Stop N steps after the first win (0 = immediately; -1 = never stop on wins)

ssize_t	_firstWinStep = -1
	Step at which the first win was found.

bool	_winCollectArm = false
	Whether "Win State Collection" was enabled in the config (applied to the engine post-construction)

std::vector< std::string >	_winCollectProps
	Win-state collection: dedup property names.

std::string	_winCollectPrefix
	Win-state collection: output path prefix.

size_t	_winCollectMax = 1000
	Win-state collection: Max Files cap.

size_t	_winStatesFound
	Total number of win states found so far.

float	_bestWinStateReward
	Reward for the best win state found so far.

size_t	_bestWinStateStepCount = 0
	Depth of the best win state (recorded at capture; the count is not stored per-state).

size_t	_bestStateStepCount = 0
	Depth of the current best state, set by updateBestState() and reused by the printInfo reload.

float	_bestStateReward
	Ranking reward (magnet-biased) for the best state found so far; drives eviction/display.

float	_bestStateFloorReward
	Un-biased progress (position) reward of the best state; used for the Reference Reward Floor comparison.

float	_worstStateReward
	Reward for the worst state found so far.

bool	_referenceFloorEnabled
	Whether the reference reward floor cancel is active.

float	_referenceFloorTolerance
	Allowed shortfall of best below the reference per step.

uint32_t	_referenceFloorStepGrace = 0
	Compare best against the reference this many steps earlier (bounded time slack for jumpy rewards).

bool	_cancelIfReferenceBelowWorst
	Opt-in: enable the below-worst check (surfaced as a log addendum, not a cancel).

float	_referenceBelowWorstMargin
	Margin added to the reference before the below-worst comparison (typically the pinning bonus).

bool	_referenceBelowWorstNow = false
	Whether the reference is currently below the worst kept state (per-step log addendum).

std::string	_referenceTracePath
	Legacy precomputed-trace file path (loaded on demand if only the engine-side prune needs it)

std::vector< float >	_referenceReward
	Per-step reference reward floor (index = step).

std::vector< int >	_referenceStateType
	Per-step reference state type (normal/win/fail) recorded during the floor replay.

std::string	_referenceSolutionPath
	Optional reference solution (.sol) replayed at init to build _referenceReward.

std::string	_referenceFloorInitialStatePath
	Optional raw state file rebasing the floor replay onto the reference's own lineage.

std::string	_referenceFloorInitialSequencePath
	Optional emulator-level prefix sequence for the reference-lineage rebase.

double	_inputHistoryCapacityWatermark = 0.95
	Fraction of the input-history trie's hard ceiling at which the run stops gracefully (high-water mark).

std::string	_bestStateStorage
	Storage for the current best (win or otherwise) state.

std::string	_worstStateStorage
	Storage for the current worst (win or otherwise) state.

std::string	_bestSolutionStorage
	Storage for the current best solution's input history.

std::string	_worstSolutionStorage
	Storage for the current worst solution's input history.

size_t	_stateSize
	Storage size of a runner state.

__volatile__ bool	_hasFinished
	Internal flag indicating the driver has finished.

bool	_saveIntermediateResultsEnabled
	Whether to store intermediate results at all.

float	_saveIntermediateFrequency
	Minimum interval, in seconds, between intermediate result saves.

std::string	_saveIntermediateBestSolutionPath
	Path to store the best solution found so far.

std::string	_saveIntermediateWorstSolutionPath
	Path to store the worst solution found so far.

std::mutex	_updateIntermediateResultMutex
	Guards intermediate result storage between the main and saver threads.

Detailed Description

Owns and runs the engine's step loop and reports how the run ended.

The driver reads its configuration sections (Driver/Emulator/Game/Runner/Engine), constructs a Runner and an Engine, and repeatedly advances the engine one step at a time until a termination condition is reached (a win state, exhaustion of states, or the maximum step count). On each step it refreshes the tracked best and worst states, optionally stores a manually requested solution, and prints status. A separate thread periodically saves the best and worst solutions to file when intermediate result saving is enabled.

Definition at line 35 of file driver.hpp.

Member Enumeration Documentation

◆ exitReason_t

enum jaffarPlus::Driver::exitReason_t

Reason the run loop terminated, returned by run.

Enumerator
winStateFound	Found a win state.
winCollectionFull	Win-state collection reached its Max Files cap.
outOfStates	Engine ran out of states.
maximumStepReached	Maximum step reached.
bestBelowReference	The best state's reward fell below the reference reward floor at this step.
inputHistoryNearCapacity	The shared input-history trie neared/hit its hard memory ceiling.
referenceBelowWorst	The reference reward fell below the worst kept state (reference evicted from the frontier)
exceededReferenceFrames	The run reached the reference's frame count without winning (can no longer beat it)

Definition at line 40 of file driver.hpp.

Constructor & Destructor Documentation

◆ Driver()

jaffarPlus::Driver::Driver	(	const std::string &	configFilePath,
		const nlohmann::json &	config
	)

inline

Constructs the driver and its engine/runner from the parsed configuration.

Reads the "Driver Configuration" section (end-on-first-win flag, max steps, intermediate result settings), derives a job identifier from the current system time, and builds the Runner and Engine from their respective configuration sections.

Parameters

configFilePath	Path to the config file, kept for reference and reporting.
config	Parsed configuration object containing all component sections.

Definition at line 68 of file driver.hpp.

◆ ~Driver()

jaffarPlus::Driver::~Driver ( )

inline

Destroys the driver.

Definition at line 209 of file driver.hpp.

Member Function Documentation

◆ getCurrentStep()

size_t jaffarPlus::Driver::getCurrentStep ( )

inline

Returns the current step counter.

Definition at line 957 of file driver.hpp.

◆ getDriver()

static std::unique_ptr< Driver > jaffarPlus::Driver::getDriver	(	const std::string &	configFilePath,
		const nlohmann::json &	config
	)

inlinestatic

Factory that constructs a driver from configuration.

Parameters

configFilePath	Path to the config file, kept for reference and reporting.
config	Parsed configuration object containing all component sections.

Returns: A unique pointer to the newly constructed Driver.

Definition at line 947 of file driver.hpp.

◆ initialize()

void jaffarPlus::Driver::initialize ( )

inline

Resets the execution back to the starting point.

Clears the step and win-state counters, resets the best/worst reward trackers, initializes the runner and engine, and allocates storage for the current best and worst states.

Definition at line 217 of file driver.hpp.

◆ intermediateResultSaveLoop()

void jaffarPlus::Driver::intermediateResultSaveLoop ( )

inline

Background loop that periodically saves best and worst solutions to file.

Runs while the driver has not finished, waking every 100 ms; once the configured frequency has elapsed since the last save (and at least one step has been performed), it saves the best and worst state information and resets the timer.

Definition at line 679 of file driver.hpp.

◆ printInfo()

void jaffarPlus::Driver::printInfo ( )

inline

Prints the current state of execution to the logger.

Logs the job id, script file, emulator and game names, current/max step, and the best/worst (or win/worst) reward summary, followed by the engine's information and, after loading the best state into the runner, the runner/game/emulator information for that best state.

Definition at line 851 of file driver.hpp.

◆ run()

int jaffarPlus::Driver::run ( )

inline

Runs the engine's step loop until a termination condition is met.

Optionally launches the intermediate result saver thread, then advances the engine one step per iteration, updating the tracked best/worst states, storing any manually requested solution, and printing status each step. The loop ends on the first win state (when so configured), when the engine runs out of states, or when the maximum step count is reached. On exit it joins the saver thread, saves the best state information, and prints a final report.

Returns: The exitReason_t describing why the loop stopped.

Definition at line 411 of file driver.hpp.

◆ saveBestStateInformation()

void jaffarPlus::Driver::saveBestStateInformation ( )

inline

Writes the current best solution to file, under the mutex.

When a best solution path is configured, saves the best solution both under the plain configured name and under a copy suffixed with the job id and current step number.

Definition at line 629 of file driver.hpp.

◆ saveWorstStateInformation()

void jaffarPlus::Driver::saveWorstStateInformation ( )

inline

Writes the current worst solution to file, under the mutex.

When a worst solution path is configured, saves the worst solution both under the plain configured name and under a copy suffixed with the job id.

Definition at line 654 of file driver.hpp.

◆ storeManualSaveSolution()

void jaffarPlus::Driver::storeManualSaveSolution ( )

inline

Saves a solution explicitly requested by the engine, if any.

Queries the engine for a manual-save request; when one has a non-empty path, it loads that state into the runner and writes the runner's input history to the requested file.

Definition at line 606 of file driver.hpp.

◆ updateBestState()

void jaffarPlus::Driver::updateBestState ( )

inline

Refreshes the tracked best state, its solution, and its reward.

Does nothing when the state database is empty and no win states have been found. Otherwise, under the mutex: if no win state has been found yet it uses the engine's current best state; if a win state was found this step and improves on the best win reward so far, it adopts that win state. It then loads the best state into the runner, updates the best-state reward, and records the runner's input history as the best solution.

Definition at line 752 of file driver.hpp.

◆ updateWorstState()

void jaffarPlus::Driver::updateWorstState ( )

inline

Refreshes the tracked worst state, its solution, and its reward.

Does nothing when the state database is empty. Otherwise, under the mutex, copies the engine's worst state into local storage, loads it into the runner, records the runner's input history as the worst solution, and updates the worst-state reward.

Definition at line 714 of file driver.hpp.

Member Data Documentation

◆ _bestSolutionStorage

std::string jaffarPlus::Driver::_bestSolutionStorage

private

Storage for the current best solution's input history.

Definition at line 1019 of file driver.hpp.

◆ _bestStateFloorReward

float jaffarPlus::Driver::_bestStateFloorReward

private

Un-biased progress (position) reward of the best state; used for the Reference Reward Floor comparison.

Definition at line 991 of file driver.hpp.

◆ _bestStateReward

float jaffarPlus::Driver::_bestStateReward

private

Ranking reward (magnet-biased) for the best state found so far; drives eviction/display.

Definition at line 990 of file driver.hpp.

◆ _bestStateStepCount

size_t jaffarPlus::Driver::_bestStateStepCount = 0

private

Depth of the current best state, set by updateBestState() and reused by the printInfo reload.

Definition at line 988 of file driver.hpp.

◆ _bestStateStorage

std::string jaffarPlus::Driver::_bestStateStorage

private

Storage for the current best (win or otherwise) state.

Definition at line 1015 of file driver.hpp.

◆ _bestWinStateReward

float jaffarPlus::Driver::_bestWinStateReward

private

Reward for the best win state found so far.

Definition at line 986 of file driver.hpp.

◆ _bestWinStateStepCount

size_t jaffarPlus::Driver::_bestWinStateStepCount = 0

private

Depth of the best win state (recorded at capture; the count is not stored per-state).

Definition at line 987 of file driver.hpp.

◆ _cancelIfReferenceBelowWorst

bool jaffarPlus::Driver::_cancelIfReferenceBelowWorst

private

Opt-in: enable the below-worst check (surfaced as a log addendum, not a cancel).

Definition at line 998 of file driver.hpp.

◆ _configFilePath

const std::string jaffarPlus::Driver::_configFilePath

private

Path to the config file, kept for reference.

Definition at line 960 of file driver.hpp.

◆ _currentStep

size_t jaffarPlus::Driver::_currentStep

private

Counter for the number of steps performed; the initial state counts as step zero.

Definition at line 970 of file driver.hpp.

◆ _engine

std::unique_ptr<Engine> jaffarPlus::Driver::_engine

private

Pointer to the internal Jaffar engine.

Definition at line 962 of file driver.hpp.

◆ _firstWinStep

ssize_t jaffarPlus::Driver::_firstWinStep = -1

private

Step at which the first win was found.

Definition at line 974 of file driver.hpp.

◆ _hasFinished

__volatile__ bool jaffarPlus::Driver::_hasFinished

private

Internal flag indicating the driver has finished.

Definition at line 1025 of file driver.hpp.

◆ _inputHistoryCapacityWatermark

double jaffarPlus::Driver::_inputHistoryCapacityWatermark = 0.95

private

Fraction of the input-history trie's hard ceiling at which the run stops gracefully (high-water mark).

One step's growth (~ live-states nodes) is far below the remaining headroom at this level, so the next per-step check always fires before a worker hits the actual ceiling. Not a config key (sane fixed default); the real lever is Store Input History Type ("Raw" vs "Trie") and the State DB size.

Definition at line 1013 of file driver.hpp.

◆ _jobId

size_t jaffarPlus::Driver::_jobId

private

Job identifier (derived from system time) distinguishing intermediate values between jobs.

Definition at line 966 of file driver.hpp.

◆ _maxSteps

size_t jaffarPlus::Driver::_maxSteps

private

Maximum number of steps (zero = not established).

Definition at line 968 of file driver.hpp.

◆ _referenceBelowWorstMargin

float jaffarPlus::Driver::_referenceBelowWorstMargin

private

Margin added to the reference before the below-worst comparison (typically the pinning bonus).

Definition at line 999 of file driver.hpp.

◆ _referenceBelowWorstNow

bool jaffarPlus::Driver::_referenceBelowWorstNow = false

private

Whether the reference is currently below the worst kept state (per-step log addendum).

Definition at line 1000 of file driver.hpp.

◆ _referenceFloorEnabled

bool jaffarPlus::Driver::_referenceFloorEnabled

private

Whether the reference reward floor cancel is active.

Definition at line 995 of file driver.hpp.

◆ _referenceFloorInitialSequencePath

std::string jaffarPlus::Driver::_referenceFloorInitialSequencePath

private

Optional emulator-level prefix sequence for the reference-lineage rebase.

Definition at line 1007 of file driver.hpp.

◆ _referenceFloorInitialStatePath

std::string jaffarPlus::Driver::_referenceFloorInitialStatePath

private

Optional raw state file rebasing the floor replay onto the reference's own lineage.

Definition at line 1006 of file driver.hpp.

◆ _referenceFloorStepGrace

uint32_t jaffarPlus::Driver::_referenceFloorStepGrace = 0

private

Compare best against the reference this many steps earlier (bounded time slack for jumpy rewards).

Definition at line 997 of file driver.hpp.

◆ _referenceFloorTolerance

float jaffarPlus::Driver::_referenceFloorTolerance

private

Allowed shortfall of best below the reference per step.

Definition at line 996 of file driver.hpp.

◆ _referenceReward

std::vector<float> jaffarPlus::Driver::_referenceReward

private

Per-step reference reward floor (index = step).

Definition at line 1003 of file driver.hpp.

◆ _referenceSolutionPath

std::string jaffarPlus::Driver::_referenceSolutionPath

private

Optional reference solution (.sol) replayed at init to build _referenceReward.

Definition at line 1005 of file driver.hpp.

◆ _referenceStateType

std::vector<int> jaffarPlus::Driver::_referenceStateType

private

Per-step reference state type (normal/win/fail) recorded during the floor replay.

Definition at line 1004 of file driver.hpp.

◆ _referenceTracePath

std::string jaffarPlus::Driver::_referenceTracePath

private

Legacy precomputed-trace file path (loaded on demand if only the engine-side prune needs it)

Definition at line 1002 of file driver.hpp.

◆ _runner

std::unique_ptr<Runner> jaffarPlus::Driver::_runner

private

Runner used for printing information and saving partial results.

Definition at line 964 of file driver.hpp.

◆ _saveIntermediateBestSolutionPath

std::string jaffarPlus::Driver::_saveIntermediateBestSolutionPath

private

Path to store the best solution found so far.

Definition at line 1033 of file driver.hpp.

◆ _saveIntermediateFrequency

float jaffarPlus::Driver::_saveIntermediateFrequency

private

Minimum interval, in seconds, between intermediate result saves.

Definition at line 1031 of file driver.hpp.

◆ _saveIntermediateResultsEnabled

bool jaffarPlus::Driver::_saveIntermediateResultsEnabled

private

Whether to store intermediate results at all.

Definition at line 1029 of file driver.hpp.

◆ _saveIntermediateWorstSolutionPath

std::string jaffarPlus::Driver::_saveIntermediateWorstSolutionPath

private

Path to store the worst solution found so far.

Definition at line 1035 of file driver.hpp.

◆ _stateSize

size_t jaffarPlus::Driver::_stateSize

private

Storage size of a runner state.

Definition at line 1023 of file driver.hpp.

◆ _stopFramesAfterFirstWin

ssize_t jaffarPlus::Driver::_stopFramesAfterFirstWin = -1

private

Stop N steps after the first win (0 = immediately; -1 = never stop on wins)

Definition at line 972 of file driver.hpp.

◆ _updateIntermediateResultMutex

std::mutex jaffarPlus::Driver::_updateIntermediateResultMutex

private

Guards intermediate result storage between the main and saver threads.

Definition at line 1037 of file driver.hpp.

◆ _winCollectArm

bool jaffarPlus::Driver::_winCollectArm = false

private

Whether "Win State Collection" was enabled in the config (applied to the engine post-construction)

Definition at line 976 of file driver.hpp.

◆ _winCollectMax

size_t jaffarPlus::Driver::_winCollectMax = 1000

private

Win-state collection: Max Files cap.

Definition at line 982 of file driver.hpp.

◆ _winCollectPrefix

std::string jaffarPlus::Driver::_winCollectPrefix

private

Win-state collection: output path prefix.

Definition at line 980 of file driver.hpp.

◆ _winCollectProps

std::vector<std::string> jaffarPlus::Driver::_winCollectProps

private

Win-state collection: dedup property names.

Definition at line 978 of file driver.hpp.

◆ _winStatesFound

size_t jaffarPlus::Driver::_winStatesFound

private

Total number of win states found so far.

Definition at line 984 of file driver.hpp.

◆ _worstSolutionStorage

std::string jaffarPlus::Driver::_worstSolutionStorage

private

Storage for the current worst solution's input history.

Definition at line 1021 of file driver.hpp.

◆ _worstStateReward

float jaffarPlus::Driver::_worstStateReward

private

Reward for the worst state found so far.

Definition at line 993 of file driver.hpp.

◆ _worstStateStorage

std::string jaffarPlus::Driver::_worstStateStorage

private

Storage for the current worst (win or otherwise) state.

Definition at line 1017 of file driver.hpp.

The documentation for this class was generated from the following file:

driver.hpp

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ exitReason_t

Constructor & Destructor Documentation

◆ Driver()

◆ ~Driver()

Member Function Documentation

◆ getCurrentStep()

◆ getDriver()

◆ initialize()

◆ intermediateResultSaveLoop()

◆ printInfo()

◆ run()

◆ saveBestStateInformation()

◆ saveWorstStateInformation()

◆ storeManualSaveSolution()

◆ updateBestState()

◆ updateWorstState()

Member Data Documentation

◆ _bestSolutionStorage

◆ _bestStateFloorReward

◆ _bestStateReward

◆ _bestStateStepCount

◆ _bestStateStorage

◆ _bestWinStateReward

◆ _bestWinStateStepCount

◆ _cancelIfReferenceBelowWorst

◆ _configFilePath

◆ _currentStep

◆ _engine

◆ _firstWinStep

◆ _hasFinished

◆ _inputHistoryCapacityWatermark

◆ _jobId

◆ _maxSteps

◆ _referenceBelowWorstMargin

◆ _referenceBelowWorstNow

◆ _referenceFloorEnabled

◆ _referenceFloorInitialSequencePath

◆ _referenceFloorInitialStatePath

◆ _referenceFloorStepGrace

◆ _referenceFloorTolerance

◆ _referenceReward

◆ _referenceSolutionPath

◆ _referenceStateType

◆ _referenceTracePath

◆ _runner

◆ _saveIntermediateBestSolutionPath

◆ _saveIntermediateFrequency

◆ _saveIntermediateResultsEnabled

◆ _saveIntermediateWorstSolutionPath

◆ _stateSize

◆ _stopFramesAfterFirstWin

◆ _updateIntermediateResultMutex

◆ _winCollectArm

◆ _winCollectMax

◆ _winCollectPrefix

◆ _winCollectProps

◆ _winStatesFound

◆ _worstSolutionStorage

◆ _worstStateReward

◆ _worstStateStorage