# RazgaR BEE

Backtesting Exchange Engine: PHP, Redis, and Python services for replay,
backtesting, websocket delivery, and test-state persistence.

## Results V2 contract

`deploy/migrations/20260729_bee_results_v2.sql` creates idempotent terminal
summary, equity-point, and indicator-point entities. `ResultsV2` is pure: an
equity point is `wallet_balance + unrealized_pnl`; `net_pnl` is final minus
initial equity; `gross_pnl` adds the already-recorded fees back exactly once;
`return_percent` is the ratio `(net_pnl - fees) / initial_equity` (for example, `0.1`
means a 10% return); it is null when initial equity is zero.

A closed trade accumulates every realized transaction PnL from a zero-to-nonzero
opening until flat or reversal. A reversal closes the prior trade and starts a
new one; an open terminal position is retained and does not manufacture a final trade. A flat run with no
completed trades records zero trade metrics and a null profit factor. Historical
rows without intra-run equity/indicator provenance must be written with
`data_completeness = legacy_partial`; they do not claim a true intra-run maximum
drawdown. Indicator snapshots are copied, provenance-hashed, bounded to
1..5000 requested points (1000 by default), and deterministically downsampled
while retaining the first and last point when the limit permits it.

Indicator rows require an immutable `strategy_revision_id`, the SHA-256 of the
materialized strategy snapshot, and decision context. Missing or drifted
provenance rejects the indicator row and makes the terminal result partial.
Equity and indicator readers apply the same deterministic 1..5000 full-range
bound while preserving the first and latest point.

`ResultsV2Observer` records the post-fill state in the real `update.php` path
and the terminal state in both normal completion and `stop.php`. Its results DB
connection is best-effort, so unavailable telemetry cannot alter replay/order
decisions or prevent the established terminal lifecycle. Each actual transaction
is buffered in Redis before its existing publish; only a complete buffer yields
`data_completeness = complete`. A missing or unreadable buffer is persisted as
`partial`, not as a complete terminal trade summary.
Actual order IDs and wall-clock start/terminal timestamps are buffered
idempotently. All failed or missing evidence is recorded in
`incomplete_reasons` and prevents a complete result.

## Migration provenance

| Branch | GitLab source | Source SHA |
|---|---|---|
| `main` | `razgar/bee/bee-exchange-production:development` | `2e6979d76eae326bce4b06927cd40321dddcc442` |
| `staging` | `razgar/bee/bee-exchange-test:development` | `02ab027a6354d84c8f6d25d1850af86eb8ef775b` |
| `development` | `razgar/bee/bee-exchange:development` | `d4b2e80621f4a9e7d4b7e6deaa07cdd54192dc41` |

The GitLab default `main` branches were placeholders in some BEE repositories.
The selected refs above contain the latest environment code. Original refs are
retained under `legacy/prod/*`, `legacy/test/*`, and `legacy/dev/*`.