# CostNode trait + shared cost-record contract — Design Spec

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

## Goal

Lift the duplicated cost-node skeleton — shared verbatim by `ConstantCost` and
`VolSlippageCost` and locked-in by convention against `CostSum` — into one
abstraction: a **`CostNode` factor trait** carrying the single per-node
difference (the price-unit cost numerator) and a **generic `CostRunner<F>`** that
owns the shared co-temporality skeleton (geometry gating, R-normalization, the
closed/open charge, the running `cum`, the 3-field emit). One source of truth for
the 3-field cost record (`COST_FIELD_NAMES`/`COST_WIDTH`) replaces the cycle-2
audit-flagged by-convention lockstep with a structural single-source contract.

Hard constraint: **behaviour-preserving.** Every shipped cost node emits
byte-identical output; the node builders produce unchanged schemas (same port
names), so the `main.rs` wiring, the `net_r_equity` seam, and `summarize_r` are
untouched and every existing test stays green verbatim. The deliverable is an
authoring-surface and a maintainability win, not a behaviour change.

This is cycle 3 of the "Cost-model graph (in R)" milestone (#148). The
cost-graph composite-builder is deferred (decision E on #148).

## Architecture

Three layers replace the two near-identical monolith nodes:

1. **The cost-record contract** (`aura-std/src/cost.rs`): `COST_WIDTH = 3` and
   `COST_FIELD_NAMES = ["cost_in_r", "cum_cost_in_r", "open_cost_in_r"]`, plus
   `GEOMETRY_WIDTH = 4` (the PM-geometry input prefix). Mirrors the
   `position_management::{WIDTH, FIELD_NAMES}` precedent (aura-std). Both the
   producer side (the runner's schema helper) and the consumer side (`CostSum`)
   read these — the lockstep is now structural.

2. **The `CostNode` factor trait** (`aura-std/src/cost.rs`): the per-node hook —
   `cost_numerator(&mut self, &Ctx) -> f64` (the round-trip cost in *price
   units*, before R-normalization and before the closed/open gate),
   `extra_inputs() -> Vec<PortSpec>` (default none), `name`, `label`. A factor is
   pure data + one numerator; it holds no running state.

3. **The `CostRunner<F: CostNode>` adapter** (`aura-std/src/cost.rs`): a concrete
   generic node holding the shared mutable state (`cum`, `out: [Cell; COST_WIDTH]`)
   and implementing `Node`. Its `eval` is the co-temporality skeleton, written
   once. It gates **only** on the 4 PM-geometry inputs (so a not-yet-warm factor
   input contributes 0 cost but the row still emits, 1:1 with the PM record),
   divides the factor's numerator by the latched 1R distance, charges on
   close / would-be-charges on open, accumulates `cum`, and emits the triple.

`ConstantCost` and `VolSlippageCost` become thin `CostNode` factors; their
`new()` returns `CostRunner<Self>` (a ready-to-wire `Node`), preserving every
existing call site and unit test. A cost-node `PrimitiveBuilder` is assembled by
a shared `cost_node_builder` helper that prepends the geometry inputs and appends
the standard 3-field output.

**Not a blanket impl.** `impl<T: CostNode> Node for T` is rejected (decision A on
#148): the runner must hold `cum`/`out`, which a trait cannot add; and the recon
found zero blanket impls in `crates/` — the norm is concrete types implementing
`Node`. `impl<F: CostNode> Node for CostRunner<F>` is the idiomatic generic
wrapper and keeps the numerator call inlinable (no vtable on the hot path).

## Concrete code shapes

### Author-facing: writing a new cost node is now one method

A cost-node author writes **only** the numerator — the entire co-temporality
skeleton is the runner's. (Illustrative third node, NOT shipped this cycle; it is
the worked example the acceptance criterion is judged against.)

```rust
use aura_core::Ctx;
use aura_std::{CostNode, CostRunner};

/// A flat half-spread cost per round trip, in price units.
pub struct HalfSpreadCost {
    half_spread: f64,
}

impl HalfSpreadCost {
    pub fn new(half_spread: f64) -> CostRunner<HalfSpreadCost> {
        assert!(half_spread >= 0.0, "HalfSpreadCost half_spread must be >= 0");
        CostRunner::new(HalfSpreadCost { half_spread })
    }
}

impl CostNode for HalfSpreadCost {
    fn name(&self) -> &'static str {
        "HalfSpreadCost"
    }
    fn label(&self) -> String {
        format!("HalfSpreadCost({})", self.half_spread)
    }
    fn cost_numerator(&mut self, _ctx: &Ctx<'_>) -> f64 {
        self.half_spread // price units; the runner divides by latched 1R distance
    }
}
```

That is the whole node: ~16 lines, one numerator method, no `eval`, no `cum`, no
geometry gating, no 3-field schema. Compare the ~90-line per-node skeleton this
cycle removes from each of the two shipped nodes.

### The contract + trait + runner (new `aura-std/src/cost.rs`)

```rust
use aura_core::{
    Cell, Ctx, FieldSpec, Firing, Node, NodeSchema, ParamSpec, PortSpec, PrimitiveBuilder,
    ScalarKind,
};

/// The 3-field cost-in-R record every cost node emits, in slot order — one source
/// of truth, read by both the producer schema (`cost_node_builder`) and the
/// `CostSum` aggregator. Mirrors `position_management::{FIELD_NAMES, WIDTH}`.
pub const COST_WIDTH: usize = 3;
pub const COST_FIELD_NAMES: [&str; COST_WIDTH] =
    ["cost_in_r", "cum_cost_in_r", "open_cost_in_r"];

/// The PM-geometry input prefix every cost node gates on (the co-temporality
/// contract): `closed`, `open`, `entry_price`, `stop_price`. A factor's own extra
/// inputs are appended after these, beginning at slot `GEOMETRY_WIDTH`.
pub const GEOMETRY_WIDTH: usize = 4;

fn geometry_input_ports() -> Vec<PortSpec> {
    vec![
        PortSpec { kind: ScalarKind::Bool, firing: Firing::Any, name: "closed".into() },
        PortSpec { kind: ScalarKind::Bool, firing: Firing::Any, name: "open".into() },
        PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "entry_price".into() },
        PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "stop_price".into() },
    ]
}

fn cost_output_fields() -> Vec<FieldSpec> {
    COST_FIELD_NAMES
        .iter()
        .map(|n| FieldSpec { name: (*n).into(), kind: ScalarKind::F64 })
        .collect()
}

/// A cost factor: the per-round-trip cost in *price units* (the numerator the
/// runner divides by the latched 1R distance). This is the only thing a cost node
/// differs in; the co-temporality skeleton is `CostRunner`'s, shared.
pub trait CostNode: 'static {
    /// Static node-type name (a non-load-bearing debug symbol, C23).
    fn name(&self) -> &'static str;
    /// One-line render label, carrying the identifying param (C23).
    fn label(&self) -> String;
    /// Extra input ports beyond the 4 geometry inputs, appended at slot
    /// `GEOMETRY_WIDTH`. Default: none (a stateless cost like a flat fee).
    fn extra_inputs(&self) -> Vec<PortSpec> {
        Vec::new()
    }
    /// The round-trip cost in price units this cycle, BEFORE R-normalization and
    /// BEFORE the closed/open gate. Reads its extra inputs from `ctx` at
    /// `GEOMETRY_WIDTH + i`; an empty window during warm-up means the factor
    /// contributes 0 (the runner still emits the row — co-temporality).
    fn cost_numerator(&mut self, ctx: &Ctx<'_>) -> f64;
}

/// The shared co-temporality skeleton, wrapping any [`CostNode`] factor into a
/// `Node`. Holds the only running state a cost node needs — the `cum` and the
/// output buffer — so a factor impl stays pure. One home for the contract that
/// was duplicated across `ConstantCost`/`VolSlippageCost` and locked by convention
/// against `CostSum`.
pub struct CostRunner<F: CostNode> {
    factor: F,
    cum: f64,
    out: [Cell; COST_WIDTH],
}

impl<F: CostNode> CostRunner<F> {
    pub fn new(factor: F) -> Self {
        Self { factor, cum: 0.0, out: [Cell::from_f64(0.0); COST_WIDTH] }
    }
}

impl<F: CostNode> Node for CostRunner<F> {
    fn lookbacks(&self) -> Vec<usize> {
        vec![1; GEOMETRY_WIDTH + self.factor.extra_inputs().len()]
    }

    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Cell]> {
        // Gate ONLY on the PM geometry (co-temporality contract): the cost stream
        // stays 1:1 with the executor's PM record. A factor's own not-yet-warm
        // input contributes 0 (handled in `cost_numerator`), it does not withhold.
        let closed_w = ctx.bool_in(0);
        let open_w = ctx.bool_in(1);
        let entry_w = ctx.f64_in(2);
        let stop_w = ctx.f64_in(3);
        if closed_w.is_empty() || open_w.is_empty() || entry_w.is_empty() || stop_w.is_empty() {
            return None;
        }
        let closed = closed_w[0];
        let open = open_w[0];
        let latched = (entry_w[0] - stop_w[0]).abs();
        let numerator = self.factor.cost_numerator(&ctx);
        // Zero latched distance = no valid 1R denominator -> no cost (matches
        // summarize_r's guard). The `numerator / latched` token form is preserved
        // verbatim from the pre-migration nodes for byte-identity (IEEE-754).
        let per = if latched > 0.0 { numerator / latched } else { 0.0 };
        let cost_in_r = if closed { per } else { 0.0 };
        let open_cost_in_r = if open { per } else { 0.0 };
        self.cum += cost_in_r;
        self.out = [
            Cell::from_f64(cost_in_r),
            Cell::from_f64(self.cum),
            Cell::from_f64(open_cost_in_r),
        ];
        Some(&self.out)
    }

    fn label(&self) -> String {
        self.factor.label()
    }
}

/// Assemble a cost-node `PrimitiveBuilder`: the 4 geometry inputs ++ the factor's
/// extra inputs, the standard 3-field cost output, the given params, and a build
/// closure. The single home for the cost-node schema shape.
pub fn cost_node_builder(
    name: &'static str,
    extra_inputs: Vec<PortSpec>,
    params: Vec<ParamSpec>,
    build: impl Fn(&[Cell]) -> Box<dyn Node> + 'static,
) -> PrimitiveBuilder {
    let mut inputs = geometry_input_ports();
    inputs.extend(extra_inputs);
    PrimitiveBuilder::new(name, NodeSchema { inputs, output: cost_output_fields(), params }, build)
}
```

### Before → after: `ConstantCost` (the stateless factor)

```rust
// AFTER — aura-std/src/constant_cost.rs (skeleton removed; factor + thin new/builder)
use aura_core::{Cell, Ctx, ParamSpec, PrimitiveBuilder, ScalarKind};
use crate::cost::{cost_node_builder, CostNode, CostRunner};

pub struct ConstantCost {
    cost_per_trade: f64,
}

impl ConstantCost {
    /// A flat per-trade cost node (the factor wrapped in the shared runner).
    pub fn new(cost_per_trade: f64) -> CostRunner<ConstantCost> {
        assert!(cost_per_trade >= 0.0, "ConstantCost cost_per_trade must be >= 0");
        CostRunner::new(ConstantCost { cost_per_trade })
    }

    pub fn builder() -> PrimitiveBuilder {
        cost_node_builder(
            "ConstantCost",
            Vec::new(), // no extra inputs beyond geometry
            vec![ParamSpec { name: "cost_per_trade".into(), kind: ScalarKind::F64 }],
            |p| Box::new(ConstantCost::new(p[0].f64())),
        )
    }
}

impl CostNode for ConstantCost {
    fn name(&self) -> &'static str {
        "ConstantCost"
    }
    fn label(&self) -> String {
        format!("ConstantCost({})", self.cost_per_trade)
    }
    fn cost_numerator(&mut self, _ctx: &Ctx<'_>) -> f64 {
        self.cost_per_trade
    }
}
```

The existing `ConstantCost` unit-test module is kept **unchanged**: every test
calls `ConstantCost::new(x)` (now a `CostRunner<ConstantCost>`) and `.eval(...)`,
which produces byte-identical output; `new_panics_on_negative_cost` still panics
in `new`. The tests become the migration's verbatim regression guard.

### Before → after: `VolSlippageCost` (the state-dependent factor)

```rust
// AFTER — aura-std/src/vol_slippage_cost.rs
use crate::cost::{cost_node_builder, CostNode, CostRunner, GEOMETRY_WIDTH};

pub struct VolSlippageCost {
    slip_vol_mult: f64,
}

impl VolSlippageCost {
    pub fn new(slip_vol_mult: f64) -> CostRunner<VolSlippageCost> {
        assert!(slip_vol_mult >= 0.0, "VolSlippageCost slip_vol_mult must be >= 0");
        CostRunner::new(VolSlippageCost { slip_vol_mult })
    }

    pub fn builder() -> PrimitiveBuilder {
        cost_node_builder(
            "VolSlippageCost",
            vec![PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "volatility".into() }],
            vec![ParamSpec { name: "slip_vol_mult".into(), kind: ScalarKind::F64 }],
            |p| Box::new(VolSlippageCost::new(p[0].f64())),
        )
    }
}

impl CostNode for VolSlippageCost {
    fn name(&self) -> &'static str {
        "VolSlippageCost"
    }
    fn label(&self) -> String {
        format!("VolSlippageCost({})", self.slip_vol_mult)
    }
    fn extra_inputs(&self) -> Vec<PortSpec> {
        vec![PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "volatility".into() }]
    }
    fn cost_numerator(&mut self, ctx: &Ctx<'_>) -> f64 {
        // Extra input slot 0 (after the 4 geometry inputs).
        let vol_w = ctx.f64_in(GEOMETRY_WIDTH);
        let vol = if vol_w.is_empty() { 0.0 } else { vol_w[0] }; // 0 during proxy warm-up
        self.slip_vol_mult * vol
    }
}
```

Byte-identity: the runner computes `numerator / latched`. For `ConstantCost`,
`numerator = cost_per_trade`, giving `cost_per_trade / latched` (identical to the
original). For `VolSlippageCost`, `numerator = slip_vol_mult * vol`, giving
`(slip_vol_mult * vol) / latched` — left-associative-identical to the original
`slip_vol_mult * vol / latched`. The intermediate multiply rounds to the same f64
whether stored or inlined, so the divide sees the same bits.

`extra_inputs()` is declared in both the trait impl and consulted by `builder()`;
the duplication between `builder()`'s `volatility` PortSpec and `extra_inputs()`
is acceptable (the builder is the param-generic recipe, the trait method is the
runtime lookback driver) — alternatively `builder()` may call `Self::new(0.0)
.extra_inputs()`-style, left to the planner if it reads cleaner.

### Before → after: `CostSum` reads the shared contract

```rust
// AFTER — aura-std/src/cost_sum.rs (local const removed, shared contract used)
use crate::cost::{COST_FIELD_NAMES, COST_WIDTH};
// ...the local `const COST_FIELDS` / `const COST_WIDTH` are deleted; every prior
// reference to `COST_FIELDS` now reads `COST_FIELD_NAMES`. Behaviour and the
// `cost[k].<field>` port names are unchanged (identical string values).
```

### `main.rs`: the third triple duplicate is unified (behaviour-neutral)

`aura-cli/src/main.rs` defines its own `const COST_FIELDS: [&str; 3]` (driving
`COST_SUM_PORTS` interning and the cost-block wiring loops). It is replaced by the
re-exported `aura_std::COST_FIELD_NAMES` (identical values), removing the third
copy of the triple. The wiring, port names, and the C18 golden are unchanged.

## Components

- **`aura-std/src/cost.rs` (new):** `COST_WIDTH`, `COST_FIELD_NAMES`,
  `GEOMETRY_WIDTH`, `geometry_input_ports`, `cost_output_fields`, the `CostNode`
  trait, `CostRunner<F>`, `cost_node_builder`. Owns the co-temporality contract
  and its unit tests (via a test-only stub factor).
- **`aura-std/src/lib.rs`:** `mod cost;` + `pub use cost::{CostNode, CostRunner,
  COST_FIELD_NAMES, COST_WIDTH};` (and `GEOMETRY_WIDTH` if a downstream test
  needs it). `cost_node_builder` stays `pub` for cross-module node authors.
- **`aura-std/src/constant_cost.rs`:** stripped to a `CostNode` factor + thin
  `new`/`builder`; unit tests unchanged.
- **`aura-std/src/vol_slippage_cost.rs`:** same; unit tests unchanged.
- **`aura-std/src/cost_sum.rs`:** local triple const removed, reads
  `crate::cost::{COST_FIELD_NAMES, COST_WIDTH}`; tests unchanged.
- **`aura-cli/src/main.rs`:** local `COST_FIELDS` const replaced by
  `aura_std::COST_FIELD_NAMES`; wiring unchanged.

No changes to `aura-engine`, `aura-analysis`, or the composites crate (they
consume the unchanged schemas). The `aura-engine` E2E helpers call
`ConstantCost::new(c)` / `VolSlippageCost::new(k)` without a type annotation, so
they bind the `CostRunner<_>` return transparently and keep passing.

## Data flow

Unchanged from cycle 2. Per cycle: the executor (`exec`) emits PM geometry
(`closed_this_cycle`, `open`, `entry_price`, `stop_price`); each cost node's
`CostRunner` reads those 4 (slots 0-3) plus its factor's extra inputs (slot 4+,
e.g. `volatility` from the vol proxy); it emits the 3-field cost record; `CostSum`
sums N records per-field; `summarize_r` and the `net_r_equity` LinComb read the
aggregate. The graph topology, the edges, and the recorded traces are identical.

## Error handling

- **Negative param** → `assert!` panic in each node's `new` (unchanged messages,
  unchanged tests).
- **Zero latched distance** → 0 cost (the runner's guard, preserved verbatim).
- **Factor input not warm** → 0 numerator, row still emitted (the co-temporality
  contract, now enforced once in the runner rather than per-node).
- **`CostSum` leg missing** → `None` (unchanged; mode-A as-of join).
- **`GEOMETRY_WIDTH` vs `geometry_input_ports().len()` drift** → guarded by a unit
  test (`geometry_width_matches_port_count`).

## Testing strategy

RED-first where a new assertion is introduced; the migration's safety net is the
existing suite staying green verbatim.

1. **Regression net (unchanged, must stay green):** all `ConstantCost`,
   `VolSlippageCost`, `CostSum` unit tests; the `aura-engine` composition E2E
   (`cost_sum_composes_constant_and_vol_slippage_exactly`,
   `aggregate_net_r_equity_final_sample_agrees_with_summarize_r_net_total`,
   `cost_sum_of_one_is_identity_for_vol_slippage`); the `aura-cli` C18 golden
   (`stage1_r_single_run_output_golden`) byte-identical; the both-costs-compose
   CLI test. These prove behaviour preservation.
2. **New — `cost.rs` runner skeleton tests** (via a test-only `StubCost(f64)`
   factor and a `StubExtra` factor with one extra input): withholds on missing
   geometry; charges `numerator/latched` on close; would-be cost on open not
   charged to `cum`; `cum` accumulates across closes; zero-latched → 0; a factor
   whose extra input is empty contributes 0 but the row still emits.
3. **New — structural-lockstep guard:** assert
   `ConstantCost::builder().schema().output` field names `== COST_FIELD_NAMES`,
   and that `CostSum`'s per-cost input field stems derive from `COST_FIELD_NAMES`
   — proving producer and consumer read one source.
4. **New — `geometry_width_matches_port_count`:** `GEOMETRY_WIDTH ==
   geometry_input_ports().len()`.
5. **Doc-example compile:** the `HalfSpreadCost` author example compiles (a
   `cost.rs` doctest or a `tests/` fixture), proving the author surface is real.

## Acceptance criteria

- The codebase improves measurably (removes ~90 lines of duplicated skeleton per
  shipped node and three copies of the 3-field triple, collapsed to one source) —
  the C10 "one home for cost" spirit, made structural.
- A new cost node is authored as `impl CostNode` with one `cost_numerator` method
  (the `HalfSpreadCost` worked example), no `eval`/`cum`/schema boilerplate.
- No failure class is reintroduced: the cost stream stays co-temporal with the PM
  record (the contract is now enforced once, in the runner), determinism and
  causality are untouched, and every existing test passes verbatim — the C18
  golden byte-identical, the composition identity exact.
- `cargo build --workspace`, `cargo test --workspace`, and
  `cargo clippy --workspace --all-targets -- -D warnings` are clean.