1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
//! `ModelParams`, the settable half of the model preset, on the Python
//! surface.
//!
//! ```python
//! eng = pt.Engine(seed=42, universe=u, model="pt-v1") # default
//! custom = pt.ModelParams.from_preset("pt-v1", garch_alpha=0.12)
//! eng = pt.Engine(seed=42, universe=u, model=custom)
//! eng.model_fingerprint # "custom-3fb2c91a", never "pt-v1"
//! ```
//!
//! Immutable after construction (`frozen`), constructed only via
//! `from_preset` / `from_dict`: the fingerprint must not be able to lie.
//! Everything of substance lives in `crate::params`; this file is the
//! boundary.
#![allow(unexpected_cfgs, clippy::useless_conversion)]
use pyo3::prelude::*;
use pyo3::types::PyDict;
use crate::params::{claims_of, settable_names, Inconsistency, ModelParams};
use crate::python::ValidationError;
/// Refuse a vector that breaks an invariant every vector must satisfy.
///
/// Universal, and there is no hatch: `from_preset_unchecked` runs this too.
/// See `ModelParams::invariants` for what is in the set and why.
fn check_invariants(params: &ModelParams) -> PyResult<()> {
params
.invariants()
.map_err(|why| ValidationError::new_err(format!("REFUSED: {why}")))
}
/// Refuse a vector that breaks an identity its own preset claims.
///
/// `base` is the preset the vector was built FROM. If the result is
/// bit-identical to some other shipped preset -- which an arm that reverts a
/// block of dials can be, and `ALL31` in the sectorbisect run is -- then it
/// IS that preset and answers to that preset's claims instead. The
/// fingerprint is only computed when the base's claims already failed, so
/// the consistent path never pays for it.
fn check_claims(params: &ModelParams, base: &str) -> PyResult<()> {
let bad = params.claimed_inconsistencies(claims_of(base));
if bad.is_empty() {
return Ok(());
}
let landed = params.fingerprint();
if landed != base && ModelParams::preset(&landed).is_some() {
let bad = params.claimed_inconsistencies(claims_of(&landed));
if bad.is_empty() {
return Ok(());
}
return Err(refusal(&bad, &landed));
}
Err(refusal(&bad, base))
}
/// The refusal message. It names both sides of every broken identity,
/// because a refusal a reader cannot act on is a refusal they will route
/// around.
fn refusal(bad: &[Inconsistency], owner: &str) -> PyErr {
let lines: Vec<String> = bad.iter().map(|i| format!(" - {i}")).collect();
ValidationError::new_err(format!(
"REFUSED: this vector breaks {} identit{} that {owner} claims about its own \
dials:\n{}\n\nA derived dial moved off its identity is a dial that follows \
from nothing, and a reading taken on one is a reading of the break as much as \
of the arm. Either move the dials the identity depends on so it holds again, \
or build the vector with ModelParams.from_preset_unchecked(...) and record the \
waiver with the measurement.",
bad.len(),
if bad.len() == 1 { "y" } else { "ies" },
lines.join("\n")
))
}
/// An immutable model coefficient set: a shipped preset, or a named
/// deviation from one.
#[pyclass(name = "ModelParams", module = "tradefloor._core", frozen)]
#[derive(Debug, Clone)]
pub struct PyModelParams {
pub inner: ModelParams,
}
#[pymethods]
impl PyModelParams {
/// Build from a shipped preset, with keyword overrides.
///
/// With no name this returns the ENGINE'S DEFAULT preset, the same one
/// `Engine(...)` runs and `model_preset()` reports, so the two cannot
/// disagree. It read `"pt-v1"` through 0.1.4 while engines ran pt-v3,
/// a substitution bug for any caller that used the no-arg form as "the
/// default model". `Checkpoint.of` did, and dropped the model of every
/// pt-v1 run, resuming it as pt-v3.
///
/// `ModelParams.from_preset("pt-v1")` still returns pt-v1 and
/// fingerprints as `"pt-v1"`; any override that changes a bit
/// fingerprints as `"custom-XXXXXXXX"`. Unknown names, non-finite
/// values, the derived-bits coefficients (`mispricing_phi`,
/// `s_phi_tick`, so override `mispricing_half_life_days` instead) and
/// the carried read-only surface are refused by name.
#[staticmethod]
#[pyo3(signature = (name = crate::params::DEFAULT_PRESET_NAME, **overrides))]
fn from_preset(name: &str, overrides: Option<&Bound<'_, PyDict>>) -> PyResult<Self> {
let params = build(name, overrides)?;
check_invariants(¶ms)?;
check_claims(¶ms, name)?;
Ok(Self { inner: params })
}
/// `from_preset`, with the preset's own identity claims NOT checked.
///
/// It is a second constructor rather than a keyword because
/// `**overrides` IS the settable surface, and a flag name would have to
/// be reserved against every future dial forever.
///
/// Probing a derived dial off its identity is a legitimate measurement.
/// It is how the record knows the cap and the ceiling are inert on the
/// pt-v19 vector, and refusing it outright would lose that. This
/// constructor still checks `invariants`. A universal invariant has no
/// hatch, because no reading taken on a vector that breaks one means
/// anything.
///
/// The vector it returns is the same frozen type with the same bits. A
/// caller that uses it should report the waiver beside the number. The
/// arm tooling writes it into the arm record when run with
/// `--allow-identity-break`.
#[staticmethod]
#[pyo3(signature = (name = crate::params::DEFAULT_PRESET_NAME, **overrides))]
fn from_preset_unchecked(
name: &str,
overrides: Option<&Bound<'_, PyDict>>,
) -> PyResult<Self> {
let params = build(name, overrides)?;
check_invariants(¶ms)?;
Ok(Self { inner: params })
}
/// The identities `preset` claims about its own dials, evaluated on this
/// vector: one dict per identity that does not hold, with `dial`,
/// `identity`, `expected`, `actual`, `tolerance` and `claimed_by`, and
/// an empty list when they all do.
///
/// Read-only. A harness writes its result into an arm record after
/// waiving. It takes the preset name because the claims belong to a
/// preset. The cap identity, for one, holds on pt-v19 and on nothing
/// else shipped.
///
/// `preset` defaults to the engine's default preset, pt-v19, which is
/// the default `from_preset` uses, and not to the preset the vector was
/// built from. A vector does not record its base, and a waived one
/// fingerprints as `custom-XXXXXXXX`, so there is nothing to infer it
/// from. A vector built from another preset is therefore checked
/// against pt-v19's claims unless you name its own:
/// `identity_breaks(from_preset("pt-v18"))` returns two rows,
/// `vix_target_shock_cap` and `garch_beta`, each with `claimed_by`
/// `"pt-v19"`, and `identity_breaks(from_preset("pt-v18"), "pt-v18")`
/// returns none, because pt-v18 claims no identities. Pass the name the
/// vector was built from.
#[staticmethod]
#[pyo3(signature = (params, preset = crate::params::DEFAULT_PRESET_NAME))]
fn identity_breaks(
py: Python<'_>,
params: PyRef<'_, PyModelParams>,
preset: &str,
) -> PyResult<PyObject> {
let out = pyo3::types::PyList::empty_bound(py);
for bad in params.inner.claimed_inconsistencies(claims_of(preset)) {
let row = PyDict::new_bound(py);
row.set_item("dial", bad.dial)?;
row.set_item("identity", bad.identity)?;
row.set_item("expected", bad.expected)?;
row.set_item("actual", bad.actual)?;
row.set_item("tolerance", bad.tolerance)?;
row.set_item("claimed_by", bad.claimed_by)?;
out.append(row)?;
}
Ok(out.into())
}
/// Rebuild from a full parameter dictionary, the manifest's embedded
/// form. The inverse of `to_dict`.
///
/// Settable keys are applied as overrides of the shipped preset; a
/// `"name"` key is ignored (the fingerprint is recomputed, never
/// trusted); a read-only or derived key whose value does not match
/// this build is REFUSED, because the dictionary then describes a
/// model this build cannot run.
#[staticmethod]
fn from_dict(values: &Bound<'_, PyDict>) -> PyResult<Self> {
let mut params = ModelParams::preset("pt-v1").expect("shipped");
let settable: Vec<&str> = settable_names();
// Two passes so the half-life override (which rewrites the derived
// bits) is applied before the derived keys are verified.
let mut items: Vec<(String, f64)> = Vec::new();
for (key, value) in values.iter() {
let key: String = key.extract().map_err(|_| {
ValidationError::new_err("model parameter names must be strings".to_string())
})?;
if key == "name" {
continue;
}
let value: f64 = value.extract().map_err(|_| {
ValidationError::new_err(format!("{key} must be a number"))
})?;
items.push((key, value));
}
items.sort_by(|a, b| a.0.cmp(&b.0));
for (key, value) in &items {
if settable.contains(&key.as_str()) {
params = params
.with_override(key, *value)
.map_err(ValidationError::new_err)?;
}
}
for (key, value) in &items {
if settable.contains(&key.as_str()) {
continue;
}
match params.get(key) {
Some(ours) if ours.to_bits() == value.to_bits() => {}
Some(ours) => {
return Err(ValidationError::new_err(format!(
"{key} is {value:?} in this dictionary but {ours:?} \
on this build, and it is not runtime-settable here. \
The dictionary describes a model this build cannot \
run; use the build that wrote it."
)));
}
None => {
return Err(ValidationError::new_err(format!(
"unknown model parameter {key:?} in the dictionary. \
A newer build may have written it; upgrade tradefloor \
rather than dropping it silently."
)));
}
}
}
// The universal invariant and NOT the claim table. `from_dict` is the
// manifest replay path and a manifest that embeds a waived vector must
// replay: a waiver is recorded beside the measurement, not inside the
// dictionary, so `to_dict` round-trips whatever was built. The
// invariant has no hatch anywhere, including here.
//
// After the second pass rather than inside either, because the keys
// apply in sorted order and "market_vol_vix_excursion" sorts before
// "vix_level_identity": a per-key check would fire on the first of a
// pair that is consistent once both have landed. The batch is the unit.
check_invariants(¶ms)?;
Ok(Self { inner: params })
}
/// The full preset surface as a dict: every settable coefficient, the
/// derived-bits pair and the carried read-only constants, plus
/// `"name"`, which is the fingerprint. A manifest embeds this.
pub fn to_dict(&self, py: Python<'_>) -> PyResult<PyObject> {
let out = PyDict::new_bound(py);
out.set_item("name", self.inner.fingerprint())?;
for (name, value) in self.inner.to_pairs() {
out.set_item(name, value)?;
}
Ok(out.into())
}
/// The model's name: a shipped preset's name when bit-identical to it,
/// `custom-XXXXXXXX` otherwise, where the X's are the first 8 hex chars
/// of sha256 over the canonical serialisation (names sorted, values as
/// IEEE-754 bit patterns). A non-shipped preset can never present as a
/// shipped one.
#[getter]
fn fingerprint(&self) -> String {
self.inner.fingerprint()
}
/// The runtime-settable parameter names, sorted. `from_preset` accepts
/// these as keywords.
#[staticmethod]
fn settable() -> Vec<String> {
settable_names().iter().map(|s| s.to_string()).collect()
}
/// The switches left out of the model's digest while they are 0.0,
/// because at zero each one is the model that existed before it. The
/// preset records' `coefficient_digest` follows the same rule, so
/// adding one moves no fingerprint and no record.
#[staticmethod]
fn digest_silent_at_zero() -> Vec<String> {
crate::params::DIGEST_SILENT_AT_ZERO.iter().map(|s| s.to_string()).collect()
}
/// The dials left out of the model's digest while they hold their
/// default, which is not 0.0, as `{name: default}`. Each is read only
/// while a switch silent at zero is set, so at its default it is the
/// model that existed before it. The preset records follow the same
/// rule.
#[staticmethod]
fn digest_silent_at_default() -> std::collections::BTreeMap<String, f64> {
crate::params::DIGEST_SILENT_AT_DEFAULT
.iter()
.map(|(n, v)| (n.to_string(), *v))
.collect()
}
/// Read any parameter as an attribute: `params.garch_alpha`.
fn __getattr__(&self, name: &str) -> PyResult<f64> {
self.inner.get(name).ok_or_else(|| {
pyo3::exceptions::PyAttributeError::new_err(format!(
"ModelParams has no parameter {name:?}"
))
})
}
fn __richcmp__(
&self,
other: &Bound<'_, PyAny>,
op: pyo3::basic::CompareOp,
py: Python<'_>,
) -> PyResult<PyObject> {
let Ok(other) = other.extract::<PyRef<'_, PyModelParams>>() else {
return Ok(py.NotImplemented());
};
// Bit-equality via the digest, the same rule the fingerprint uses.
let equal = self.inner.digest() == other.inner.digest();
match op {
pyo3::basic::CompareOp::Eq => Ok(equal.into_py(py)),
pyo3::basic::CompareOp::Ne => Ok((!equal).into_py(py)),
_ => Ok(py.NotImplemented()),
}
}
fn __repr__(&self) -> String {
let fp = self.inner.fingerprint();
if fp == "pt-v1" {
return "ModelParams(\"pt-v1\")".to_string();
}
// Name the deviations, so a repr in a log says WHAT the custom
// model is rather than only that it is one.
let base = ModelParams::preset("pt-v1").expect("shipped");
let mut diffs: Vec<String> = Vec::new();
for name in settable_names() {
let ours = self.inner.get(name).expect("settable");
let theirs = base.get(name).expect("settable");
if ours.to_bits() != theirs.to_bits() {
diffs.push(format!("{name}={ours}"));
}
}
format!("ModelParams(\"{fp}\", from pt-v1 with {})", diffs.join(", "))
}
}
/// The preset plus its overrides, with nothing checked. Shared by the checked
/// and the unchecked constructor so the two cannot drift apart in how they
/// BUILD, only in what they refuse.
fn build(name: &str, overrides: Option<&Bound<'_, PyDict>>) -> PyResult<ModelParams> {
let mut params = ModelParams::preset(name).ok_or_else(|| {
ValidationError::new_err(crate::python::unknown_preset(name))
})?;
if let Some(kwargs) = overrides {
// Sorted for a deterministic application order. The overrides
// commute, since each writes one independent field and the derived
// recomputation depends only on the final half-life, but a
// deterministic order keeps error messages stable too.
//
// The identity checks run AFTER this loop and not inside it, and that
// is load-bearing: "market_vol_vix_excursion" sorts before
// "vix_level_identity", so an arm turning both on from a preset that
// runs neither would trip a per-override check on the first key and
// pass on the second. The batch is the unit.
let mut keys: Vec<String> = Vec::new();
for key in kwargs.keys() {
keys.push(key.extract::<String>().map_err(|_| {
ValidationError::new_err("model parameter names must be strings".to_string())
})?);
}
keys.sort();
for key in keys {
let value: f64 = kwargs
.get_item(&key)?
.expect("key came from the dict")
.extract()
.map_err(|_| ValidationError::new_err(format!("{key} must be a number")))?;
params = params
.with_override(&key, value)
.map_err(ValidationError::new_err)?;
}
}
Ok(params)
}