Historical query

Preview (historical-mode Cargo feature). The historical namespace exposes the same per-analytic builder shape as the live namespace; the C-ABI bridge that drives an upstream historical query is a documented follow-up. The accessor is opt-in so production FFI builds cannot reach the unwired path.

The historical path runs the same per-analytic dispatch as live against a bounded [start, end] YYYYMMDD date range. The callback fires once per row over the bounded set; the stream ends after the last (contract, date) unit's terminal watermark fires.

Minimal program

Preview. This snippet uses the historical-mode Cargo feature. Over the production C-ABI link (Client::connect) the .on_event call currently fails closed with LinkError::HistoricalUnwired — the historical configuration knob the engine needs is not yet exposed on the scalar wire params and is tracked as a documented follow-up. The accessor is opt-in so production FFI builds cannot reach the unwired path. To run the example today, route through the in-tree test link (Client::with_link + the in-process engine fixture); the in-process path drives the historical engine directly without the C-ABI boundary.

// Cargo.toml:
//   kairos = { version = "0.1", features = ["historical-mode"] }

use kairos::{Client, GreeksRow};

let client = Client::connect(("me@example.com", "secret"))?;

let sub = client
    .historical(20251103, 20251107)
    .greeks(["QQQ"])
    .on_event(|row: &GreeksRow| {
        println!("delta={} iv={}", row.delta, row.implied_vol);
    })?;

// The callback fires per row until the last unit's terminal
// watermark; hold `sub` for the duration, then drop it.
let _ = sub;

Bare symbols

The historical builder accepts an iterator of bare symbols; option contracts within the chain expand at engine resolution time. Per-option (symbol, expiration, right, strike) 4-tuples on the historical arm are tracked as future work; today historical fan-outs operate on whole-chain bare-symbol filters:

.greeks(["QQQ", "SPY", "SPX"])

Termination contract

Every (contract, date) unit emits exactly one terminal watermark frame anchored on (unit_date, resolved_close_ms), whether or not the unit produced any ticks. The callback stops firing once every unit's terminal watermark drains.

Tier entitlement

The historical namespace verifies the per-asset historical tier engine-side before issuing the first upstream call. See Tier quotas for the per-analytic matrix.

See also

• The historical surface.
• Historical builder.