Snapshots and audit trail

Configuration snapshots and rollback for Binary AI Engines, what a snapshot does and does not capture, and the append-only action log that records every steering decision, cooldown and status change.

5 min readUpdated 3 August 2026snapshots, rollback, audit, compliance

Two records sit behind every engine: a snapshot history you can roll back to, and an action log you cannot change. Between them they answer "what was this engine configured to do, and what did it do", which is the question that matters if anyone ever asks about an outcome.

Snapshots

A snapshot is a point-in-time copy of one engine's configuration, plus the performance figures at that moment. They live under System → Snapshots.

When one is taken

Trigger	Type
Every engine update — automatically, before the write	Automatic
Create Snapshot on the snapshots screen	Manual
Create All Snapshots on the Settings page	Manual, one per engine
Before a rollback — of the state being replaced	Automatic

The automatic snapshot before an update runs after payload validation, so a rejected edit does not leave a snapshot behind. That ordering also means a snapshot only ever records a state the engine legitimately held.

What a snapshot captures

Thirty-seven configuration columns — everything the engine update endpoint is allowed to change:

Win rate: targetUserWinRate, winRateVariance, winRateResetHours, optimizationStrategy
Steering: maxPriceAdjustmentPercent, adjustmentLeadTimeSeconds, volatilityMaskingEnabled, volatilityNoisePercent, minPositionForOptimization
Whales: enableWhaleDetection, whaleThreshold, whaleStrategy, whaleWinRateCap, whaleProfitMultiplier
Tiers: enableUserTiers, tierCalculationMethod
Cooldowns: enableBigWinCooldown, bigWinThreshold, cooldownDurationMinutes, cooldownWinRateReduction, enableStreakCooldown, streakThreshold, streakCooldownDuration
Practice and simulation: practiceMode, practiceTargetWinRate, practiceWinRateVariance, simulationMode, logSimulatedActions
Risk: maxDailyLoss, maxSingleOrderExposure, emergencyStopLoss
Correlation: enableExternalCorrelation, externalPriceSource, maxDeviationPercent, correlationConfig
Other: allowedOrderTypes, enableMlAutoApply

Alongside that, a performance snapshot: period wins, losses, win rate and platform profit at the moment it was taken.

What it deliberately does not capture

Status. status is a runtime lifecycle column, not configuration. Rolling it back with a raw update would set the database to a state the in-memory tick loop does not agree with — an engine recorded as ACTIVE that nothing is running, or the reverse.

Restore configuration from a snapshot; set status deliberately afterwards.

Also outside a snapshot: user tiers, cooldowns, positions, A/B tests and cohorts. Those are data, not configuration, and a rollback does not touch them.

A snapshot is only worth taking if rolling it back returns the engine to the state it was in. If a future field becomes editable but is not captured, a rollback would restore most columns, report success, and silently leave the rest wherever they had drifted to. That has happened before — eight fields were missing, including simulationMode, which is whether the engine steers real money at all.

Rolling back

Rollback on a snapshot restores its configuration to the engine.

The sequence:

An automatic snapshot of the current state is taken first, so a rollback is itself reversible.
The captured fields are applied. Unknown or absent fields are skipped rather than written as null.
A ROLLBACK_EXECUTED audit row is written.
The loaded engine configuration is reloaded so the next tick uses it.

Rollback requires manage.ai.binary_engine.snapshot.

Comparing

Compare diffs an engine's current configuration against a snapshot, field by field. Use it before you roll back: it is usually faster to change the two fields that actually drifted than to revert thirty-seven.

Retention

Automatic snapshots are capped at 50 per engine. When the cap is passed, the oldest are deleted. Manual snapshots are never pruned — if a configuration matters enough to keep, make it a manual snapshot with a name that says why.

Deleting an engine cascades to its snapshots.

A practical routine

Before a deliberate retune, take a manual snapshot named for what you are about to try — "before widening band to 0.005".
Make one change at a time and let a full period elapse. Changing three things at once means you learn nothing from the result.
Read the engine statistics and the dashboard verdict breakdown at the end of the period.
Roll back if it went badly. The named snapshot is the destination; the automatic one taken during the rollback is your way back out again.

The action log

Every engine has an append-only action log at Engine → Audit Log, filterable by action type. It is written by the engine itself, not by the admin request layer, so it records what the engine did as well as what an operator asked for.

Action type	Written when
`ENGINE_CREATED`	An engine is created, with its initial target and practice mode
`ENGINE_START`	An engine is activated
`ENGINE_PAUSE`	An engine is paused
`ENGINE_STOP`	An engine is stopped
`EMERGENCY_STOP`	The emergency stop fires, with the supplied reason
`PRICE_ADJUSTMENT`	A market-side price nudge is executed
`OUTCOME_OVERRIDE`	An outcome decision is applied
`SIMULATION_RUN`	A shadow-mode decision is recorded
`WHALE_DETECTED`	An order crosses the whale threshold
`WHALE_HANDLED`	A whale strategy is applied
`COOLDOWN_APPLIED`	A big-win or streak cooldown starts
`COOLDOWN_REMOVED`	A cooldown is lifted
`TIER_ADJUSTMENT`	A user's tier changes
`PERIOD_RESET`	A win-rate period is archived and cleared
`CORRELATION_ALERT`	An external price deviation breaches the threshold
`AB_TEST_STARTED` / `AB_TEST_ENDED`	An experiment begins or closes
`ROLLBACK_EXECUTED`	A snapshot is restored
`CONFIG_CHANGE`	Configuration is edited; also carries risk alerts

Rows carry the engine, the symbol, who triggered it (SYSTEM, ADMIN or a user ID), a simulated flag, and a JSON details object with the specifics.

The risk manager records alerts as CONFIG_CHANGE with details.alertType = "RISK_ALERT". Filtering the log on an action type of RISK_ALERT returns nothing, because nothing writes that type.

The dashboard's recent events

The dashboard shows the newest engine events from the last 24 hours, capped at 20. It is a sample, not a population:

never read its length as a total;
never conclude that something did not happen because it is absent.

The one question the dashboard answers as a fact — "did the emergency stop fire in the last 24 hours?" — gets its own dedicated query for exactly that reason. A stop buried under twenty newer whale rows is still a stop.

The position record

Alongside the action log, every order the engine tracked has a position row that survives settlement. It is the per-trade record:

Field	What it tells you
`side`, `amount`, `entryPrice`, `expiryTime`	The order as placed
`userTier`, `isWhale`, `hasCooldown`	The per-user context in force
`abTestId`, `abVariant`	The experiment arm governing this position
`outcome`, `closePrice`, `settledAt`	How it resolved
`platformProfit`	Realised house profit or loss
`wasManipulated`	Whether the close was genuinely steered
`manipulationDetails.targetSide`	Which side the engine chose
`manipulationDetails.settlementDecision`	Why it was, or was not, steered

settlementDecision is the field that turns "the engine is ACTIVE, so why did this settle fairly?" from an investigation into a lookup. Every value is documented in Pricing and settlement.

Positions are visible per engine at Engine → Positions, filterable by status and whale flag.

Retention and deletion

Nothing here is pruned except automatic snapshots. Actions, positions, daily statistics, cooldown history and correlation history accumulate for as long as the engine exists.

Deleting an engine cascades to all of it: positions, actions, daily stats, tiers, cooldowns, snapshots, simulations, A/B tests, cohorts, correlation alerts and correlation history. There is no soft delete and no export step.

If you are retiring a market, set the engine to STOPPED. It costs nothing and it keeps the record.

Global settings — the platform-wide switches
Engines — per-engine configuration and the update path
Admin audit trail — the platform-wide audit trail, which is separate from this addon's engine log