# Position-Event Derive — Implementation Plan

> **Parent spec:** `docs/specs/0068-position-event-derive.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run
> this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Add the pure post-run reduction `derive_position_events(record,
instrument_id) -> Vec<PositionEvent>` to `aura-engine`, deriving the
broker-independent position-event table as the first difference of the executed
book from a `PositionManagement` dense record.

**Architecture:** One new `pub fn` in `crates/aura-engine/src/report.rs` beside
`summarize_r` (same positional, type-erased `Scalar` read of the 14-column PM
record), two added private `r_col` constants (`DIRECTION=4`, `SIZE=10`), a
crate-root re-export, unit tests in `report.rs`, and a lockstep-guard extension +
an agreement E2E test in `crates/aura-engine/tests/stage1_r_e2e.rs`. Purely
additive: no signature change, no struct change, no existing output touched.

**Tech Stack:** Rust, `aura-engine` (depends only on `aura-core`), the existing
`PositionEvent` / `PositionAction` value types (cycle 0063), the
`PositionManagement` dense-record contract (`aura-std`).

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-engine/src/report.rs:69-77` — add `r_col::DIRECTION=4` and
  `r_col::SIZE=10`; add `pub fn derive_position_events` immediately after
  `summarize_r` (ends L218); add unit tests in the `#[cfg(test)] mod tests`
  block (opens L515).
- Modify: `crates/aura-engine/src/lib.rs:64-67` — add `derive_position_events`
  to the `pub use report::{…}` re-export.
- Test: `crates/aura-engine/tests/stage1_r_e2e.rs` — add `const DIRECTION = 4`
  (beside L35-42), extend `r_col_indices_match_producer_field_layout` (L291-324)
  to name-pin `direction`, and add one agreement E2E test.

---

### Task 1: `derive_position_events` + `r_col` consts + re-export + unit tests

**Files:**
- Modify: `crates/aura-engine/src/report.rs` (`mod r_col` L69-77; new fn after
  L218; tests in `mod tests` from L515)
- Modify: `crates/aura-engine/src/lib.rs:64-67`

- [ ] **Step 1: Add the two column-index constants to `mod r_col`**

In `crates/aura-engine/src/report.rs`, inside the existing `mod r_col { … }`
(L69-77), add these two lines (keep the others unchanged; `OPEN=11` is already
present):

```rust
    pub const DIRECTION: usize = 4;
    pub const SIZE: usize = 10;
```

(Place `DIRECTION` after `REALIZED_R` and `SIZE` after `CONVICTION_AT_ENTRY` so
the consts stay in ascending index order; exact position is cosmetic.)

- [ ] **Step 2: Write the failing unit tests + the row helper**

In `crates/aura-engine/src/report.rs`, inside `#[cfg(test)] mod tests` (after the
existing `summarize_r_*` tests; `use super::*;` is already at the top of the
module, bringing `Scalar`, `Timestamp`, `r_col`, `PositionEvent`,
`PositionAction`, and the new `derive_position_events` into scope), add:

```rust
// One PositionManagement dense record row for the derive tests: only the columns
// derive_position_events reads (closed, direction, size, open) are set; the rest
// default to 0. Distinct per-row timestamps (the derive keys events on the row's
// own cycle, not the entry_ts column).
fn pm_row(ts: i64, closed: bool, dir: i64, size: f64, open: bool) -> (Timestamp, Vec<Scalar>) {
    let mut v = vec![Scalar::f64(0.0); r_col::UNREALIZED_R + 1];
    v[r_col::CLOSED] = Scalar::bool(closed);
    v[r_col::DIRECTION] = Scalar::i64(dir);
    v[r_col::SIZE] = Scalar::f64(size);
    v[r_col::OPEN] = Scalar::bool(open);
    (Timestamp(ts), v)
}

#[test]
fn derive_reversal_emits_close_then_opposite_open_at_one_ts() {
    let rec = vec![
        pm_row(10, false, 1, 2.0, true),   // open long
        pm_row(20, true, -1, 3.0, true),   // reversal: close long, reopen short
        pm_row(30, true, -1, 3.0, false),  // close short, flat
    ];
    let ev = derive_position_events(&rec, 42);
    assert_eq!(ev.len(), 4);
    assert_eq!(ev[0].action, PositionAction::Buy);
    assert_eq!(ev[0].event_ts, Timestamp(10));
    assert_eq!(ev[0].position_id, 0);
    assert_eq!(ev[0].volume, 2.0);
    assert_eq!(ev[0].instrument_id, 42);
    assert_eq!(ev[1].action, PositionAction::Close);
    assert_eq!(ev[1].position_id, 0);
    assert_eq!(ev[1].event_ts, Timestamp(20));
    assert_eq!(ev[1].volume, 2.0); // close sizes the actual (old) book, not the new leg
    assert_eq!(ev[2].action, PositionAction::Sell);
    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));
}

#[test]
fn derive_normal_open_hold_close_lifecycle() {
    let rec = vec![
        pm_row(1, false, 1, 1.0, true),  // open long
        pm_row(2, false, 1, 1.0, true),  // hold (no event)
        pm_row(3, true, 1, 1.0, false),  // close to flat
    ];
    let ev = derive_position_events(&rec, 9);
    assert_eq!(ev.len(), 2);
    assert_eq!(ev[0].action, PositionAction::Buy);
    assert_eq!(ev[0].event_ts, Timestamp(1));
    assert_eq!(ev[1].action, PositionAction::Close);
    assert_eq!(ev[1].event_ts, Timestamp(3));
    assert_eq!(ev[1].position_id, 0);
}

#[test]
fn derive_short_entry_emits_sell() {
    let ev = derive_position_events(&[pm_row(5, false, -1, 1.0, true)], 0);
    assert_eq!(ev.len(), 1);
    assert_eq!(ev[0].action, PositionAction::Sell);
    assert_eq!(ev[0].position_id, 0);
}

#[test]
fn derive_window_end_open_has_no_synthetic_close() {
    // opened and never closed in-window -> open event only, no Close.
    let rec = vec![
        pm_row(1, false, 1, 1.0, true),
        pm_row(2, false, 1, 1.0, true), // still open on the last row
    ];
    let ev = derive_position_events(&rec, 0);
    assert_eq!(ev.len(), 1);
    assert_eq!(ev[0].action, PositionAction::Buy);
}

#[test]
fn derive_empty_record_is_empty_table() {
    let rec: Vec<(Timestamp, Vec<Scalar>)> = vec![];
    assert!(derive_position_events(&rec, 0).is_empty());
}

#[test]
fn derive_position_ids_are_monotonic_across_trades() {
    let rec = vec![
        pm_row(1, false, 1, 1.0, true),   // open id0
        pm_row(2, true, 1, 1.0, false),   // close id0
        pm_row(3, false, -1, 1.0, true),  // open id1 (short)
        pm_row(4, true, -1, 1.0, false),  // close id1
    ];
    let ev = derive_position_events(&rec, 0);
    assert_eq!(ev.len(), 4);
    assert_eq!(ev[0].position_id, 0);
    assert_eq!(ev[1].position_id, 0);
    assert_eq!(ev[2].position_id, 1);
    assert_eq!(ev[3].position_id, 1);
}
```

- [ ] **Step 3: Run the unit tests to verify they fail (RED)**

Run: `cargo test --workspace derive_`
Expected: FAIL — compile error `cannot find function 'derive_position_events' in
this scope` (the function does not exist yet). This is the RED state for a new
pure function (its first reference cannot compile until Step 4).

- [ ] **Step 4: Implement `derive_position_events`**

In `crates/aura-engine/src/report.rs`, immediately after `summarize_r` (which
ends at L218, before the `PositionAction` enum), add:

```rust
/// Derive the broker-independent position-event table from a `PositionManagement`
/// dense record (read positionally, C7 SoA), as the first difference of the
/// executed book (`deal = target - book - in_flight`; `in_flight = 0` for the
/// instant-fill backtest). 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 position still open on the last row emits its
/// open with no synthetic `Close` (the table records actual executed events —
/// unlike `summarize_r`, which force-closes for the R metric).
pub fn derive_position_events(
    record: &[(Timestamp, Vec<Scalar>)],
    instrument_id: i64,
) -> Vec<PositionEvent> {
    // The derive's single-position book (in_flight is structurally 0).
    struct Book {
        position_id: 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 this cycle.
        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 is not 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, volume });
            next_id += 1;
        }
    }
    out
}
```

- [ ] **Step 5: Re-export the function from the crate root**

In `crates/aura-engine/src/lib.rs`, the `pub use report::{…}` block (L64-67) adds
`derive_position_events` to the list (alphabetical-ish, beside `summarize_r`):

```rust
pub use report::{
    derive_position_events, f64_field, join_on_ts, summarize, summarize_r, ColumnarTrace,
    JoinedRow, PositionAction, PositionEvent, RMetrics, RunManifest, RunMetrics, RunReport,
};
```

- [ ] **Step 6: Run the unit tests to verify they pass (GREEN)**

Run: `cargo test --workspace derive_`
Expected: PASS — the 6 `derive_*` tests pass (0 failed).

---

### Task 2: lockstep-guard `direction` pin + agreement E2E test

**Files:**
- Test: `crates/aura-engine/tests/stage1_r_e2e.rs` (consts L35-42; guard test
  L291-324; new E2E test)

- [ ] **Step 1: Add the `DIRECTION` index const + extend the imports**

In `crates/aura-engine/tests/stage1_r_e2e.rs`, beside the re-declared index
consts (L35-42, which already hold `SIZE = 10`), add:

```rust
const DIRECTION: usize = 4;
```

And extend the engine import (L29) from
`use aura_engine::{RMetrics, summarize_r};` to:

```rust
use aura_engine::{PositionAction, RMetrics, derive_position_events, summarize_r};
```

- [ ] **Step 2: Name-pin `direction` in the lockstep guard test**

In `r_col_indices_match_producer_field_layout` (L291-324), beside the existing
`SIZE` assertions (`PM_FIELD_NAMES[SIZE] == "size"`, `PM_RECORD_KINDS[SIZE] ==
ScalarKind::F64`), add the matching `DIRECTION` pin:

```rust
    assert_eq!(PM_FIELD_NAMES[DIRECTION], "direction");
    assert_eq!(PM_RECORD_KINDS[DIRECTION], ScalarKind::I64);
```

- [ ] **Step 3: Add the agreement E2E test**

In `crates/aura-engine/tests/stage1_r_e2e.rs`, add a new test that folds both
`summarize_r` and `derive_position_events` over one recorded ledger (reusing the
existing `run_chain_ledger` / `long_path` helpers and the known
`synthetic_long_then_stop` scenario):

```rust
/// Property: the derived position-event table agrees with the R-metrics fold over
/// the SAME recorded ledger — one Close per closed round-trip, every open either
/// closed in-window or still open at window end, every Close referencing an earlier
/// open, and the caller's instrument_id threaded onto every event.
#[test]
fn derived_event_table_agrees_with_r_metrics_over_one_ledger() {
    let mut stop = FixedStop::new(5.0);
    let ledger =
        run_chain_ledger(&mut stop, &long_path(&[100.0, 104.0, 108.0, 110.0, 102.0, 96.0, 94.0]));
    let m: RMetrics = summarize_r(&ledger, 0.0);
    let events = derive_position_events(&ledger, 7);

    let closes = events.iter().filter(|e| e.action == PositionAction::Close).count() as u64;
    let opens = events
        .iter()
        .filter(|e| matches!(e.action, PositionAction::Buy | PositionAction::Sell))
        .count() as u64;
    // one Close per closed round-trip; a window-end open position has no Close.
    assert_eq!(closes, m.n_trades - m.n_open_at_end);
    // every open is either closed in-window or still open at window end.
    assert_eq!(opens, closes + m.n_open_at_end);
    assert!(opens >= 1, "scenario must open at least one position");

    // referential integrity: every Close references a position_id opened earlier.
    let mut opened: std::collections::HashSet<i64> = std::collections::HashSet::new();
    for e in &events {
        match e.action {
            PositionAction::Buy | PositionAction::Sell => {
                opened.insert(e.position_id);
            }
            PositionAction::Close => assert!(opened.contains(&e.position_id)),
        }
    }
    // the caller-supplied instrument_id is threaded onto every event.
    assert!(events.iter().all(|e| e.instrument_id == 7));
}
```

- [ ] **Step 4: Run the E2E + guard tests to verify they pass**

Run: `cargo test --workspace stage1_r_e2e`
Expected: PASS — all tests in the file pass (0 failed), including the new
`derived_event_table_agrees_with_r_metrics_over_one_ledger` and the extended
`r_col_indices_match_producer_field_layout`.

---

### Task 3: full workspace verification

**Files:** none (verification only)

- [ ] **Step 1: Build the workspace**

Run: `cargo build --workspace`
Expected: clean build, 0 errors.

- [ ] **Step 2: Run the full test suite**

Run: `cargo test --workspace`
Expected: 0 failed across every test binary. The suite gains 7 new tests vs the
pre-cycle baseline (6 `derive_*` unit tests in `report.rs` + 1
`derived_event_table_agrees_with_r_metrics_over_one_ledger` E2E); the guard test
count is unchanged (it gained assertions, not a new `#[test]`). Confirm the new
`derive_*` and `derived_event_table_*` tests are present and passing in the
summary, and that no previously-green test regressed.

- [ ] **Step 3: Lint**

Run: `cargo clippy --workspace --all-targets -- -D warnings`
Expected: clean, 0 warnings. (The `Book` struct stores only the fields the close
path reads — `position_id`, `volume` — so no dead-field lint; `dir` is a local
used only to choose `Buy`/`Sell`.)