# 01 — Field Definitions
## Endur Projection Methods Framework

This file defines every field used in the Projection Method framework. The Agent must ground all
interpretation and calculation in these definitions and never infer field meaning from general
financial knowledge alone.

---

## 1. Identification Fields

| Field | Type | Description |
|---|---|---|
| `TC_ID` | Text | Unique test case identifier. Format: `TC-001`, `TC-002`, etc. |
| `Method_Name` | Text | Canonical name of the projection method (e.g. X DAYS ARD Event, TMA Argus/Platts). |
| `Method_Name` | Text | Human-readable label for the method (e.g. `X DAYS ARD Event`, `TMA Argus/Platts`). |
| `Scenario` | Text | Description of the specific test scenario (e.g. `TC-A: Normal weekday`, `TC-C: Saturday BOL`). |

---

## 2. Input Fields

### 2.1 BOL_Date (Bill Of Lading Date)
- **Type:** Date (MM/DD/YYYY)
- **Definition:** The physical delivery or event anchor date. Every pricing window calculation starts from this date.
- **Important:** If BOL_Date falls on a non-Good Business Day (weekend or bank holiday), the Non-GBD Roll Rule is applied before any window calculation begins.

### 2.2 BOL_DoW
- **Type:** Text
- **Definition:** Day of week of the BOL_Date (Mon, Tue, Wed, Thu, Fri, Sat, Sun). Used to identify weekend scenarios.

### 2.3 Pricing_Event
- **Type:** Enum
- **Allowed values:**
  - `BOL` — the BOL date is the pricing anchor event.
  - `ARD` — Actual Receipt Date; an alternative event anchor used by some methods.
  - `Cycle Close Date` — used exclusively by CycleSchDt-2.
- **Override behaviour:** If a test case row specifies this field, it overrides the master definition default for that row only.

### 2.4 Non_GBD_Roll_Rule
- **Type:** Enum
- **Definition:** Controls how a BOL_Date that falls on a non-Good Business Day is rolled to produce the Effective BOL before the Pivot Date Offset is applied.
- **Allowed values:**

| Value | Meaning | Roll Direction |
|---|---|---|
| `+SatSunHol` | Following convention — roll forward to next GBD | Forward |
| `-SatSunHol` | Preceding convention — roll backward to previous GBD | Backward |
| `-Sat+Sun+MonHol-Hol` | Token-based (see File 2 Section 4.2) — Saturday rolls **backward** to Friday | Token-based |
| `No Roll` | Date is used as-is regardless of whether it is a GBD | None |

- **Override behaviour:** Can be overridden at the test case row level. If blank in the test row, inherits from Master Definitions.

---

## 3. Projection Method Configuration Fields

These fields define how the pricing window is constructed for a given method. They are stored in the Master Definitions (File 4) and can be overridden per test case.

### 3.1 Reset_Convention
- **Type:** Text / Code
- **Definition:** The convention that links a deal's reset dates to a date sequence or event calendar in Endur. Used to resolve RFIS/RFIE dates and the date sequence for TMA methods.
- **Examples:** `Event Date`, `Flexible Pricing Period`, `arg_trm`, `dmo_one_cme_xxv_minusgbd_three`

### 3.2 Avg_Type
- **Type:** Enum
- **Definition:** Determines how prices are averaged across reset dates within the pricing window.
- **Allowed values:**

| Value | Description | Volume data required? |
|---|---|---|
| `Unweighted` | Simple arithmetic mean of all daily prices | No |
| `Notional Weighted` | Prices weighted by daily notional flowing volume | **Yes** — flag APPROXIMATE if absent |
| `Weighted` | Average weighted by total days in month; non-GBD roll rule applies | Yes |

> **Note:** `Notional Weighted` and `Weighted` are distinct. `Notional Weighted` uses actual flowing volume per day. `Weighted` uses total calendar days in the month as weight.

### 3.3 Pivot_Date_Offset
- **Type:** Integer (GBDs) or symbolic offset expression
- **Definition:** The primary mechanism for computing the Pivot Date from the Effective BOL. Applied AFTER the Non-GBD Roll Rule.

  ```
  Pivot_Date = Effective_BOL + Pivot_Date_Offset
  ```

  **For event-anchored methods** (CycleSchDt-2, X DAYS ARD Event, Event Date Roll Early, Event +Xdays_Roll Fwd, Event -Xdays_Roll Back, X days after Event_Roll Fwd, X days prior Event_Roll Back, Event Date Only): `Pivot_Date_Offset = 0d` — Pivot equals Effective BOL.

  **For month-anchored methods** (EventPMANOWE, EventPMAWE, CMANOWE, CMAWE): the symbolic expression shifts the Pivot to the first day of the target month, making Before=`0d` and After=`1lom` define the full month window correctly regardless of when BOL falls:

  | Method | Pivot_Date_Offset | Pivot resolves to |
  |---|---|---|
  | EventPMANOWE | `1d>-2lom` | First GBD of the **prior** month |
  | EventPMAWE | `1cd>-2lom` | First **calendar day** of the **prior** month |
  | CMANOWE | `1d>-1lom` | First GBD of the **current** month |
  | FX_Ref | `1d>-1lom` | First GBD of the **current** month |
  | CMAWE | `1cd>-1lom` | First **calendar day** of the **current** month |

  **For week-anchored methods** (EventCWA, EventPWA):

  | Method | Pivot_Date_Offset | Pivot resolves to |
  |---|---|---|
  | EventCWA | `0monday` | Monday of the BOL week |
  | EventPWA | `-1monday` | Monday of the **prior** week (week before BOL week) |

  **For date-sequence (TMA) methods** (TMA Argus/Platts, TMA Nymex/CME):

  | Method | Pivot_Date_Offset | Pivot resolves to |
  |---|---|---|
  | TMA Argus/Platts | `1d>-2arg_trm` | First GBD after the previous arg_trm date |
  | TMA Nymex/CME | `1d>-2dmo_one_cme_xxv_minusgbd_three` | First GBD after the previous CME expiry |

  **⚠ Critical distinction — `1d>` vs `1cd>` in Pivot_Date_Offset:**
  - `1d>-1lom` means: go to the first **Good Business Day** after the last day of the prior month → first GBD of current month
  - `1cd>-1lom` means: go to the first **calendar day** after the last day of the prior month → the 1st of the month, even if Saturday

  This prefix (`1d>` or `1cd>`) in the Pivot_Date_Offset expression is **completely independent** of the `Reset_Sym_Date` field. They are different fields with different roles.

  **Why this architecture matters:** By anchoring the Pivot at the start of the pricing period (not at the BOL), the After Offset `1lom` means "last of the **Pivot's** month" — which is always the correct target month end, regardless of when the BOL falls.

  **Note on Event Date Roll Early:** Last Trading Date = -1 is an Endur contract management field (controls contract LTD relative to deal date). The Pivot_Date_Offset for window calculation is `0d`.

### 3.4 Include_Pivot / Exclude_Pivot
- **Type:** Enum — `Include` or `Exclude`
- **Definition:** Controls whether the Pivot Date itself is counted as a reset date.
  - `Include` — Pivot is a reset date and counted in Num_Days.
  - `Exclude` — Pivot is a boundary reference only; NOT a reset date. For date-sequence methods, this means Window_Start = day AFTER the previous sequence boundary (Pivot), not the boundary itself.

### 3.5 Before_Pivot_Offset
- **Type:** Integer (GBDs, typically negative) or `0d`
- **Definition:** Defines the window start relative to the Pivot Date.
  - `0d` — Window starts at the Pivot Date itself. Used by all month-anchored, week-anchored, and TMA methods (where Pivot already points to the window start).
  - `-1d` — Window starts 1 GBD before the Pivot. Used by X DAYS ARD Event.
  - `-2d` — Window starts 2 GBDs before the Pivot. Used by CycleSchDt-2, Event Date Roll Early, Event -Xdays_Roll Back, X days prior Event_Roll Back.

### 3.6 Before_Offset_Roll
- **Type:** Enum — `Before` or `After`
- **Definition:** Controls the **sequencing of operations** when computing the Before Offset — specifically, whether the Before_Pivot_Offset is applied to the **raw (unrolled) Pivot_Date** or to the **already-GBD-rolled Pivot_Date**.

  > *From Endur V26 help: "The Reference Roll specifies whether the Before Offset will be calculated before or after the Pivot Date is rolled to a GBD. This can have a significant effect when the Pivot date falls on a weekend or holiday."*

  | Value | Meaning |
  |---|---|
  | `Before` | Apply Before_Pivot_Offset to the raw Pivot_Date (before GBD roll). All commodity methods use this. |
  | `After` | Apply Before_Pivot_Offset to the Pivot_Date after it has been rolled to a GBD. |

  **⚠ Common misread:** This field does NOT control whether Window_Start rolls forward or backward if it lands on a non-GBD. That direction is determined by the Non-GBD Roll Rule. This field controls the **order of operations** when the Pivot itself is non-GBD.

  **All methods in this framework use `Before`.**

### 3.7 After_Pivot_Offset
- **Type:** Integer (GBDs, typically positive) or Symbolic expression
- **Definition:** Defines the window end relative to the Pivot Date.

  | Expression | Resolves to |
  |---|---|
  | `0d` | Same date as Pivot (single-day window end or event-anchored end) |
  | `+1d` | 1 GBD after the Pivot. Used by X DAYS ARD Event. |
  | `+2d` | 2 GBDs after Pivot. Used by Event Date Roll Early, Event +Xdays_Roll Fwd, X days after Event_Roll Fwd. |
  | `1lom` | Last calendar day of the Pivot's month (then rolls to last GBD). |
  | `1low` | Friday of the Pivot's week. |
  | `-1arg_trm` | The current arg_trm sequence date (window boundary for TMA Argus). |
  | `-1dmo_one_cme_xxv_minusgbd_three` | The current CME expiry date (window boundary for TMA CME). |

### 3.8 After_Offset_Roll
- **Type:** Enum — `Before` or `After`
- **Definition:** Controls the **sequencing of operations** when computing the After Offset — whether the After_Pivot_Offset is applied to the raw Pivot_Date or to the already-GBD-rolled Pivot_Date.

  | Value | Meaning |
  |---|---|
  | `Before` | Apply After_Pivot_Offset to the raw Pivot_Date (before GBD roll). |
  | `After` | Apply After_Pivot_Offset to the Pivot_Date after it has been rolled to a GBD. All commodity methods use this. |

  **All methods in this framework use `After`.**

### 3.9 Nearby
- **Type:** Integer (0, 1, 2, 3, …)
- **Definition:** Specifies **which futures contract expiry** to use as the price reference for each reset date. This is a **price lookup control** — it has no effect on which dates are in the pricing window, on Num_Days, or on Window_Start/Window_End.

  > **IMPORTANT — terminology disambiguation:**
  > "Nearby" in Endur refers to **futures contract proximity** (how many contract expirations forward). It is completely unrelated to geographic or physical proximity. Do not interpret this field in any spatial or location-based sense.

  | Value | Meaning |
  |---|---|
  | `0` | **Spot** — price effective for the reset date itself; no futures contract reference |
  | `1` | **Front month (prompt)** — the nearest upcoming contract expiry as of each reset date |
  | `2` | **Second nearby** — the second upcoming contract expiry |
  | `N` | **Nth nearby** — the Nth upcoming contract expiry |

  Applies universally to ALL projection methods. Controls price lookup ONLY. NOT geographic.

### 3.10 RFI_Shift
- **Type:** Integer (business days)
- **Definition:** Once the RFIS date is resolved via Nearby + date sequence, RFI_Shift offsets it by N business days (positive = forward, negative = backward). Standard value: `0` (no shift) for most methods.

### 3.11 Roll_Boundary_Resets
- **Type:** Enum — `Yes` or `No`
- **Definition:** Controls what happens when a boundary date (Window_Start or Window_End) falls on a non-GBD.

  | Value | Behaviour |
  |---|---|
  | `Yes` (default) | Apply the Non-GBD Roll Rule outward. A non-GBD Window_End rolls to the **next GBD**, even if it crosses into the following month. |
  | `No` | Roll boundary dates **inward** (toward the centre of the window). A non-GBD Window_End rolls to the **previous GBD**, staying within the target month. |

  > *From Endur V26 help: "If the boundary reset is set to No, and if the reset start or reset end date are non-good business days, the system does not roll the non-GBD resets using the Non-GBD Roll Rule. Instead, these non-GBD resets are rolled to be within the date range specified by Before Offset and After Offset."*

  **Example — why CMA/PMA methods use `No`:**
  If March 31 is a Saturday and Roll_Boundary_Resets = Yes, Window_End rolls to Monday April 1 → the window spills into April.
  With Roll_Boundary_Resets = No, Window_End rolls to Friday March 30 → the window stays within March.

  **Methods using `No`:** EventPMANOWE, CMANOWE, FX_Ref.

### 3.12 Reset_Sym_Date
- **Type:** Symbolic — typically `1d`. Also accepts other symbolic dates, date sequences, or Julian dates.
- **Formerly named:** Reset Period

  **Behaviour depends on Reset Convention:**

  **Case 1 — Reset Conv = Event Date** (all PMA, CMA, Weekly, TMA, ARD Event methods):
  Setting this field to `1d` instructs the system to **exclude holidays** from the generated date sequence, using the Reset Holiday Schedule as the holiday calendar. In practice:
  - `1d` → the reset date list contains only Good Business Days (GBDs). Weekends and holidays are automatically excluded.
  - The field and the Reset Holiday Schedule work together: the schedule defines which days are holidays; `1d` tells the system to skip them.

  **Case 2 — Reset Conv = Flexible Pricing Period** (DEEMED DATE only):
  This field defines the **step size for enumerating reset dates** between the pricing period start and end dates provided by the user:
  - `1d` → enumerate GBDs only between start and end
  - `1cd` → enumerate all calendar days between start and end

  **All Commodity Toolset methods use `1d`.** The only exception is DEEMED DATE, which is configurable at deal level.

  **⚠ Critical disambiguation — `1cd` in Pivot_Date_Offset vs Reset_Sym_Date:**
  CMAWE and EventPMAWE have `1cd>-1lom` in their **Pivot_Date_Offset** field. This `1cd>` prefix is part of the pivot calculation syntax — it sets the pivot to the first *calendar* day of the month. It is **not** the Reset_Sym_Date field. The Reset_Sym_Date for these methods is still `1d`. These are two completely separate fields.

### 3.13 Stack_Non_GBD_Volume
- **Type:** Flag — `Yes` or blank/No
- **Definition:** When `Yes`, volume from non-GBD dates at the start of the pricing window is **accumulated (stacked) onto the next adjacent GBD** for the purpose of notional-weighted averaging.

  **Mechanics:**
  When Pivot_Date_Offset = `1cd>X` (first calendar day of a month), the pivot can fall on a Saturday, Sunday, or holiday. In that case:
  - The non-GBD day(s) from the start of the window up to the first GBD are not excluded.
  - Their volume is added to the first GBD's volume for the weighted average calculation.
  - The reset date list (for pricing) still shows only GBDs — the stacking is a volume aggregation, not a date addition.

  **Example:** If June 1 is a Saturday (Pivot for CMAWE), Stack_Non_GBD_Volume = Yes means: June 1 (Sat) + June 2 (Sun) volume stacks onto June 3 (Mon). Monday's weighted average entry carries 3 days of notional volume (Sat + Sun + Mon). Without stacking, that volume would be lost.

  **Used by:** CMAWE and EventPMAWE only — both Notional Weighted methods with `1cd>` pivot.

---

## 4. The Four Mechanisms That Control Reset Date Enumeration

| # | Mechanism | Controls | Affected Methods |
|---|---|---|---|
| 1 | `Reset_Sym_Date = 1d` | Step = GBD only → reset dates are GBDs only (holidays excluded via Reset Holiday Schedule) | All methods (default) |
| 2 | `Pivot_Date_Offset = 1d>X` | Pivot at first GBD of target month | EventPMANOWE, CMANOWE, FX_Ref |
| 3 | `Pivot_Date_Offset = 1cd>X` + `Stack_Non_GBD_Volume = Yes` | Pivot at first calendar day; non-GBD volume stacks onto first GBD | EventPMAWE, CMAWE |
| 4 | `Pivot_Date_Offset = 0monday / -1monday` | Pivot at Monday of current/prior week | EventCWA, EventPWA |

---

## 5. Output / Calculated Fields

### 5.1 Pivot_Date
- **Definition:** `Pivot_Date = Roll(BOL_Date, Non_GBD_Roll_Rule) + Pivot_Date_Offset`
- All window offsets (Before, After) are measured from this date.

### 5.2 Window_Start
- **Definition:** `Window_Start = Pivot_Date + Before_Pivot_Offset`, then apply Before_Offset_Roll if non-GBD.

### 5.3 Window_End
- **Definition:** `Window_End = Pivot_Date + After_Pivot_Offset`, then apply After_Offset_Roll if non-GBD.

### 5.4 Num_Days
- **Definition:** Count of reset dates within [Window_Start, Window_End] inclusive, after applying Include/Exclude Pivot logic.
  - For `Reset_Sym_Date = 1d`: count Good Business Days only.
  - If `Exclude`: remove Pivot_Date from count.

### 5.5 Incl_Pivot
- **Type:** Text — `Yes` / `No`
- **Definition:** Whether the pivot date is included in the reset date set. `Yes` for all methods except X days after Event_Roll Fwd and X days prior Event_Roll Back which use `No`.

### 5.6 Price_Average
- **Definition:** Arithmetic mean of daily prices for all reset dates in the window. Blank if any reset date lacks a price (unless user authorises partial average).

---

## 6. Test Evaluation Fields

| Field | Type | Description |
|---|---|---|
| `Expected_Pivot` | Date | Known-correct pivot date for the test scenario. |
| `Expected_Window_Start` | Date | Known-correct window start date. |
| `Expected_Window_End` | Date | Known-correct window end date. |
| `Expected_Num_Days` | Integer | Known-correct GBD count. |
| `Expected_Incl_Pivot` | Text | Known-correct Include/Exclude pivot flag. |
| `Expected_Behaviour` | Text | Natural language description of what the method should do. |
| `QA_Notes` | Text | Edge cases, known issues, or tester notes. |
| `Status` | Enum | `PASS` — all calculated fields match expected. `FAIL` — one or more differ. `ERROR` — calculation could not be completed. |
| `Run_Notes` | Text | On `FAIL`, describes exactly which fields mismatched and by how much. |

---

## 7. Good Business Day (GBD) Definition

A date is a Good Business Day if and only if:
1. It is a weekday (Monday through Friday), **AND**
2. It is not a bank/exchange holiday listed in the HolidayList.

Non-GBDs are: Saturdays, Sundays, and all listed bank/exchange holidays.

---

## 8. Commodity Toolset Field Guide

This section covers **all 36 Endur Projection Method fields** from the Endur V26 interface, classified by their relevance to the Commodity Toolset. The Agent must use this table to answer user questions about any field — including fields that are not used.

### 8.1 Field Classification Table

| Field | Commodity Status | Fixed Value / Rule |
|---|---|---|
| `ID` | Informational | System-assigned numeric ID |
| `Name` | Informational | Max 32 characters |
| `Reset Period` | **Constrained** | Always `1d` — do not change |
| `Avg Period` | Used | Typically `1d` (one reset per day) |
| `Comp Period` | **Not used** | Not applicable in Commodity Toolset |
| `Reset Conv` | Used | `Event Date`, `arg_trm`, `dmo_one_cme_xxv_minusgbd_three`, `Flexible Pricing Period` |
| `Avg Type` | Used | `Unweighted` or `Notional Weighted` (per method) |
| `Reset Holiday Option` | **Not used** | Not applicable in Commodity Toolset |
| `Last Trading Day` | Informational | Similar to offset to reset roll convention date sequence |
| `Nearby` | Used | Integer — controls price lookup only |
| `Reset Yield Basis` | **Not used** | Financial/interest rate only |
| `Proj Index Tenor` | **Not used** | Financial/interest rate only |
| `Roll Date Option` | **Constrained** | Always **BACKWARD** — do not change (see 8.2) |
| `Reset Against` | **Not used** | Default No — not applicable |
| `Reset Spd` | **Not used** | Default 0.00 — not applicable |
| `Reset Rate Method` | Used | `Normal` or `Daily Average` (see 8.3) |
| `Reset Delay` | **Not used** | Always 0 — should not be used |
| `Non-GBD Roll Rule` | Used | Varies by method — see Master Definitions |
| `Active` | Informational | Enables/disables the method in Endur |
| `Est. Event Date` | Informational | Estimated event date; symbolic date |
| `Pivot Date Offset` | **Critical** | Primary window anchor mechanism |
| `Include Pivot` | Used | Include / Exclude W/H / Exclude |
| `Before Offset` | Used | Window start offset from Pivot |
| `Before Offset Roll` | Used | Sequencing control (Before = use raw Pivot) |
| `After Offset` | Used | Window end offset from Pivot |
| `After Offset Roll` | Used | Sequencing control (After = use GBD-rolled Pivot) |
| `Reset Sym Date` | Used | `1d` for all methods; `1d`/`1cd` for DEEMED DATE |
| `Stack Non GBD Volume` | Used | Yes for CMAWE and EventPMAWE only |
| `Reset Shift` | **Not used** | Would shift all reset dates by N business days — not used here |
| `Roll Boundary Resets` | Used | No for CMA/PMA methods; Yes for others |
| `RFI Shift` | Used | Business day shift on RFIS/RFIE dates |
| `Pricing Event Type` | Used | BOL or Cycle Close Date |
| `Reset Rounding Method` | **Not used** | Read-only None for Commodity Projector |
| `Reset Precision` | **Not used** | Read-only Full for Commodity Projector |
| `Reset Holiday Schedule` | Used | Holiday calendar driving GBD exclusions |
| `Modified` | Informational | Administrative — hidden by default |

### 8.2 Roll Date Option — Always BACKWARD

> *From Endur V26 help: "For the Commodity Toolset, this field should default to BACKWARD and should not be changed."*

When a daily deal ends on a non-GBD, the reset date may roll over to the first GBD of the next month. The Roll Date Option controls the RFIS date behaviour in this situation:
- **BACKWARD** — the RFIS date reflects the last delivery date within the delivery month (does not cross the month boundary).
- **FORWARD** — the RFIS rolls forward, potentially into the next month.

For all Commodity Toolset methods: always BACKWARD.

### 8.3 Reset Rate Method — Normal vs Daily Average

| Option | Description | Typical Use |
|---|---|---|
| `Normal` | Maintains full daily reset history. Recommended for financial deals where invoice reconciliation is required. | Financial swaps, any deal requiring daily price history |
| `Daily Average` | Reduces database overhead. The system expands resets to daily view for current and prior delivery month, then collapses to one record per month (WACOG/WASP) after Rate Fixing is run. For months 2+ in the past with complete history, collapses to a single bullet reset. | Physical trades — client's internal market view, no invoice reconciliation needed |

> **WACOG/WASP:** Weighted Average Cost of Gas Bought / Weighted Average Sales Price — the collapsed monthly price after fixing.

This field does **not impact valuation**. It controls database storage and reset structure granularity only.

### 8.4 Reset Delay — Always 0

> *From Endur V26 help: "This field should not be used and should be kept at a value of 0."*

If ever set to a non-zero value, it would shift all reset dates forward or backward by N business days. In the Commodity Toolset, it is always 0. If a user asks about shifting reset dates, the correct field is **RFI_Shift** (shifts RFIS/RFIE dates) or **Reset_Shift** (would shift reset dates — also not used here).

---

*Source: Endur V26 help documentation (EndurV26/helpdir/HTML_Help/whtdhtml.htm), Projection Methods Definition.xlsx (updated June 2026), PM_Framework_v2 implementation*