# Position-Event Derive (book first-difference) — Design Spec

**Date:** 2026-06-24
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude

> Reference issue: #115 (milestone "Realistic broker & position-event table
> (C10 A-side)"). Fork decisions recorded as a #115 comment (cycle 0068).
> Supersedes the rolled-back 0064 exposure-integral derive (abandoned per #117).

## Goal

Derive the broker-independent **position-event table** — the `PositionEvent`
rows pinned by #114 — from a completed `PositionManagement` run, as the **first
difference of the executed book** (`deal = target − book − in_flight`;
`in_flight = 0` for the instant-fill backtest). This is the standalone,
deterministic, post-run reduction that #116's realistic brokers will consume and
that #122 will persist. It is the decoupled Stage-2 *audit* layer of C10,
buildable and testable now against the existing flat-1R executor — independent of
the realistic broker, currency equity, and the equity→Sizer feedback (all #116).

Out of scope (deferred to #116): fixed-fractional sizing that reads account
equity (the only feedback, cut by the z⁻¹ register on the fill edge — C10 assigns
it to #116); the realistic broker; currency equity; persistence (#122);
currency metrics (#121).

## Architecture

A pure post-run fold

```
derive_position_events(record, instrument_id) -> Vec<PositionEvent>
```

in `aura-engine` (`src/report.rs`), the **sibling of `summarize_r`** — same home
(beside `RunMetrics` / `PositionEvent`, both already there since cycle 0063), same
shape (a total pure function over the `PositionManagement` dense record), same
cross-crate discipline: it reads the 14-column record **positionally** as
type-erased `Scalar`s (C7 SoA), never importing the producer's `aura-std` types.

It is **not** an in-graph node — the run loop never calls it, so the hot path
stays domain-free (the same standard that placed `PositionEvent`/`summarize_r` in
`aura-engine`). `aura-engine` depends only on `aura-core`, so it **cannot** import
`InstrumentSpec` (that lives in `aura-ingest`, which depends on `aura-engine`; the
reverse is a dependency cycle). The `instrument_id` is therefore a caller-supplied
**scalar** argument — exactly as `summarize_r` takes `round_trip_cost` — extracted
by the caller from the run's `InstrumentSpec.instrument_id` at the source edge.

The derive maintains a single-position **book** as it walks the record in cycle
order and emits the book's first difference: a `Buy`/`Sell` at each open, a `Close`
at each close. A **reversal** (close + re-open in one cycle) emits `Close` then the
opposite-direction open at the **same `event_ts`**, close before open (the #114
contract). This is `deal = target − book − in_flight` specialised to the current
single-position-at-a-time executor (`book` ∈ {flat, ±one position}; `in_flight`
always 0).

## Concrete code shapes

### Worked usage (what a consumer / the future #123 CLI writes)

```rust
use aura_engine::{derive_position_events, PositionEvent, PositionAction};

// After a stage1-r run, `r_record: Vec<(Timestamp, Vec<Scalar>)>` is the
// PositionManagement dense record (the same value summarize_r already folds).
// `instrument_id` comes from the run's InstrumentSpec (a scalar; the engine
// never imports aura-ingest).
let events: Vec<PositionEvent> = derive_position_events(&r_record, instrument_id);

// Each entry is a Buy/Sell; each exit a Close referencing the position it closes.
// A reversal is a Close then the opposite open at the SAME event_ts (close first).
// A position still open at window end has its open event but no synthetic Close —
// the table records actual executed events (summarize_r's force-close is for the
// R metric only, not for the event table).
```

### Must-pass test (the #114 reversal contract, now *produced by the derive*)

```rust
#[test]
fn reversal_derives_close_then_open_at_same_ts() {
    // Hand-built PM record (only the columns the derive reads are set; others 0):
    //   t=10: open LONG  size 2.0  (closed=false, direction=+1, size=2.0, open=true)
    //   t=20: REVERSAL to SHORT    (closed=true,  direction=-1, size=3.0, open=true)
    //   t=30: stop close           (closed=true,  direction=-1, size=3.0, open=false)
    let record = pm_rows(&[
        (10, /*closed*/ false, /*dir*/  1, /*size*/ 2.0, /*open*/ true),
        (20, /*closed*/ true,  /*dir*/ -1, /*size*/ 3.0, /*open*/ true),
        (30, /*closed*/ true,  /*dir*/ -1, /*size*/ 3.0, /*open*/ false),
    ]);

    let ev = derive_position_events(&record, 42);

    // open long; reversal = close-then-open at t=20; final close at t=30
    assert_eq!(ev.len(), 4);
    assert_eq!(ev[0].action, PositionAction::Buy);
    assert_eq!(ev[0].event_ts, Timestamp(10));
    assert_eq!(ev[0].volume, 2.0);          // unsigned lots = the size column
    assert_eq!(ev[0].position_id, 0);

    assert_eq!(ev[1].action, PositionAction::Close);   // close the long
    assert_eq!(ev[1].position_id, 0);
    assert_eq!(ev[1].event_ts, Timestamp(20));
    assert_eq!(ev[1].volume, 2.0);          // full close = the book's volume

    assert_eq!(ev[2].action, PositionAction::Sell);    // open the short
    assert_eq!(ev[2].position_id, 1);
    assert_eq!(ev[2].event_ts, Timestamp(20));         // SAME instant as the close
    assert_eq!(ev[2].volume, 3.0);

    assert_eq!(ev[3].action, PositionAction::Close);
    assert_eq!(ev[3].position_id, 1);
    assert_eq!(ev[3].event_ts, Timestamp(30));

    assert_eq!(ev[0].instrument_id, 42);
}
```

### Before → after implementation shape (secondary)

`PositionEvent` / `PositionAction` already exist (cycle 0063). No struct change.
The change is one new public function plus two column-index constants:

```rust
// crates/aura-engine/src/report.rs — extend the existing `mod r_col`
mod r_col {
    pub const CLOSED: usize = 0;
    pub const REALIZED_R: usize = 1;
    pub const DIRECTION: usize = 4;      // NEW — i64: +1 long, -1 short (0 = flat)
    pub const ENTRY_PRICE: usize = 6;
    pub const STOP_PRICE: usize = 7;
    pub const CONVICTION_AT_ENTRY: usize = 9;
    pub const SIZE: usize = 10;          // NEW — f64 lots from the Sizer
    pub const OPEN: usize = 11;
    pub const UNREALIZED_R: usize = 12;
}

/// Derive the broker-independent position-event table from a `PositionManagement`
/// dense record (read positionally, C7 SoA), as the first difference of the
/// executed book. Pure (C1); no look-ahead (each event's `event_ts` is its own
/// cycle, C2). `instrument_id` is supplied by the caller (the engine never imports
/// `InstrumentSpec`). A reversal emits Close then the opposite open at one
/// `event_ts` (close first); a window-end open position emits its open with no
/// synthetic Close.
pub fn derive_position_events(
    record: &[(Timestamp, Vec<Scalar>)],
    instrument_id: i64,
) -> Vec<PositionEvent> {
    struct Book { position_id: i64, dir: i64, volume: f64 }
    let mut out: Vec<PositionEvent> = Vec::new();
    let mut book: Option<Book> = None;
    let mut next_id: i64 = 0;
    for (ts, row) in record {
        // 1) close first: the book held into this cycle exited
        if row[r_col::CLOSED].as_bool()
            && let Some(b) = book.take()
        {
            out.push(PositionEvent {
                event_ts: *ts,
                action: PositionAction::Close,
                position_id: b.position_id,
                instrument_id,
                volume: b.volume,
            });
        }
        // 2) then open: a position is open at cycle end the book isn't tracking
        if row[r_col::OPEN].as_bool() && book.is_none() {
            let dir = row[r_col::DIRECTION].as_i64();
            let volume = row[r_col::SIZE].as_f64();
            let action = if dir >= 0 { PositionAction::Buy } else { PositionAction::Sell };
            out.push(PositionEvent {
                event_ts: *ts,
                action,
                position_id: next_id,
                instrument_id,
                volume,
            });
            book = Some(Book { position_id: next_id, dir, volume });
            next_id += 1;
        }
    }
    out
}
```

(Exact bytes / `Scalar` accessor names — `.as_bool()` / `.as_i64()` / `.as_f64()`
mirror `summarize_r`'s reads — and the test helper `pm_rows`/`pm_record` are the
planner's job.)

## Components

- **`derive_position_events`** — new `pub fn` in `crates/aura-engine/src/report.rs`,
  beside `summarize_r`. Re-export from the crate root mirrors `PositionEvent`
  (already exported; the fn joins the same `pub use` line in `lib.rs`).
- **`r_col::DIRECTION` (=4), `r_col::SIZE` (=10)** — two added column indices in the
  existing private `r_col` module (the lockstep contract with `aura-std`'s
  `FIELD_NAMES`/`RECORD_KINDS`, guarded by `stage1_r_e2e.rs`).
- **Internal `Book` state** — the derive's single-position book (`position_id`,
  `dir`, `volume`); `in_flight` is structurally 0 (instant fills) so it is not
  represented.

## Data flow

`PositionManagement` dense record (per-cycle `(Timestamp, Vec<Scalar>)` rows, in
cycle order) → `derive_position_events` walks rows, maintaining the book → emits
`Vec<PositionEvent>`. The caller (a test, or the future #123 CLI) supplies
`instrument_id` from the run's `InstrumentSpec` at the source edge. No node, no
graph wiring, no hot-path call — the run loop is untouched (C14 domain-free hot
path holds, as for `summarize_r`).

## Error handling

The function is **total and pure**: an empty record → empty vec; a window-end open
position → its open event with no synthetic Close. The record's column layout is
the producer-guaranteed `PositionManagement` lockstep contract (`stage1_r_e2e.rs`
guards it), so malformed input is not a runtime concern; no panics, no `Result`.
`direction == 0` cannot occur on an `open` row (the executor only opens on a
nonzero bias), and the `dir >= 0 => Buy` branch is a total mapping regardless.

## Testing strategy

Unit tests in `report.rs` (sibling of the `summarize_r` tests):

- **reversal** → Close then opposite open at the same `event_ts`, close first
  (the must-pass test above).
- **normal lifecycle** — open long, hold one cycle, stop-close → `Buy` at the open
  cycle, `Close` at the exit cycle; `event_ts` from each row's own cycle.
- **short** — a short entry → `Sell`.
- **window-end open** — last row `open = true`, never closed → the open event only,
  no `Close`.
- **empty record** → empty vec.
- **position_id monotonic** — successive positions get 0, 1, 2…; each `Close`
  carries the `position_id` of the open it closes; `volume` equals the book volume,
  unsigned.

E2E (extend `crates/aura-engine/tests/stage1_r_e2e.rs`): run the existing stage1-r
seam, fold both `summarize_r` and `derive_position_events`, and assert the table is
consistent with the metrics — the number of `Close` events equals
`summarize_r`'s closed-trade count (`n_trades` minus any window-end open), and
every `Close`'s `position_id` was opened by an earlier `Buy`/`Sell`.

## Acceptance criteria

- `derive_position_events(record, instrument_id)` produces a faithful
  `PositionEvent` table from a `PositionManagement` record.
- A reversal emits `Close` then the opposite open at one `event_ts`, close before
  open (the #114 contract, now *derived*, not just hand-built in a test).
- A window-end open position emits its open with no synthetic `Close`.
- Deterministic (C1); no look-ahead — each event's `event_ts` is its own cycle (C2);
  broker-independent (C10); pure scalar columns, no new streamed type (C7); the
  hot path is untouched (no node, C14).
- Fixed-fractional / currency / equity-feedback sizing is **not** in scope (#116).
- Additive only: `cargo build --workspace`, `cargo test --workspace`, and
  `cargo clippy --workspace --all-targets -- -D warnings` are clean, and no existing
  golden / serde test changes (the derive adds a function; it touches no existing
  output).