claude
73ad87b08a
campaign introspect (--block std::process_ref and --unwired) described
the slot as "content id of a process document" — a plausible bare-string
reading the validator rejects; the required {"content_id":"..."} tagging
appeared in no introspection output (binary-only M1 fieldtest finding).
The SlotKind::ContentRef label and the open-slot hint now lead with the
tagged { content_id } shape. Deliberately narrower than the issue's
suggestion of mirroring std::strategy's { content_id } | { identity_id }
form: validate_campaign refuses an identity_id process ref
(DocFault::ProcessRefMustBeContentId) and a pinned test forbids
advertising it, so the hint states the one accepted key only (C29
honesty; correction minuted on the issue). RED-first: the extended
process_ref_describe_advertises_content_id_only assertion failed against
the old label before the fix.
closes #329
2565 lines
114 KiB
Rust
2565 lines
114 KiB
Rust
//! aura-research — the research-artifact document layer.
|
|
//!
|
|
//! Closed-vocabulary, typed, serialized document types for the methodology
|
|
//! and campaign roles (#188): the **process document** (a named
|
|
//! validation/eval methodology) and the **campaign document** (persisted
|
|
//! experiment intent). This crate owns parsing, intrinsic validation,
|
|
//! canonical serialization + content ids, and the introspection contract.
|
|
//! It is a leaf: no store, no engine access, no execution semantics.
|
|
//!
|
|
//! Control-flow power is the ratified P1 tier: bounded axes over declared
|
|
//! finite sets and structured gates between stages. Shapes outside P1
|
|
//! (variables, recursion, unbounded iteration) are unrepresentable.
|
|
|
|
use std::collections::BTreeMap;
|
|
|
|
use aura_core::{doc_gate, DocGateFault, Scalar, ScalarKind};
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
/// The one accepted document format version.
|
|
pub const FORMAT_VERSION: u32 = 1;
|
|
|
|
/// Document kind tag carried in every document envelope.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "lowercase")]
|
|
pub enum DocKind {
|
|
Process,
|
|
Campaign,
|
|
}
|
|
|
|
/// A process document: a named, versionable validation/eval methodology.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct ProcessDoc {
|
|
pub format_version: u32,
|
|
pub kind: DocKind,
|
|
pub name: String,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub description: Option<String>,
|
|
pub pipeline: Vec<StageBlock>,
|
|
}
|
|
|
|
/// One pipeline stage. Serialize derives the internally-tagged wire form;
|
|
/// Deserialize is hand-rolled (schema-strict) because serde's
|
|
/// `deny_unknown_fields` does not compose with `#[serde(tag = ...)]`.
|
|
#[derive(Clone, Debug, PartialEq, Serialize)]
|
|
#[serde(tag = "block")]
|
|
pub enum StageBlock {
|
|
#[serde(rename = "std::sweep")]
|
|
Sweep {
|
|
/// The selection triple is one optional group: `None` is a
|
|
/// selection-free sweep (permitted only as the terminal stage — the
|
|
/// executor's preflight rule), `Some` carries metric+select(+deflate).
|
|
/// Flattened so the wire form stays the flat `metric`/`select`/
|
|
/// `deflate` slots and every existing document's canonical bytes —
|
|
/// and content id — are unchanged.
|
|
#[serde(flatten, skip_serializing_if = "Option::is_none")]
|
|
selection: Option<SweepSelection>,
|
|
},
|
|
#[serde(rename = "std::gate")]
|
|
Gate { all: Vec<Predicate> },
|
|
#[serde(rename = "std::walk_forward")]
|
|
WalkForward {
|
|
in_sample_ms: u64,
|
|
out_of_sample_ms: u64,
|
|
step_ms: u64,
|
|
mode: WfMode,
|
|
metric: String,
|
|
select: SelectRule,
|
|
},
|
|
#[serde(rename = "std::monte_carlo")]
|
|
MonteCarlo { resamples: u32, block_len: u32 },
|
|
#[serde(rename = "std::generalize")]
|
|
Generalize { metric: String },
|
|
/// Enumerate-only leading stage (#256 fork B): yields the axis grid's
|
|
/// parameter points to the next stage; executes and persists nothing.
|
|
/// Fieldless — the axes live in the campaign document.
|
|
#[serde(rename = "std::grid")]
|
|
Grid,
|
|
}
|
|
|
|
fn is_false(b: &bool) -> bool {
|
|
!*b
|
|
}
|
|
|
|
/// The sweep stage's selection group — all-or-nothing (a half-populated
|
|
/// group is unrepresentable; the schema-strict parser refuses it).
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub struct SweepSelection {
|
|
pub metric: String,
|
|
pub select: SelectRule,
|
|
#[serde(default, skip_serializing_if = "is_false")]
|
|
pub deflate: bool,
|
|
}
|
|
|
|
/// Winner-selection rule; wire strings mirror the CLI `--select` values.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub enum SelectRule {
|
|
#[serde(rename = "argmax")]
|
|
Argmax,
|
|
#[serde(rename = "plateau:mean")]
|
|
PlateauMean,
|
|
#[serde(rename = "plateau:worst")]
|
|
PlateauWorst,
|
|
}
|
|
|
|
/// Walk-forward roll mode — wire form "rolling" | "anchored" (the two shipped
|
|
/// engine `RollMode`s: fixed-length rolling in-sample vs anchored-origin
|
|
/// growing in-sample).
|
|
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub enum WfMode {
|
|
#[serde(rename = "rolling")]
|
|
Rolling,
|
|
#[serde(rename = "anchored")]
|
|
Anchored,
|
|
}
|
|
|
|
/// One typed gate predicate: `<metric> <cmp> <value>`.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct Predicate {
|
|
pub metric: String,
|
|
pub cmp: Cmp,
|
|
pub value: f64,
|
|
}
|
|
|
|
/// Closed comparator set (no equality on floats).
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "lowercase")]
|
|
pub enum Cmp {
|
|
Gt,
|
|
Ge,
|
|
Lt,
|
|
Le,
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Block schema tables — the single source for slot strictness (unknown-slot
|
|
// rejection in `stage_from_value`) AND the introspection contract (the 0105
|
|
// roster lesson). Block *ids* still need declaring at each of the enum
|
|
// `#[serde(rename)]`, `PROCESS_BLOCKS.id`, and the `stage_from_value` match
|
|
// arms — Rust's static enum representation doesn't let a single runtime
|
|
// table drive both the type and the parse dispatch.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Slot value kind, for schema description and CLI presentation.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
pub enum SlotKind {
|
|
MetricName,
|
|
SelectRule,
|
|
/// Walk-forward roll mode (`WfMode` wire strings).
|
|
WfMode,
|
|
Bool,
|
|
U32,
|
|
U64,
|
|
Predicates,
|
|
Strings,
|
|
Windows,
|
|
Ref,
|
|
/// A content-id-only reference (the process ref: `validate_campaign`
|
|
/// refuses an identity id there, so the describe path must not offer one).
|
|
ContentRef,
|
|
Axes,
|
|
EmitKinds,
|
|
/// The closed tap vocabulary (`tap_vocabulary()` entries).
|
|
TapKinds,
|
|
Regimes,
|
|
Costs,
|
|
}
|
|
|
|
/// One typed slot of a block.
|
|
pub struct SlotInfo {
|
|
pub name: &'static str,
|
|
pub kind: SlotKind,
|
|
pub required: bool,
|
|
}
|
|
|
|
/// One block of a document vocabulary: id, one-line doc, typed slots.
|
|
pub struct BlockSchema {
|
|
pub id: &'static str,
|
|
pub doc: &'static str,
|
|
pub slots: &'static [SlotInfo],
|
|
}
|
|
|
|
/// The closed v1 process-stage vocabulary (std set; ids are namespaced).
|
|
pub const PROCESS_BLOCKS: &[BlockSchema] = &[
|
|
BlockSchema {
|
|
id: "std::sweep",
|
|
doc: "evaluate the campaign's axes-space; reduce members to R metrics; \
|
|
optionally select a winner (the selection group metric+select is \
|
|
all-or-nothing; omitted = selection-free, terminal-stage-only)",
|
|
slots: &[
|
|
SlotInfo { name: "metric", kind: SlotKind::MetricName, required: false },
|
|
SlotInfo { name: "select", kind: SlotKind::SelectRule, required: false },
|
|
SlotInfo { name: "deflate", kind: SlotKind::Bool, required: false },
|
|
],
|
|
},
|
|
BlockSchema {
|
|
id: "std::gate",
|
|
doc: "filter survivors by a conjunction of typed metric predicates",
|
|
slots: &[SlotInfo { name: "all", kind: SlotKind::Predicates, required: true }],
|
|
},
|
|
BlockSchema {
|
|
id: "std::walk_forward",
|
|
doc: "rolling in-sample optimize + out-of-sample test",
|
|
slots: &[
|
|
SlotInfo { name: "in_sample_ms", kind: SlotKind::U64, required: true },
|
|
SlotInfo { name: "out_of_sample_ms", kind: SlotKind::U64, required: true },
|
|
SlotInfo { name: "step_ms", kind: SlotKind::U64, required: true },
|
|
SlotInfo { name: "mode", kind: SlotKind::WfMode, required: true },
|
|
SlotInfo { name: "metric", kind: SlotKind::MetricName, required: true },
|
|
SlotInfo { name: "select", kind: SlotKind::SelectRule, required: true },
|
|
],
|
|
},
|
|
BlockSchema {
|
|
id: "std::monte_carlo",
|
|
doc: "R-bootstrap over realised R (terminal annotator): after a \
|
|
walk_forward, ONE bootstrap over its pooled OOS trade series; \
|
|
otherwise one per surviving member; both slots must be > 0 to \
|
|
execute",
|
|
slots: &[
|
|
SlotInfo { name: "resamples", kind: SlotKind::U32, required: true },
|
|
SlotInfo { name: "block_len", kind: SlotKind::U32, required: true },
|
|
],
|
|
},
|
|
BlockSchema {
|
|
id: "std::generalize",
|
|
doc: "cross-instrument worst-case floor (terminal annotator): runs at \
|
|
campaign scope, per (strategy, window) over the cells' nominees; \
|
|
needs >= 2 instruments and an R-expectancy metric to execute",
|
|
slots: &[SlotInfo { name: "metric", kind: SlotKind::MetricName, required: true }],
|
|
},
|
|
BlockSchema {
|
|
id: "std::grid",
|
|
doc: "enumerate the axis grid as parameter points for the next stage \
|
|
(enumerate-only leading stage): executes and persists nothing; \
|
|
legal only as the first stage, immediately before \
|
|
std::walk_forward",
|
|
slots: &[],
|
|
},
|
|
];
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Strict stage parsing (schema-driven).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
fn require_str(
|
|
m: &serde_json::Map<String, serde_json::Value>,
|
|
key: &str,
|
|
block: &str,
|
|
) -> Result<String, String> {
|
|
match m.get(key) {
|
|
Some(serde_json::Value::String(s)) => Ok(s.clone()),
|
|
Some(_) => Err(format!("block {block}: slot \"{key}\" must be a string")),
|
|
None => Err(format!("block {block}: missing required slot \"{key}\"")),
|
|
}
|
|
}
|
|
|
|
fn require_u64(
|
|
m: &serde_json::Map<String, serde_json::Value>,
|
|
key: &str,
|
|
block: &str,
|
|
) -> Result<u64, String> {
|
|
match m.get(key) {
|
|
Some(v) => v
|
|
.as_u64()
|
|
.ok_or_else(|| format!("block {block}: slot \"{key}\" must be a non-negative integer")),
|
|
None => Err(format!("block {block}: missing required slot \"{key}\"")),
|
|
}
|
|
}
|
|
|
|
fn require_u32(
|
|
m: &serde_json::Map<String, serde_json::Value>,
|
|
key: &str,
|
|
block: &str,
|
|
) -> Result<u32, String> {
|
|
let v = require_u64(m, key, block)?;
|
|
u32::try_from(v).map_err(|_| format!("block {block}: slot \"{key}\" out of range"))
|
|
}
|
|
|
|
fn optional_bool(
|
|
m: &serde_json::Map<String, serde_json::Value>,
|
|
key: &str,
|
|
block: &str,
|
|
) -> Result<bool, String> {
|
|
match m.get(key) {
|
|
None => Ok(false),
|
|
Some(serde_json::Value::Bool(b)) => Ok(*b),
|
|
Some(_) => Err(format!("block {block}: slot \"{key}\" must be a bool")),
|
|
}
|
|
}
|
|
|
|
fn select_from(
|
|
m: &serde_json::Map<String, serde_json::Value>,
|
|
block: &str,
|
|
) -> Result<SelectRule, String> {
|
|
let s = require_str(m, "select", block)?;
|
|
// SelectRule's own derived Deserialize (which carries the #[serde(rename)]
|
|
// wire strings) is the type oracle for *parsing*, mirroring
|
|
// kind_tag/scalar_from_bare. The refusal's roster text below is sourced
|
|
// from slot_kind_label(SlotKind::SelectRule) rather than a second
|
|
// hardcoded copy of the three wire strings: CLI describe output and the
|
|
// document refusal stay in sync by construction (add a SelectRule
|
|
// variant, update one string).
|
|
serde_json::from_value(serde_json::Value::String(s.clone())).map_err(|_| {
|
|
let roster =
|
|
slot_kind_label(SlotKind::SelectRule).trim_start_matches("select rule: ");
|
|
format!("block {block}: unknown select rule \"{s}\" (accepted: {roster})")
|
|
})
|
|
}
|
|
|
|
fn mode_from(
|
|
m: &serde_json::Map<String, serde_json::Value>,
|
|
block: &str,
|
|
) -> Result<WfMode, String> {
|
|
let s = require_str(m, "mode", block)?;
|
|
// WfMode's own derived Deserialize (which carries the #[serde(rename)]
|
|
// wire strings) is the type oracle, mirroring select_from: no second
|
|
// hardcoded copy of the two roll-mode wire strings.
|
|
serde_json::from_value(serde_json::Value::String(s.clone()))
|
|
.map_err(|_| format!("block {block}: unknown mode \"{s}\""))
|
|
}
|
|
|
|
fn stage_from_value(v: &serde_json::Value) -> Result<StageBlock, String> {
|
|
let m = v
|
|
.as_object()
|
|
.ok_or_else(|| "a pipeline stage must be an object".to_string())?;
|
|
let id = match m.get("block") {
|
|
Some(serde_json::Value::String(s)) => s.clone(),
|
|
_ => return Err("a pipeline stage must carry a string \"block\" id".to_string()),
|
|
};
|
|
let schema = PROCESS_BLOCKS
|
|
.iter()
|
|
.find(|b| b.id == id)
|
|
.ok_or_else(|| format!("unknown block \"{id}\""))?;
|
|
for key in m.keys() {
|
|
if key != "block" && !schema.slots.iter().any(|s| s.name == key) {
|
|
return Err(format!("block {id}: unknown slot \"{key}\""));
|
|
}
|
|
}
|
|
match id.as_str() {
|
|
"std::sweep" => {
|
|
let has_metric = m.contains_key("metric");
|
|
let has_select = m.contains_key("select");
|
|
let selection = match (has_metric, has_select) {
|
|
(true, true) => Some(SweepSelection {
|
|
metric: require_str(m, "metric", &id)?,
|
|
select: select_from(m, &id)?,
|
|
deflate: optional_bool(m, "deflate", &id)?,
|
|
}),
|
|
(false, false) => {
|
|
if m.contains_key("deflate") {
|
|
return Err(format!(
|
|
"block {id}: slot \"deflate\" needs the selection \
|
|
group (\"metric\" + \"select\")"
|
|
));
|
|
}
|
|
None
|
|
}
|
|
(true, false) => {
|
|
return Err(format!(
|
|
"block {id}: slot \"metric\" without \"select\" — the \
|
|
selection group is all-or-nothing"
|
|
));
|
|
}
|
|
(false, true) => {
|
|
return Err(format!(
|
|
"block {id}: slot \"select\" without \"metric\" — the \
|
|
selection group is all-or-nothing"
|
|
));
|
|
}
|
|
};
|
|
Ok(StageBlock::Sweep { selection })
|
|
}
|
|
"std::gate" => {
|
|
let all = m
|
|
.get("all")
|
|
.ok_or_else(|| format!("block {id}: missing required slot \"all\""))?;
|
|
let all: Vec<Predicate> = serde_json::from_value(all.clone())
|
|
.map_err(|e| format!("block {id}: bad predicate list: {e}"))?;
|
|
Ok(StageBlock::Gate { all })
|
|
}
|
|
"std::walk_forward" => Ok(StageBlock::WalkForward {
|
|
in_sample_ms: require_u64(m, "in_sample_ms", &id)?,
|
|
out_of_sample_ms: require_u64(m, "out_of_sample_ms", &id)?,
|
|
step_ms: require_u64(m, "step_ms", &id)?,
|
|
mode: mode_from(m, &id)?,
|
|
metric: require_str(m, "metric", &id)?,
|
|
select: select_from(m, &id)?,
|
|
}),
|
|
"std::monte_carlo" => Ok(StageBlock::MonteCarlo {
|
|
resamples: require_u32(m, "resamples", &id)?,
|
|
block_len: require_u32(m, "block_len", &id)?,
|
|
}),
|
|
"std::generalize" => Ok(StageBlock::Generalize {
|
|
metric: require_str(m, "metric", &id)?,
|
|
}),
|
|
"std::grid" => Ok(StageBlock::Grid),
|
|
_ => unreachable!("schema membership checked above"),
|
|
}
|
|
}
|
|
|
|
impl<'de> Deserialize<'de> for StageBlock {
|
|
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
|
|
let v = serde_json::Value::deserialize(d)?;
|
|
stage_from_value(&v).map_err(serde::de::Error::custom)
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Parse (envelope-checked).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Parse-level refusals. By-identifier and Display-free: the CLI phrases them.
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub enum DocError {
|
|
NotJson(String),
|
|
BadFormatVersion(u32),
|
|
WrongKind { expected: DocKind },
|
|
Malformed(String),
|
|
}
|
|
|
|
fn check_envelope(v: &serde_json::Value, expected: DocKind) -> Result<(), DocError> {
|
|
let fv = v.get("format_version").and_then(|x| x.as_u64());
|
|
if fv != Some(u64::from(FORMAT_VERSION)) {
|
|
return Err(DocError::BadFormatVersion(fv.unwrap_or(0) as u32));
|
|
}
|
|
let want = match expected {
|
|
DocKind::Process => "process",
|
|
DocKind::Campaign => "campaign",
|
|
};
|
|
match v.get("kind").and_then(|k| k.as_str()) {
|
|
Some(k) if k == want => Ok(()),
|
|
_ => Err(DocError::WrongKind { expected }),
|
|
}
|
|
}
|
|
|
|
/// Parse a process document from text (envelope + strict vocabulary).
|
|
pub fn parse_process(text: &str) -> Result<ProcessDoc, DocError> {
|
|
let v: serde_json::Value =
|
|
serde_json::from_str(text).map_err(|e| DocError::NotJson(e.to_string()))?;
|
|
check_envelope(&v, DocKind::Process)?;
|
|
serde_json::from_value(v).map_err(|e| DocError::Malformed(e.to_string()))
|
|
}
|
|
|
|
/// A campaign document: persisted experiment intent.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct CampaignDoc {
|
|
pub format_version: u32,
|
|
pub kind: DocKind,
|
|
pub name: String,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub description: Option<String>,
|
|
pub data: DataSection,
|
|
/// Structural risk-execution axis: the finite list of stop regimes the
|
|
/// matrix runs each cell under. Absent or empty = one implicit default
|
|
/// regime (the runtime's baked constants). Absent-serializes → content-id
|
|
/// parity for every risk-less document (the `description` precedent).
|
|
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
|
pub risk: Vec<RiskRegime>,
|
|
/// The campaign's cost model (#234): additive components (C10) every
|
|
/// member runs under. Absent or empty = zero costs (`summarize_r`'s
|
|
/// empty-slice baseline: net == gross). Absent-serializes → content-id
|
|
/// parity for every cost-less document (the `risk` precedent above).
|
|
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
|
pub cost: Vec<CostSpec>,
|
|
pub strategies: Vec<StrategyEntry>,
|
|
pub process: ProcessRef,
|
|
pub seed: u64,
|
|
pub presentation: Presentation,
|
|
}
|
|
|
|
/// Structural data axes: which instruments over which windows, plus the
|
|
/// optional per-campaign input-binding overrides (role name -> column name,
|
|
/// #231 — the campaign rebind seam: re-aim a strategy's input roles without
|
|
/// touching its blueprint's content identity). Additive on the
|
|
/// `description`/`risk` precedent: absent-serializes, so binding-less
|
|
/// documents keep their content ids.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct DataSection {
|
|
pub instruments: Vec<String>,
|
|
pub windows: Vec<Window>,
|
|
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
|
|
pub bindings: BTreeMap<String, String>,
|
|
}
|
|
|
|
/// One data window, inclusive epoch-ms bounds (the CLI --from/--to form).
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct Window {
|
|
pub from_ms: i64,
|
|
pub to_ms: i64,
|
|
}
|
|
|
|
/// A strategy under test: an opaque id handle + its tuning axes.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct StrategyEntry {
|
|
#[serde(rename = "ref")]
|
|
pub r#ref: DocRef,
|
|
pub axes: BTreeMap<String, Axis>,
|
|
}
|
|
|
|
/// One tuning axis: the parameter's kind, declared ONCE, plus a finite list
|
|
/// of bare JSON values parsed as that kind. A mixed-kind axis is
|
|
/// unrepresentable by construction (the kind is a property of the
|
|
/// parameter, not of each value — user decision 2026-07-03, #189).
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub struct Axis {
|
|
pub kind: ScalarKind,
|
|
pub values: Vec<Scalar>,
|
|
}
|
|
|
|
/// A protective-stop regime: a serializable, content-addressable mirror of the
|
|
/// runtime `StopRule` structural axis (C10/C20). The sole implemented variant is
|
|
/// the vol-stop; the shipped fixed-stop rule is admitted as a future additive
|
|
/// variant (it runs as a composite today but is not yet campaign-reachable).
|
|
/// Externally tagged so adding `Fixed` is additive — no content-id churn on
|
|
/// stored `Vol` regimes.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields, rename_all = "snake_case")]
|
|
pub enum RiskRegime {
|
|
Vol { length: i64, k: f64 },
|
|
VolTf { period_minutes: i64, length: i64, k: f64 },
|
|
}
|
|
|
|
/// One component of the campaign's cost model (#234): a closed, additive
|
|
/// vocabulary over the shipped C10 cost nodes — components sum (`CostSum`).
|
|
/// Serde field names are the builders' own `ParamSpec` names
|
|
/// (`constant_cost.rs` / `vol_slippage_cost.rs` / `carry_cost.rs`), so the doc
|
|
/// vocabulary conforms to the node vocabulary. Externally tagged so a future
|
|
/// component is additive — no content-id churn on stored components.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields, rename_all = "snake_case")]
|
|
pub enum CostSpec {
|
|
Constant { cost_per_trade: CostValue },
|
|
VolSlippage { slip_vol_mult: CostValue },
|
|
Carry { carry_per_cycle: CostValue },
|
|
}
|
|
|
|
/// One cost knob's value (#260): one number for every cell, or an
|
|
/// instrument-keyed map resolved per cell at member construction. Custom
|
|
/// serde keeps the scalar form byte-identical to the historical bare number
|
|
/// (content-id parity for stored docs — the `Axis` precedent); the map form
|
|
/// is a plain JSON object of numbers (BTreeMap: deterministic key order).
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub enum CostValue {
|
|
Scalar(f64),
|
|
PerInstrument(std::collections::BTreeMap<String, f64>),
|
|
}
|
|
|
|
impl CostValue {
|
|
/// The per-cell value: the scalar, or the instrument's map entry. `None`
|
|
/// only for an uncovered instrument — unreachable after intrinsic
|
|
/// validation; callers refuse with prose rather than defaulting.
|
|
pub fn resolve(&self, instrument: &str) -> Option<f64> {
|
|
match self {
|
|
CostValue::Scalar(v) => Some(*v),
|
|
CostValue::PerInstrument(m) => m.get(instrument).copied(),
|
|
}
|
|
}
|
|
/// Every numeric value the validator finiteness/sign-checks.
|
|
pub fn values(&self) -> Vec<f64> {
|
|
match self {
|
|
CostValue::Scalar(v) => vec![*v],
|
|
CostValue::PerInstrument(m) => m.values().copied().collect(),
|
|
}
|
|
}
|
|
/// The map's key set (empty for a scalar) — the validate cross-check input.
|
|
pub fn instrument_keys(&self) -> Vec<&str> {
|
|
match self {
|
|
CostValue::Scalar(_) => Vec::new(),
|
|
CostValue::PerInstrument(m) => m.keys().map(String::as_str).collect(),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl Serialize for CostValue {
|
|
fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
|
|
match self {
|
|
CostValue::Scalar(v) => v.serialize(s),
|
|
CostValue::PerInstrument(m) => m.serialize(s),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<'de> Deserialize<'de> for CostValue {
|
|
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
|
|
use serde::de::Error as _;
|
|
#[derive(Deserialize)]
|
|
#[serde(untagged)]
|
|
enum Raw {
|
|
Scalar(f64),
|
|
PerInstrument(std::collections::BTreeMap<String, f64>),
|
|
}
|
|
match Raw::deserialize(d)? {
|
|
Raw::Scalar(v) => Ok(CostValue::Scalar(v)),
|
|
Raw::PerInstrument(m) if m.is_empty() => {
|
|
Err(D::Error::custom("instrument map is empty"))
|
|
}
|
|
Raw::PerInstrument(m) => Ok(CostValue::PerInstrument(m)),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Bare wire value of one Scalar (strips the tagged form via Scalar's own
|
|
/// serde as the oracle — no Scalar internals assumed).
|
|
fn scalar_to_bare(s: &Scalar) -> serde_json::Value {
|
|
match serde_json::to_value(s).expect("scalar serializes") {
|
|
serde_json::Value::Object(m) => m.into_values().next().expect("tagged form has one value"),
|
|
v => v,
|
|
}
|
|
}
|
|
|
|
/// The wire tag of a `ScalarKind`, using `ScalarKind`'s own serde as the
|
|
/// oracle (mirrors `scalar_to_bare`: no wire shape assumed, only asked of
|
|
/// serde) rather than re-hardcoding the four tag strings as a second source
|
|
/// of truth for `Scalar`'s variant names.
|
|
fn kind_tag(kind: ScalarKind) -> String {
|
|
match serde_json::to_value(kind).expect("scalar kind serializes") {
|
|
serde_json::Value::String(s) => s,
|
|
other => unreachable!("ScalarKind serializes to a string, got {other}"),
|
|
}
|
|
}
|
|
|
|
/// Parse one bare JSON value as a Scalar of the declared kind, using
|
|
/// Scalar's own serde as the type oracle (an int literal under F64 parses
|
|
/// as F64; a float under I64 refuses).
|
|
fn scalar_from_bare(kind: ScalarKind, v: &serde_json::Value) -> Result<Scalar, String> {
|
|
let tag = kind_tag(kind);
|
|
serde_json::from_value(serde_json::json!({ tag.clone(): v }))
|
|
.map_err(|_| format!("value {v} is not a valid {tag}"))
|
|
}
|
|
|
|
impl Serialize for Axis {
|
|
fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
|
|
use serde::ser::SerializeStruct;
|
|
let mut st = s.serialize_struct("Axis", 2)?;
|
|
st.serialize_field("kind", &self.kind)?;
|
|
let bare: Vec<serde_json::Value> = self.values.iter().map(scalar_to_bare).collect();
|
|
st.serialize_field("values", &bare)?;
|
|
st.end()
|
|
}
|
|
}
|
|
|
|
impl<'de> Deserialize<'de> for Axis {
|
|
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
|
|
use serde::de::Error as _;
|
|
#[derive(Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
struct Raw {
|
|
kind: ScalarKind,
|
|
values: Vec<serde_json::Value>,
|
|
}
|
|
let raw = Raw::deserialize(d)?;
|
|
let values = raw
|
|
.values
|
|
.iter()
|
|
.map(|v| scalar_from_bare(raw.kind, v))
|
|
.collect::<Result<Vec<_>, _>>()
|
|
.map_err(D::Error::custom)?;
|
|
Ok(Axis { kind: raw.kind, values })
|
|
}
|
|
}
|
|
|
|
/// Reference to a content-addressed artifact: by byte-exact content id or
|
|
/// by topological identity id. Externally tagged one-of.
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "snake_case")]
|
|
pub enum DocRef {
|
|
ContentId(String),
|
|
IdentityId(String),
|
|
}
|
|
|
|
/// The campaign's process slot: reference-only, never an inline body.
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct ProcessRef {
|
|
#[serde(rename = "ref")]
|
|
pub r#ref: DocRef,
|
|
}
|
|
|
|
/// Data-level presentation: what to record and emit (never how to render).
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct Presentation {
|
|
pub persist_taps: Vec<String>,
|
|
pub emit: Vec<String>,
|
|
}
|
|
|
|
/// Parse a campaign document from text (envelope + strict fields).
|
|
pub fn parse_campaign(text: &str) -> Result<CampaignDoc, DocError> {
|
|
let v: serde_json::Value =
|
|
serde_json::from_str(text).map_err(|e| DocError::NotJson(e.to_string()))?;
|
|
check_envelope(&v, DocKind::Campaign)?;
|
|
serde_json::from_value(v).map_err(|e| DocError::Malformed(e.to_string()))
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Canonical form + content id — THE hashing primitive (library home; the
|
|
// CLI's content_id/topology_hash delegate here).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Canonical byte form of a process document: omit-defaults JSON in struct
|
|
/// field order, no trailing newline (the blueprint canonical-form recipe).
|
|
pub fn process_to_json(doc: &ProcessDoc) -> String {
|
|
serde_json::to_string(doc).expect("process document serializes")
|
|
}
|
|
|
|
/// Canonical byte form of a campaign document. Value spelling is
|
|
/// normalized: an F64 axis serializes 8 as 8.0, so equivalent spellings
|
|
/// share one content id.
|
|
pub fn campaign_to_json(doc: &CampaignDoc) -> String {
|
|
serde_json::to_string(doc).expect("campaign document serializes")
|
|
}
|
|
|
|
/// SHA-256 hex over canonical bytes — the single content-id primitive.
|
|
pub fn content_id_of(canonical: &str) -> String {
|
|
use sha2::{Digest, Sha256};
|
|
let mut hasher = Sha256::new();
|
|
hasher.update(canonical.as_bytes());
|
|
format!("{:x}", hasher.finalize())
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Intrinsic validation (store-free).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// A shipped metric with its one-line meaning (C29). One carrier — the
|
|
/// #190 guard keeps this list, the RMetrics serde fields, and the CLI
|
|
/// count in lockstep; the doc column adds no fourth roster site.
|
|
pub struct MetricSchema {
|
|
pub id: &'static str,
|
|
pub doc: &'static str,
|
|
}
|
|
|
|
/// The closed declared-metric vocabulary: the scalar field names of the
|
|
/// shipped metrics/selection types (RMetrics + RunMetrics scalars, plus the
|
|
/// FamilySelection annotation scores). Single source for gate/stage checks
|
|
/// and introspection.
|
|
///
|
|
/// Accepted residual: this is a hand-copy of `aura-analysis`'s
|
|
/// `RMetrics`/`RunMetrics`/`FamilySelection` field names, not oracle-guarded
|
|
/// in-crate — this leaf crate deliberately has no `aura-analysis` dependency
|
|
/// (engine/domain separation), so there is no compile-time field pin to
|
|
/// reference here, unlike the block-schema tables above (:105). Same #160/0105
|
|
/// drift class; fails safe in the direction that matters: a metric renamed or
|
|
/// removed upstream surfaces as `DocFault::UnknownMetric` at parse/validation
|
|
/// time, never a silent accept. A cross-crate guard test
|
|
/// (`aura-campaign/tests/metric_vocabulary_e2e.rs`, #190) also enumerates the
|
|
/// shipped scalar fields via serde and goes red on any desync, so a stale
|
|
/// hand-edit here is test-caught rather than silent. Keep this list in sync by
|
|
/// hand when the upstream field sets change (this list stays a hand-copy by
|
|
/// the crate's ratified core-only isolation; #147 single-sourced the rankable
|
|
/// roster elsewhere and the extended #190 guard pins this list's nesting).
|
|
pub fn metric_vocabulary() -> &'static [MetricSchema] {
|
|
&[
|
|
MetricSchema { id: "expectancy_r", doc: "mean realized R per closed trade — the headline E[R]" },
|
|
MetricSchema { id: "win_rate", doc: "fraction of closed trades with positive realized R" },
|
|
MetricSchema { id: "avg_win_r", doc: "mean realized R over winning trades" },
|
|
MetricSchema { id: "avg_loss_r", doc: "mean realized R over losing trades" },
|
|
MetricSchema { id: "profit_factor", doc: "gross winning R divided by absolute gross losing R" },
|
|
MetricSchema { id: "max_r_drawdown", doc: "deepest peak-to-trough decline of the cumulative R curve" },
|
|
MetricSchema { id: "sqn", doc: "System Quality Number: mean R over its std deviation, scaled by trade count" },
|
|
MetricSchema { id: "sqn_normalized", doc: "SQN normalized to a 100-trade basis for n-independent comparison" },
|
|
MetricSchema { id: "net_expectancy_r", doc: "expectancy net of the cost model's per-trade cost in R" },
|
|
MetricSchema { id: "n_trades", doc: "count of closed trades in the run" },
|
|
MetricSchema { id: "n_open_at_end", doc: "positions still open when the run ends" },
|
|
MetricSchema { id: "total_pips", doc: "summed pip result over all closed trades" },
|
|
MetricSchema { id: "max_drawdown", doc: "deepest peak-to-trough decline of the pip equity curve" },
|
|
MetricSchema { id: "bias_sign_flips", doc: "count of sign changes in the strategy's bias stream" },
|
|
MetricSchema { id: "deflated_score", doc: "selection score deflated for multiple testing against the bootstrap null" },
|
|
MetricSchema { id: "overfit_probability", doc: "probability the selected edge is overfit, from the bootstrap null" },
|
|
MetricSchema { id: "neighbourhood_score", doc: "plateau robustness: score aggregated over the param-space neighbourhood" },
|
|
]
|
|
}
|
|
|
|
/// The closed v1 emit vocabulary (data-level presentation outputs).
|
|
pub fn emit_vocabulary() -> &'static [&'static str] {
|
|
&["family_table", "selection_report"]
|
|
}
|
|
|
|
/// A closed-vocabulary persisted-tap slot with its one-line meaning (C29).
|
|
pub struct TapSchema {
|
|
pub id: &'static str,
|
|
pub doc: &'static str,
|
|
}
|
|
|
|
/// The wrap convention's persisted sink names — the closed tap vocabulary
|
|
/// (#201 decision 1). A genuinely new observable becomes a new entry or an
|
|
/// authored sink in the strategy blueprint (C22: the choice of sinks is part
|
|
/// of the experiment) — never an open node-path namespace in the document.
|
|
pub fn tap_vocabulary() -> &'static [TapSchema] {
|
|
&[
|
|
TapSchema { id: "equity", doc: "cumulative pip equity per cycle" },
|
|
TapSchema { id: "exposure", doc: "signed position exposure per cycle" },
|
|
TapSchema { id: "r_equity", doc: "cumulative gross R per cycle" },
|
|
TapSchema { id: "net_r_equity", doc: "cumulative net R per cycle, after the cost model" },
|
|
]
|
|
}
|
|
|
|
/// The closed archive-column vocabulary a campaign `data.bindings` VALUE may
|
|
/// name — the six M1 columns plus `price`, the alias of close. Doc-tier
|
|
/// mirror of the CLI binding module's role->column map (the `tap_vocabulary`
|
|
/// precedent for doc-tier string tables); the CLI pins the two surfaces
|
|
/// against each other in `binding::tests`.
|
|
pub fn binding_column_vocabulary() -> &'static [&'static str] {
|
|
&["open", "high", "low", "close", "price", "spread", "volume"]
|
|
}
|
|
|
|
/// The vocabulary in the refusal-prose register — the alias annotated
|
|
/// instead of listed as a flat column (mirrors the CLI binding module).
|
|
pub fn binding_column_vocabulary_display() -> &'static str {
|
|
"open | high | low | close (alias: price) | spread | volume"
|
|
}
|
|
|
|
/// Intrinsic-validation findings. By-identifier and Display-free.
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub enum DocFault {
|
|
// process side
|
|
EmptyPipeline,
|
|
UnknownMetric { stage: usize, metric: String },
|
|
EmptyConjunction { stage: usize },
|
|
GateFirst,
|
|
GateAfterTerminalStage { stage: usize },
|
|
ZeroWalkForwardLength { stage: usize, field: &'static str },
|
|
// campaign side
|
|
EmptyInstruments,
|
|
DuplicateInstrument { index: usize, instrument: String },
|
|
NoWindow,
|
|
BadWindow { index: usize },
|
|
BadRegime { index: usize },
|
|
BadCost { index: usize },
|
|
CostInstrumentKeys { index: usize, missing: Vec<String>, extra: Vec<String> },
|
|
NoStrategy,
|
|
EmptyAxes { strategy: usize },
|
|
EmptyAxis { strategy: usize, axis: String },
|
|
UnknownEmitKind(String),
|
|
UnknownTap { index: usize, tap: String },
|
|
UnknownBindingColumn { role: String, column: String },
|
|
ProcessRefMustBeContentId,
|
|
/// C29 (#316): a document's optional top-level `description` is present
|
|
/// but fails the shape gate. Absent is never a fault.
|
|
BadDescription { subject: String, fault: DocGateFault },
|
|
}
|
|
|
|
fn is_known_metric(name: &str) -> bool {
|
|
metric_vocabulary().iter().any(|m| m.id == name)
|
|
}
|
|
|
|
/// Intrinsic validation of a process document (P1 constraints included).
|
|
/// Returns ALL findings, not the first.
|
|
pub fn validate_process(doc: &ProcessDoc) -> Vec<DocFault> {
|
|
let mut faults = Vec::new();
|
|
if let Some(desc) = &doc.description
|
|
&& let Err(fault) = doc_gate(&doc.name, desc)
|
|
{
|
|
faults.push(DocFault::BadDescription { subject: doc.name.clone(), fault });
|
|
}
|
|
if doc.pipeline.is_empty() {
|
|
faults.push(DocFault::EmptyPipeline);
|
|
}
|
|
let mut terminal_seen = false;
|
|
for (i, stage) in doc.pipeline.iter().enumerate() {
|
|
match stage {
|
|
StageBlock::Sweep { selection } => {
|
|
if let Some(sel) = selection
|
|
&& !is_known_metric(&sel.metric)
|
|
{
|
|
faults.push(DocFault::UnknownMetric { stage: i, metric: sel.metric.clone() });
|
|
}
|
|
}
|
|
StageBlock::Generalize { metric } => {
|
|
if !is_known_metric(metric) {
|
|
faults.push(DocFault::UnknownMetric { stage: i, metric: metric.clone() });
|
|
}
|
|
}
|
|
StageBlock::WalkForward { in_sample_ms, out_of_sample_ms, step_ms, metric, .. } => {
|
|
if !is_known_metric(metric) {
|
|
faults.push(DocFault::UnknownMetric { stage: i, metric: metric.clone() });
|
|
}
|
|
// WindowRoller::new refuses NonPositiveLength at run time; the
|
|
// doc tier refuses the same zeroes earlier, path-addressed.
|
|
for (field, value) in [
|
|
("in_sample_ms", *in_sample_ms),
|
|
("out_of_sample_ms", *out_of_sample_ms),
|
|
("step_ms", *step_ms),
|
|
] {
|
|
if value == 0 {
|
|
faults.push(DocFault::ZeroWalkForwardLength { stage: i, field });
|
|
}
|
|
}
|
|
}
|
|
StageBlock::Gate { all } => {
|
|
if i == 0 {
|
|
faults.push(DocFault::GateFirst);
|
|
} else if terminal_seen {
|
|
faults.push(DocFault::GateAfterTerminalStage { stage: i });
|
|
}
|
|
if all.is_empty() {
|
|
faults.push(DocFault::EmptyConjunction { stage: i });
|
|
}
|
|
for p in all {
|
|
if !is_known_metric(&p.metric) {
|
|
faults.push(DocFault::UnknownMetric { stage: i, metric: p.metric.clone() });
|
|
}
|
|
}
|
|
}
|
|
StageBlock::MonteCarlo { .. } => {}
|
|
StageBlock::Grid => {}
|
|
}
|
|
if matches!(stage, StageBlock::MonteCarlo { .. } | StageBlock::Generalize { .. }) {
|
|
terminal_seen = true;
|
|
}
|
|
}
|
|
faults
|
|
}
|
|
|
|
/// Intrinsic validation of a campaign document (P1 constraints included).
|
|
/// Returns ALL findings, not the first.
|
|
pub fn validate_campaign(doc: &CampaignDoc) -> Vec<DocFault> {
|
|
let mut faults = Vec::new();
|
|
if let Some(desc) = &doc.description
|
|
&& let Err(fault) = doc_gate(&doc.name, desc)
|
|
{
|
|
faults.push(DocFault::BadDescription { subject: doc.name.clone(), fault });
|
|
}
|
|
if doc.data.instruments.is_empty() {
|
|
faults.push(DocFault::EmptyInstruments);
|
|
}
|
|
let mut seen_instruments = std::collections::BTreeSet::new();
|
|
for (index, instrument) in doc.data.instruments.iter().enumerate() {
|
|
if !seen_instruments.insert(instrument.as_str()) {
|
|
faults.push(DocFault::DuplicateInstrument {
|
|
index,
|
|
instrument: instrument.clone(),
|
|
});
|
|
}
|
|
}
|
|
if doc.data.windows.is_empty() {
|
|
faults.push(DocFault::NoWindow);
|
|
}
|
|
for (i, w) in doc.data.windows.iter().enumerate() {
|
|
if w.from_ms >= w.to_ms {
|
|
faults.push(DocFault::BadWindow { index: i });
|
|
}
|
|
}
|
|
// Binding VALUES parse against the closed column vocabulary here (the
|
|
// structural tier — no blueprint access); binding KEYS are checked against
|
|
// the strategies' input roles in the resolver tier (validate_campaign_refs).
|
|
for (role, column) in &doc.data.bindings {
|
|
if !binding_column_vocabulary().contains(&column.as_str()) {
|
|
faults.push(DocFault::UnknownBindingColumn {
|
|
role: role.clone(),
|
|
column: column.clone(),
|
|
});
|
|
}
|
|
}
|
|
for (i, r) in doc.risk.iter().enumerate() {
|
|
match r {
|
|
RiskRegime::Vol { length, k } => {
|
|
// length < 1 catches 0 and negatives; `k <= 0.0 || k.is_nan()`
|
|
// catches a non-positive or NaN multiplier (clippy-clean vs
|
|
// `!(k > 0.0)`; +inf is unreachable via JSON, so it need not
|
|
// be excluded).
|
|
if *length < 1 || *k <= 0.0 || k.is_nan() {
|
|
faults.push(DocFault::BadRegime { index: i });
|
|
}
|
|
}
|
|
RiskRegime::VolTf { period_minutes, length, k } => {
|
|
if *period_minutes < 1 || *length < 1 || *k <= 0.0 || k.is_nan() {
|
|
faults.push(DocFault::BadRegime { index: i });
|
|
}
|
|
}
|
|
}
|
|
}
|
|
for (i, c) in doc.cost.iter().enumerate() {
|
|
// Every shipped cost node asserts a finite, non-negative price-unit
|
|
// knob (`>= 0`); the doc tier refuses the same bounds earlier,
|
|
// path-addressed (the BadRegime precedent). NaN/inf are unreachable
|
|
// via JSON but refused defensively.
|
|
let value = match c {
|
|
CostSpec::Constant { cost_per_trade } => cost_per_trade,
|
|
CostSpec::VolSlippage { slip_vol_mult } => slip_vol_mult,
|
|
CostSpec::Carry { carry_per_cycle } => carry_per_cycle,
|
|
};
|
|
if value.values().iter().any(|v| !v.is_finite() || *v < 0.0) {
|
|
faults.push(DocFault::BadCost { index: i });
|
|
}
|
|
// #260: an instrument map must cover the campaign's instruments
|
|
// exactly — a missing instrument silently un-costs its cells, an
|
|
// extra key is almost always a symbol typo; both refuse up front.
|
|
let keys = value.instrument_keys();
|
|
if !keys.is_empty() {
|
|
let missing: Vec<String> = doc
|
|
.data
|
|
.instruments
|
|
.iter()
|
|
.filter(|inst| !keys.contains(&inst.as_str()))
|
|
.cloned()
|
|
.collect();
|
|
let extra: Vec<String> = keys
|
|
.iter()
|
|
.filter(|k| !doc.data.instruments.iter().any(|inst| inst == *k))
|
|
.map(|k| k.to_string())
|
|
.collect();
|
|
if !missing.is_empty() || !extra.is_empty() {
|
|
faults.push(DocFault::CostInstrumentKeys { index: i, missing, extra });
|
|
}
|
|
}
|
|
}
|
|
if doc.strategies.is_empty() {
|
|
faults.push(DocFault::NoStrategy);
|
|
}
|
|
for (i, s) in doc.strategies.iter().enumerate() {
|
|
if s.axes.is_empty() {
|
|
faults.push(DocFault::EmptyAxes { strategy: i });
|
|
}
|
|
for (axis, ax) in &s.axes {
|
|
if ax.values.is_empty() {
|
|
faults.push(DocFault::EmptyAxis { strategy: i, axis: axis.clone() });
|
|
}
|
|
}
|
|
}
|
|
if matches!(doc.process.r#ref, DocRef::IdentityId(_)) {
|
|
faults.push(DocFault::ProcessRefMustBeContentId);
|
|
}
|
|
for e in &doc.presentation.emit {
|
|
if !emit_vocabulary().contains(&e.as_str()) {
|
|
faults.push(DocFault::UnknownEmitKind(e.clone()));
|
|
}
|
|
}
|
|
for (i, t) in doc.presentation.persist_taps.iter().enumerate() {
|
|
if !tap_vocabulary().iter().any(|k| k.id == t.as_str()) {
|
|
faults.push(DocFault::UnknownTap { index: i, tap: t.clone() });
|
|
}
|
|
}
|
|
faults
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Introspection contract: enumerate vocabulary, describe a block's typed
|
|
// slots, list a partial document's open slots. The same tables that make
|
|
// parsing strict make a block palette generatable (the litmus test).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// The campaign document's section vocabulary (descriptive: campaign parsing
|
|
/// is derive-strict; this table powers introspection).
|
|
pub const CAMPAIGN_SECTIONS: &[BlockSchema] = &[
|
|
BlockSchema {
|
|
id: "std::data",
|
|
doc: "campaign section: instruments + windows",
|
|
slots: &[
|
|
SlotInfo { name: "instruments", kind: SlotKind::Strings, required: true },
|
|
SlotInfo { name: "windows", kind: SlotKind::Windows, required: true },
|
|
],
|
|
},
|
|
BlockSchema {
|
|
id: "std::risk",
|
|
doc: "campaign section: the structural risk axis — stop regimes the matrix runs each cell under (absent = one default regime)",
|
|
slots: &[SlotInfo { name: "risk", kind: SlotKind::Regimes, required: false }],
|
|
},
|
|
BlockSchema {
|
|
id: "std::cost",
|
|
doc: "campaign section: the cost model — additive components (C10) every member runs under (absent = zero costs; net == gross)",
|
|
slots: &[SlotInfo { name: "cost", kind: SlotKind::Costs, required: false }],
|
|
},
|
|
BlockSchema {
|
|
id: "std::strategy",
|
|
doc: "campaign section: strategy ref (content or identity id) + param axes",
|
|
slots: &[
|
|
SlotInfo { name: "ref", kind: SlotKind::Ref, required: true },
|
|
SlotInfo { name: "axes", kind: SlotKind::Axes, required: true },
|
|
],
|
|
},
|
|
BlockSchema {
|
|
id: "std::process_ref",
|
|
doc: "campaign section: reference to a named process document (content id)",
|
|
slots: &[SlotInfo { name: "ref", kind: SlotKind::ContentRef, required: true }],
|
|
},
|
|
BlockSchema {
|
|
id: "std::presentation",
|
|
doc: "campaign section: taps to persist + tables to emit (data-level only)",
|
|
slots: &[
|
|
SlotInfo { name: "persist_taps", kind: SlotKind::TapKinds, required: true },
|
|
SlotInfo { name: "emit", kind: SlotKind::EmitKinds, required: true },
|
|
],
|
|
},
|
|
];
|
|
|
|
/// Human label for a slot kind (CLI presentation).
|
|
pub fn slot_kind_label(kind: SlotKind) -> &'static str {
|
|
match kind {
|
|
SlotKind::MetricName => "metric name (see metric_vocabulary)",
|
|
SlotKind::SelectRule => "select rule: argmax | plateau:mean | plateau:worst",
|
|
SlotKind::WfMode => "one of: rolling | anchored",
|
|
SlotKind::Bool => "bool",
|
|
SlotKind::U32 => "non-negative integer (u32)",
|
|
SlotKind::U64 => "non-negative integer (u64)",
|
|
SlotKind::Predicates => "list of { metric, cmp: gt|ge|lt|le, value }",
|
|
SlotKind::Strings => "list of strings",
|
|
SlotKind::Windows => "list of { from_ms, to_ms }",
|
|
SlotKind::Ref => "one of { content_id } | { identity_id }",
|
|
SlotKind::ContentRef => "{ content_id }: content id of a process document",
|
|
SlotKind::Axes => "map: param name -> { kind, values }",
|
|
SlotKind::EmitKinds => "list of: family_table | selection_report",
|
|
SlotKind::TapKinds => "list of: equity | exposure | r_equity | net_r_equity",
|
|
SlotKind::Regimes => {
|
|
"list of stop regimes { vol: { length, k } } | { vol_tf: { period_minutes, length, k } }; absent = one default regime"
|
|
}
|
|
SlotKind::Costs => {
|
|
"list of cost components { constant: { cost_per_trade } } | { vol_slippage: { slip_vol_mult } } | { carry: { carry_per_cycle } }; absent = zero costs (net == gross)"
|
|
}
|
|
}
|
|
}
|
|
|
|
/// The process-stage vocabulary (id + doc + slots per block).
|
|
pub fn process_vocabulary() -> &'static [BlockSchema] {
|
|
PROCESS_BLOCKS
|
|
}
|
|
|
|
/// The campaign section vocabulary.
|
|
pub fn campaign_vocabulary() -> &'static [BlockSchema] {
|
|
CAMPAIGN_SECTIONS
|
|
}
|
|
|
|
/// Describe one block by id, searching both vocabularies.
|
|
pub fn describe_block(id: &str) -> Option<&'static BlockSchema> {
|
|
PROCESS_BLOCKS
|
|
.iter()
|
|
.chain(CAMPAIGN_SECTIONS.iter())
|
|
.find(|b| b.id == id)
|
|
}
|
|
|
|
/// One open slot of a partial document.
|
|
#[derive(Clone, Debug, PartialEq, Eq)]
|
|
pub struct OpenSlot {
|
|
/// JSON-ish path, e.g. `process.ref` or `strategies[0].axes.slow`.
|
|
pub path: String,
|
|
/// Short human hint, e.g. "required, one of: content_id, identity_id".
|
|
pub hint: String,
|
|
/// Additional unit/semantics notes rendered as indented sub-lines under
|
|
/// the slot's main line (#265) — additive, so the `hint` string itself
|
|
/// (pinned verbatim by earlier tests) never changes.
|
|
pub notes: Vec<String>,
|
|
}
|
|
|
|
fn open(path: impl Into<String>, hint: impl Into<String>) -> OpenSlot {
|
|
OpenSlot { path: path.into(), hint: hint.into(), notes: Vec::new() }
|
|
}
|
|
|
|
/// Like `open`, but carries additional unit/semantics notes (#265) rendered
|
|
/// as indented sub-lines under the slot — the `hint` string stays exactly as
|
|
/// `open` would have produced it, so sibling tests pinning `hint` verbatim
|
|
/// are unaffected.
|
|
fn open_with_notes(path: impl Into<String>, hint: impl Into<String>, notes: Vec<String>) -> OpenSlot {
|
|
OpenSlot { path: path.into(), hint: hint.into(), notes }
|
|
}
|
|
|
|
/// List the open slots of a (possibly partial) process document. Only the
|
|
/// text being JSON is required; everything else missing is reported as open.
|
|
pub fn open_slots_process(text: &str) -> Result<Vec<OpenSlot>, DocError> {
|
|
let v: serde_json::Value =
|
|
serde_json::from_str(text).map_err(|e| DocError::NotJson(e.to_string()))?;
|
|
let mut slots = Vec::new();
|
|
envelope_open_slots(&v, "process", &mut slots);
|
|
if v.get("name").and_then(|n| n.as_str()).is_none() {
|
|
slots.push(open("name", "required, string"));
|
|
}
|
|
match v.get("pipeline").and_then(|p| p.as_array()) {
|
|
None => slots.push(open("pipeline", "required, list of stage blocks")),
|
|
Some(stages) if stages.is_empty() => {
|
|
slots.push(open("pipeline", "declared empty — a process needs at least one stage"))
|
|
}
|
|
Some(stages) => {
|
|
for (i, stage) in stages.iter().enumerate() {
|
|
let Some(m) = stage.as_object() else {
|
|
slots.push(open(format!("pipeline[{i}]"), "must be a stage object"));
|
|
continue;
|
|
};
|
|
let Some(id) = m.get("block").and_then(|b| b.as_str()) else {
|
|
slots.push(open(format!("pipeline[{i}].block"), "required, block id"));
|
|
continue;
|
|
};
|
|
let Some(schema) = PROCESS_BLOCKS.iter().find(|b| b.id == id) else {
|
|
slots.push(open(format!("pipeline[{i}].block"), format!("unknown block \"{id}\"")));
|
|
continue;
|
|
};
|
|
for s in schema.slots.iter().filter(|s| s.required) {
|
|
if !m.contains_key(s.name) {
|
|
slots.push(open(
|
|
format!("pipeline[{i}].{}", s.name),
|
|
format!("required, {}", slot_kind_label(s.kind)),
|
|
));
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
Ok(slots)
|
|
}
|
|
|
|
/// List the open slots of a (possibly partial) campaign document.
|
|
/// Whether a `ref` slot in a DRAFT reads as open: absent, or one of the two
|
|
/// natural placeholder spellings `{}` / `null` (#195). A draft affordance of
|
|
/// the open-slot probe only — the strict parse tier keeps refusing
|
|
/// placeholders (they are not a valid document form).
|
|
fn ref_slot_is_open(r: Option<&serde_json::Value>) -> bool {
|
|
match r {
|
|
None | Some(serde_json::Value::Null) => true,
|
|
Some(serde_json::Value::Object(m)) => m.is_empty(),
|
|
Some(_) => false,
|
|
}
|
|
}
|
|
|
|
pub fn open_slots_campaign(text: &str) -> Result<Vec<OpenSlot>, DocError> {
|
|
let v: serde_json::Value =
|
|
serde_json::from_str(text).map_err(|e| DocError::NotJson(e.to_string()))?;
|
|
let mut slots = Vec::new();
|
|
envelope_open_slots(&v, "campaign", &mut slots);
|
|
if v.get("name").and_then(|n| n.as_str()).is_none() {
|
|
slots.push(open("name", "required, string"));
|
|
}
|
|
match v.get("data") {
|
|
None => slots.push(open("data", "required section: instruments + windows")),
|
|
Some(d) => {
|
|
if d.get("instruments").and_then(|x| x.as_array()).is_none_or(|a| a.is_empty()) {
|
|
slots.push(open("data.instruments", "required, non-empty list of strings"));
|
|
}
|
|
if d.get("windows").and_then(|x| x.as_array()).is_none_or(|a| a.is_empty()) {
|
|
slots.push(open("data.windows", "required, non-empty list of { from_ms, to_ms }"));
|
|
}
|
|
}
|
|
}
|
|
// The one optional slot the probe lists: the structural risk axis is
|
|
// invisible to a required-slot sweep (#[serde(default)]), which is exactly
|
|
// how it went undiscovered (#216). Absent, empty, or non-array = open.
|
|
let risk_bound = v.get("risk").and_then(|r| r.as_array()).is_some_and(|a| !a.is_empty());
|
|
if !risk_bound {
|
|
slots.push(open_with_notes(
|
|
"risk",
|
|
"optional, list of stop regimes { vol: { length, k } } | { vol_tf: { period_minutes, length, k } }; absent = one default regime",
|
|
vec![
|
|
"vol.length smooths the per-cycle vol estimator; it does not set the stop's timescale.".to_string(),
|
|
"vol.k scales the stop distance (the risk-unit lever).".to_string(),
|
|
"vol_tf computes the same estimator over completed period_minutes buckets: period_minutes IS the stop's timescale; length smooths in buckets; k scales the distance.".to_string(),
|
|
],
|
|
));
|
|
}
|
|
// The optional cost slot, mirroring the risk axis (#216's discoverability
|
|
// lesson applied to #234): absent, empty, or non-array = open.
|
|
let cost_bound = v.get("cost").and_then(|c| c.as_array()).is_some_and(|a| !a.is_empty());
|
|
if !cost_bound {
|
|
slots.push(open_with_notes(
|
|
"cost",
|
|
"optional, list of cost components { constant: { cost_per_trade } } | { vol_slippage: { slip_vol_mult } } | { carry: { carry_per_cycle } }; absent = zero costs (net == gross)",
|
|
vec![
|
|
"constant.cost_per_trade is in price units, not R (charged per close as cost/|entry-stop| in R).".to_string(),
|
|
"vol_slippage.slip_vol_mult is a multiplier on the per-cycle vol estimate (charged in R likewise).".to_string(),
|
|
"carry.carry_per_cycle is in price units per held cycle, not R (accrues over the hold, emitted in R likewise).".to_string(),
|
|
"each knob takes one number for all instruments, or an instrument-keyed map { \"GER40\": 2.0, ... } covering exactly the campaign's instruments.".to_string(),
|
|
],
|
|
));
|
|
}
|
|
match v.get("strategies").and_then(|s| s.as_array()) {
|
|
None => slots.push(open("strategies", "required, non-empty list of { ref, axes }")),
|
|
Some(list) if list.is_empty() => {
|
|
slots.push(open("strategies", "declared empty — a campaign needs at least one strategy"))
|
|
}
|
|
Some(list) => {
|
|
for (i, s) in list.iter().enumerate() {
|
|
if ref_slot_is_open(s.get("ref")) {
|
|
slots.push(open(
|
|
format!("strategies[{i}].ref"),
|
|
"required, one of: content_id, identity_id",
|
|
));
|
|
}
|
|
match s.get("axes").and_then(|a| a.as_object()) {
|
|
None => slots.push(open(
|
|
format!("strategies[{i}].axes"),
|
|
"required, map: param name -> { kind, values }",
|
|
)),
|
|
Some(axes) => {
|
|
for (axis, spec) in axes {
|
|
let empty = spec
|
|
.get("values")
|
|
.and_then(|c| c.as_array())
|
|
.is_none_or(|c| c.is_empty());
|
|
if empty {
|
|
slots.push(open(
|
|
format!("strategies[{i}].axes.{axis}"),
|
|
"axis declared empty — a P1 axis is a non-empty finite set",
|
|
));
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
if ref_slot_is_open(v.get("process").and_then(|p| p.get("ref"))) {
|
|
// deliberately narrower than the strategy-ref hint: validate_campaign
|
|
// refuses an identity_id process ref, so the guide must not offer it.
|
|
// The tagged { content_id } shape is stated explicitly (#329) so the
|
|
// hint cannot be misread as accepting a bare id string.
|
|
slots.push(open("process.ref", "required, { content_id }: content id of a process document"));
|
|
}
|
|
if v.get("seed").and_then(|s| s.as_u64()).is_none() {
|
|
slots.push(open("seed", "required, non-negative integer"));
|
|
}
|
|
if v.get("presentation").is_none() {
|
|
slots.push(open(
|
|
"presentation",
|
|
format!(
|
|
"required section: persist_taps ({}) + emit",
|
|
tap_vocabulary().iter().map(|t| t.id).collect::<Vec<_>>().join(" | ")
|
|
),
|
|
));
|
|
}
|
|
Ok(slots)
|
|
}
|
|
|
|
fn envelope_open_slots(v: &serde_json::Value, kind: &str, slots: &mut Vec<OpenSlot>) {
|
|
if v.get("format_version").and_then(|x| x.as_u64()) != Some(u64::from(FORMAT_VERSION)) {
|
|
slots.push(open("format_version", "required, must be 1"));
|
|
}
|
|
if v.get("kind").and_then(|k| k.as_str()) != Some(kind) {
|
|
slots.push(open("kind", format!("required, must be \"{kind}\"")));
|
|
}
|
|
// C29 (#323): the description slot is enumerable like every other
|
|
// envelope slot — optional, so only listed while absent.
|
|
if v.get("description").is_none() {
|
|
slots.push(open(
|
|
"description",
|
|
"optional, string — a one-line meaning (C29-gated when present)",
|
|
));
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
pub(crate) const PROCESS_FIXTURE: &str = r#"{
|
|
"format_version": 1,
|
|
"kind": "process",
|
|
"name": "wf-deflated-screen",
|
|
"description": "Sweep, keep only deflated-positive candidates, then walk-forward.",
|
|
"pipeline": [
|
|
{ "block": "std::sweep", "metric": "net_expectancy_r", "select": "plateau:worst", "deflate": true },
|
|
{ "block": "std::gate", "all": [
|
|
{ "metric": "net_expectancy_r", "cmp": "gt", "value": 0.0 },
|
|
{ "metric": "overfit_probability", "cmp": "lt", "value": 0.1 } ] },
|
|
{ "block": "std::walk_forward", "in_sample_ms": 4000, "out_of_sample_ms": 1000,
|
|
"step_ms": 1000, "mode": "rolling", "metric": "net_expectancy_r", "select": "argmax" }
|
|
]
|
|
}"#;
|
|
|
|
#[test]
|
|
fn process_fixture_parses_to_typed_stages() {
|
|
let doc = parse_process(PROCESS_FIXTURE).expect("fixture parses");
|
|
assert_eq!(doc.format_version, 1);
|
|
assert_eq!(doc.kind, DocKind::Process);
|
|
assert_eq!(doc.name, "wf-deflated-screen");
|
|
assert_eq!(doc.pipeline.len(), 3);
|
|
match &doc.pipeline[0] {
|
|
StageBlock::Sweep { selection } => {
|
|
let sel = selection.as_ref().expect("fixture sweep carries a selection");
|
|
assert_eq!(sel.metric, "net_expectancy_r");
|
|
assert_eq!(sel.select, SelectRule::PlateauWorst);
|
|
assert!(sel.deflate);
|
|
}
|
|
other => panic!("stage 0 is not a sweep: {other:?}"),
|
|
}
|
|
match &doc.pipeline[1] {
|
|
StageBlock::Gate { all } => {
|
|
assert_eq!(all.len(), 2);
|
|
assert_eq!(all[0].cmp, Cmp::Gt);
|
|
}
|
|
other => panic!("stage 1 is not a gate: {other:?}"),
|
|
}
|
|
match &doc.pipeline[2] {
|
|
StageBlock::WalkForward {
|
|
in_sample_ms,
|
|
out_of_sample_ms,
|
|
step_ms,
|
|
mode,
|
|
metric,
|
|
select,
|
|
} => {
|
|
assert_eq!(*in_sample_ms, 4000);
|
|
assert_eq!(*out_of_sample_ms, 1000);
|
|
assert_eq!(*step_ms, 1000);
|
|
assert_eq!(*mode, WfMode::Rolling);
|
|
assert_eq!(metric, "net_expectancy_r");
|
|
assert_eq!(*select, SelectRule::Argmax);
|
|
}
|
|
other => panic!("stage 2 is not a walk_forward: {other:?}"),
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn process_parse_refuses_bad_envelope_and_unknown_vocabulary() {
|
|
// wrong format_version
|
|
let bad_fv = PROCESS_FIXTURE.replacen("\"format_version\": 1", "\"format_version\": 2", 1);
|
|
assert_eq!(parse_process(&bad_fv), Err(DocError::BadFormatVersion(2)));
|
|
// wrong kind
|
|
let bad_kind = PROCESS_FIXTURE.replacen("\"kind\": \"process\"", "\"kind\": \"campaign\"", 1);
|
|
assert_eq!(
|
|
parse_process(&bad_kind),
|
|
Err(DocError::WrongKind { expected: DocKind::Process })
|
|
);
|
|
// unknown block id
|
|
let bad_block = PROCESS_FIXTURE.replacen("std::sweep", "std::sweeep", 1);
|
|
let err = parse_process(&bad_block).expect_err("unknown block refused");
|
|
assert!(matches!(err, DocError::Malformed(msg) if msg.contains("unknown block")));
|
|
// unknown slot on a known block
|
|
let bad_slot = PROCESS_FIXTURE.replacen("\"deflate\": true", "\"deflaate\": true", 1);
|
|
let err = parse_process(&bad_slot).expect_err("unknown slot refused");
|
|
assert!(matches!(err, DocError::Malformed(msg) if msg.contains("unknown slot")));
|
|
// unknown select rule
|
|
let bad_select = PROCESS_FIXTURE.replacen("plateau:worst", "plateau:median", 1);
|
|
let err = parse_process(&bad_select).expect_err("unknown select refused");
|
|
assert!(matches!(err, DocError::Malformed(msg) if msg.contains("unknown select rule")));
|
|
// top-level unknown field (derive deny_unknown_fields)
|
|
let extra = PROCESS_FIXTURE.replacen("\"name\":", "\"nam3\": \"x\", \"name\":", 1);
|
|
assert!(matches!(parse_process(&extra), Err(DocError::Malformed(_))));
|
|
// not JSON at all
|
|
assert!(matches!(parse_process("not json"), Err(DocError::NotJson(_))));
|
|
}
|
|
|
|
/// #301 (fieldtest cycle-300 df_3): the unknown-select-rule refusal must
|
|
/// teach the accepted vocabulary, not just refuse — an author who learned
|
|
/// bare `plateau` at the CLI pastes it into a document and needs the
|
|
/// roster (argmax | plateau:mean | plateau:worst) in the refusal prose to
|
|
/// self-serve the fix. The schema stays strict: bare "plateau" remains
|
|
/// refused in documents (#300 F7 — it is a CLI-only argv alias), and the
|
|
/// prose stays sparse — the roster only, no alias-bridging sentence.
|
|
#[test]
|
|
fn unknown_select_rule_refusal_enumerates_accepted_rules() {
|
|
let bare_plateau = PROCESS_FIXTURE.replacen("plateau:worst", "plateau", 1);
|
|
let err =
|
|
parse_process(&bare_plateau).expect_err("bare plateau stays refused in documents");
|
|
let DocError::Malformed(msg) = err else {
|
|
panic!("expected DocError::Malformed, got {err:?}");
|
|
};
|
|
// The existing contract survives: the offending value stays named, quoted.
|
|
assert!(
|
|
msg.contains("unknown select rule \"plateau\""),
|
|
"offending value no longer named: {msg}"
|
|
);
|
|
// The new behaviour: the refusal enumerates the accepted rules.
|
|
for accepted in ["argmax", "plateau:mean", "plateau:worst"] {
|
|
assert!(
|
|
msg.contains(accepted),
|
|
"accepted rule {accepted:?} not enumerated in the refusal: {msg}"
|
|
);
|
|
}
|
|
// Precise and sparse: the roster alone rescues the paste case — no
|
|
// alias-hint sentence bridging plateau -> plateau:mean.
|
|
assert!(!msg.contains("alias"), "refusal grew an alias hint: {msg}");
|
|
}
|
|
|
|
/// The refusal derives its roster from slot_kind_label by trimming the
|
|
/// "select rule: " prefix. That trim is a positional contract: if the
|
|
/// label's wording ever drifts, trim_start_matches degrades to a no-op
|
|
/// and the refusal grows a redundant prefix without any test noticing.
|
|
/// This pin makes that drift loud.
|
|
#[test]
|
|
fn select_rule_label_keeps_the_prefix_the_refusal_trims() {
|
|
assert!(
|
|
slot_kind_label(SlotKind::SelectRule).starts_with("select rule: "),
|
|
"slot_kind_label(SelectRule) no longer starts with \"select rule: \" — \
|
|
update select_from's roster derivation alongside the label"
|
|
);
|
|
}
|
|
|
|
pub(crate) const CAMPAIGN_FIXTURE: &str = r#"{
|
|
"format_version": 1,
|
|
"kind": "campaign",
|
|
"name": "ger40-momentum-screen",
|
|
"description": "GER40 momentum screen over the fast/slow SMA grid.",
|
|
"data": {
|
|
"instruments": ["GER40"],
|
|
"windows": [ { "from_ms": 1704067200000, "to_ms": 1719792000000 } ]
|
|
},
|
|
"strategies": [
|
|
{ "ref": { "content_id": "9f3a" },
|
|
"axes": { "fast": { "kind": "I64", "values": [8, 12, 16] },
|
|
"slow": { "kind": "I64", "values": [21, 34] } } }
|
|
],
|
|
"process": { "ref": { "content_id": "4e2d" } },
|
|
"seed": 1,
|
|
"presentation": {
|
|
"persist_taps": ["net_r_equity"],
|
|
"emit": ["family_table", "selection_report"]
|
|
}
|
|
}"#;
|
|
|
|
#[test]
|
|
fn campaign_fixture_parses_with_axis_level_kind() {
|
|
let doc = parse_campaign(CAMPAIGN_FIXTURE).expect("fixture parses");
|
|
assert_eq!(doc.kind, DocKind::Campaign);
|
|
assert_eq!(doc.data.instruments, vec!["GER40".to_string()]);
|
|
let s = &doc.strategies[0];
|
|
assert_eq!(s.r#ref, DocRef::ContentId("9f3a".into()));
|
|
let fast = &s.axes["fast"];
|
|
assert_eq!(fast.kind, ScalarKind::I64);
|
|
assert_eq!(fast.values, vec![Scalar::I64(8), Scalar::I64(12), Scalar::I64(16)]);
|
|
assert_eq!(doc.process.r#ref, DocRef::ContentId("4e2d".into()));
|
|
// an int literal under an F64 axis parses AS F64 (kind is the oracle)
|
|
let f64_axis: Axis =
|
|
serde_json::from_str(r#"{ "kind": "F64", "values": [1, 2.5] }"#).expect("parses");
|
|
assert_eq!(f64_axis.values, vec![Scalar::F64(1.0), Scalar::F64(2.5)]);
|
|
}
|
|
|
|
/// Axis's hand-rolled Serialize strips the tagged Scalar wire form down
|
|
/// to bare values (scalar_to_bare), and Deserialize re-parses those bare
|
|
/// values back through the declared kind (scalar_from_bare) — this must
|
|
/// round-trip exactly, and the wire shape must actually be bare (no
|
|
/// per-value `{"I64": ...}` tag leaking through).
|
|
#[test]
|
|
fn axis_serializes_to_bare_values_and_round_trips() {
|
|
let axis = Axis {
|
|
kind: ScalarKind::I64,
|
|
values: vec![Scalar::I64(8), Scalar::I64(12), Scalar::I64(16)],
|
|
};
|
|
let json = serde_json::to_value(&axis).expect("axis serializes");
|
|
assert_eq!(json, serde_json::json!({ "kind": "I64", "values": [8, 12, 16] }));
|
|
let round_tripped: Axis = serde_json::from_value(json).expect("bare json round-trips");
|
|
assert_eq!(round_tripped, axis);
|
|
}
|
|
|
|
#[test]
|
|
fn campaign_refuses_inline_process_and_kindless_axes() {
|
|
// an inline process body in the ref slot must refuse to parse
|
|
let inline = CAMPAIGN_FIXTURE.replacen(
|
|
r#""process": { "ref": { "content_id": "4e2d" } }"#,
|
|
r#""process": { "ref": { "pipeline": [] } }"#,
|
|
1,
|
|
);
|
|
assert!(matches!(parse_campaign(&inline), Err(DocError::Malformed(_))));
|
|
// an inline body BESIDE the ref must refuse too (deny_unknown_fields)
|
|
let beside = CAMPAIGN_FIXTURE.replacen(
|
|
r#""process": { "ref": { "content_id": "4e2d" } }"#,
|
|
r#""process": { "ref": { "content_id": "4e2d" }, "pipeline": [] }"#,
|
|
1,
|
|
);
|
|
assert!(matches!(parse_campaign(&beside), Err(DocError::Malformed(_))));
|
|
// a kindless bare array is not an axis
|
|
let bare = CAMPAIGN_FIXTURE.replacen(
|
|
r#"{ "kind": "I64", "values": [8, 12, 16] }"#,
|
|
"[8, 12, 16]",
|
|
1,
|
|
);
|
|
assert!(matches!(parse_campaign(&bare), Err(DocError::Malformed(_))));
|
|
// a tagged cell inside values is not a bare value
|
|
let tagged = CAMPAIGN_FIXTURE.replacen("[8, 12, 16]", r#"[{"I64": 8}]"#, 1);
|
|
assert!(matches!(parse_campaign(&tagged), Err(DocError::Malformed(_))));
|
|
// a float under an I64 axis refuses
|
|
let float_in_i64 = CAMPAIGN_FIXTURE.replacen("[8, 12, 16]", "[8.5]", 1);
|
|
assert!(matches!(parse_campaign(&float_in_i64), Err(DocError::Malformed(_))));
|
|
// wrong kind envelope
|
|
let bad_kind = CAMPAIGN_FIXTURE.replacen("\"kind\": \"campaign\"", "\"kind\": \"process\"", 1);
|
|
assert_eq!(
|
|
parse_campaign(&bad_kind),
|
|
Err(DocError::WrongKind { expected: DocKind::Campaign })
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn process_canonical_form_is_pinned_and_id_stable() {
|
|
let doc = parse_process(PROCESS_FIXTURE).unwrap();
|
|
let canonical = process_to_json(&doc);
|
|
let golden = concat!(
|
|
r#"{"format_version":1,"kind":"process","name":"wf-deflated-screen","#,
|
|
r#""description":"Sweep, keep only deflated-positive candidates, then walk-forward.","#,
|
|
r#""pipeline":[{"block":"std::sweep","metric":"net_expectancy_r","select":"plateau:worst","deflate":true},"#,
|
|
r#"{"block":"std::gate","all":[{"metric":"net_expectancy_r","cmp":"gt","value":0.0},"#,
|
|
r#"{"metric":"overfit_probability","cmp":"lt","value":0.1}]},"#,
|
|
r#"{"block":"std::walk_forward","in_sample_ms":4000,"out_of_sample_ms":1000,"step_ms":1000,"#,
|
|
r#""mode":"rolling","metric":"net_expectancy_r","select":"argmax"}]}"#
|
|
);
|
|
assert_eq!(canonical, golden);
|
|
assert!(!canonical.ends_with('\n'));
|
|
let id = content_id_of(&canonical);
|
|
assert_eq!(id.len(), 64);
|
|
assert!(id.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()));
|
|
let reparsed = parse_process(&canonical).unwrap();
|
|
assert_eq!(content_id_of(&process_to_json(&reparsed)), id);
|
|
// omit-defaults: deflate:false disappears from the canonical form
|
|
let no_deflate = PROCESS_FIXTURE.replacen("\"deflate\": true", "\"deflate\": false", 1);
|
|
let canonical2 = process_to_json(&parse_process(&no_deflate).unwrap());
|
|
assert!(!canonical2.contains("\"deflate\":"));
|
|
assert_ne!(content_id_of(&canonical2), id);
|
|
}
|
|
|
|
#[test]
|
|
fn campaign_canonical_form_normalizes_and_distinguishes() {
|
|
let doc = parse_campaign(CAMPAIGN_FIXTURE).unwrap();
|
|
let canonical = campaign_to_json(&doc);
|
|
assert!(!canonical.ends_with('\n'));
|
|
let reparsed = parse_campaign(&canonical).unwrap();
|
|
assert_eq!(reparsed, doc);
|
|
assert_eq!(campaign_to_json(&reparsed), canonical);
|
|
let id = content_id_of(&canonical);
|
|
assert_eq!(id.len(), 64);
|
|
// a different seed is a different campaign
|
|
let other = CAMPAIGN_FIXTURE.replacen("\"seed\": 1", "\"seed\": 2", 1);
|
|
let other_id = content_id_of(&campaign_to_json(&parse_campaign(&other).unwrap()));
|
|
assert_ne!(other_id, id);
|
|
// spelling normalization: an F64 axis writes ints as floats, so the
|
|
// two spellings share one canonical form (and thus one content id)
|
|
let spelled_a = CAMPAIGN_FIXTURE.replacen(
|
|
r#""fast": { "kind": "I64", "values": [8, 12, 16] }"#,
|
|
r#""fast": { "kind": "F64", "values": [8, 12.0, 16] }"#,
|
|
1,
|
|
);
|
|
let spelled_b = CAMPAIGN_FIXTURE.replacen(
|
|
r#""fast": { "kind": "I64", "values": [8, 12, 16] }"#,
|
|
r#""fast": { "kind": "F64", "values": [8.0, 12, 16.0] }"#,
|
|
1,
|
|
);
|
|
let ca = campaign_to_json(&parse_campaign(&spelled_a).unwrap());
|
|
let cb = campaign_to_json(&parse_campaign(&spelled_b).unwrap());
|
|
assert_eq!(ca, cb);
|
|
assert!(ca.contains(r#""values":[8.0,12.0,16.0]"#));
|
|
}
|
|
|
|
#[test]
|
|
fn risk_regime_round_trips_as_externally_tagged_vol() {
|
|
let r = RiskRegime::Vol { length: 3, k: 2.0 };
|
|
let j = serde_json::to_string(&r).unwrap();
|
|
assert_eq!(j, r#"{"vol":{"length":3,"k":2.0}}"#);
|
|
let back: RiskRegime = serde_json::from_str(&j).unwrap();
|
|
assert_eq!(back, r);
|
|
}
|
|
|
|
/// #262: the second variant's wire form is pinned the same way its Vol
|
|
/// sibling is — `vol_tf` snake_case tag, three named fields — so a stored
|
|
/// VolTf document's parse path doesn't silently rot.
|
|
#[test]
|
|
fn risk_regime_round_trips_as_externally_tagged_vol_tf() {
|
|
let r = RiskRegime::VolTf { period_minutes: 60, length: 14, k: 2.0 };
|
|
let j = serde_json::to_string(&r).unwrap();
|
|
assert_eq!(j, r#"{"vol_tf":{"period_minutes":60,"length":14,"k":2.0}}"#);
|
|
let back: RiskRegime = serde_json::from_str(&j).unwrap();
|
|
assert_eq!(back, r);
|
|
}
|
|
|
|
#[test]
|
|
fn campaign_absent_and_empty_risk_omit_from_canonical_bytes() {
|
|
let doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
assert!(doc.risk.is_empty(), "an absent risk key deserializes to empty");
|
|
let absent = campaign_to_json(&doc);
|
|
assert!(!absent.contains("\"risk\""), "absent risk omits from serialization: {absent}");
|
|
let mut empty = doc.clone();
|
|
empty.risk = vec![];
|
|
assert_eq!(
|
|
content_id_of(&campaign_to_json(&empty)),
|
|
content_id_of(&absent),
|
|
"an explicit empty risk hashes identically to an absent one"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn campaign_with_risk_serializes_and_round_trips_the_regimes() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.risk = vec![
|
|
RiskRegime::Vol { length: 3, k: 1.5 },
|
|
RiskRegime::Vol { length: 3, k: 3.0 },
|
|
];
|
|
let out = campaign_to_json(&doc);
|
|
assert!(out.contains(r#""risk":[{"vol":{"length":3,"k":1.5}},{"vol":{"length":3,"k":3.0}}]"#),
|
|
"risk serializes in place as a tagged list: {out}");
|
|
let back: CampaignDoc = serde_json::from_str(&out).unwrap();
|
|
assert_eq!(back.risk, doc.risk);
|
|
}
|
|
|
|
#[test]
|
|
fn validate_campaign_flags_each_non_positive_regime() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.risk = vec![
|
|
RiskRegime::Vol { length: 3, k: 2.0 }, // 0: valid
|
|
RiskRegime::Vol { length: 0, k: 2.0 }, // 1: length < 1
|
|
RiskRegime::Vol { length: 3, k: 0.0 }, // 2: k <= 0
|
|
];
|
|
let faults = validate_campaign(&doc);
|
|
assert!(faults.contains(&DocFault::BadRegime { index: 1 }), "{faults:?}");
|
|
assert!(faults.contains(&DocFault::BadRegime { index: 2 }), "{faults:?}");
|
|
assert!(!faults.contains(&DocFault::BadRegime { index: 0 }), "valid regime not flagged: {faults:?}");
|
|
}
|
|
|
|
/// #262: a non-positive `period_minutes` must be refused as a graceful
|
|
/// `DocFault::BadRegime` at the doc tier — otherwise it reaches
|
|
/// `VolTfStop::new`'s assert and panics instead of a validation error.
|
|
#[test]
|
|
fn validate_campaign_flags_non_positive_period_minutes_regime() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.risk = vec![
|
|
RiskRegime::VolTf { period_minutes: 60, length: 14, k: 2.0 }, // 0: valid
|
|
RiskRegime::VolTf { period_minutes: 0, length: 14, k: 2.0 }, // 1: period_minutes < 1
|
|
];
|
|
let faults = validate_campaign(&doc);
|
|
assert!(faults.contains(&DocFault::BadRegime { index: 1 }), "{faults:?}");
|
|
assert!(!faults.contains(&DocFault::BadRegime { index: 0 }), "valid regime not flagged: {faults:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn validate_campaign_accepts_a_valid_risk_section() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.risk = vec![RiskRegime::Vol { length: 3, k: 1.5 }];
|
|
assert!(validate_campaign(&doc).is_empty(), "{:?}", validate_campaign(&doc));
|
|
}
|
|
|
|
#[test]
|
|
fn cost_spec_round_trips_as_externally_tagged_components() {
|
|
// Serde field names ARE the shipped builders' ParamSpec names
|
|
// (cost_per_trade / slip_vol_mult / carry_per_cycle) — the doc
|
|
// vocabulary conforms to the node vocabulary, not the other way round.
|
|
for (spec, wire) in [
|
|
(
|
|
CostSpec::Constant { cost_per_trade: CostValue::Scalar(2.0) },
|
|
r#"{"constant":{"cost_per_trade":2.0}}"#,
|
|
),
|
|
(
|
|
CostSpec::VolSlippage { slip_vol_mult: CostValue::Scalar(0.5) },
|
|
r#"{"vol_slippage":{"slip_vol_mult":0.5}}"#,
|
|
),
|
|
(
|
|
CostSpec::Carry { carry_per_cycle: CostValue::Scalar(0.1) },
|
|
r#"{"carry":{"carry_per_cycle":0.1}}"#,
|
|
),
|
|
] {
|
|
assert_eq!(serde_json::to_string(&spec).unwrap(), wire);
|
|
let back: CostSpec = serde_json::from_str(wire).unwrap();
|
|
assert_eq!(back, spec);
|
|
}
|
|
// deny_unknown_fields: a misspelled knob refuses to parse
|
|
assert!(serde_json::from_str::<CostSpec>(r#"{"constant":{"per_close_r":2.0}}"#).is_err());
|
|
}
|
|
|
|
/// Property (#260): a cost knob's map form round-trips as a plain JSON
|
|
/// object keyed by instrument, and the scalar form stays the bare number
|
|
/// (content-id parity for stored docs is pinned by the sibling scalar
|
|
/// round-trip test, which must stay green untouched).
|
|
#[test]
|
|
fn cost_value_map_form_round_trips_and_scalar_stays_bare() {
|
|
let json = r#"{"constant":{"cost_per_trade":{"EURUSD":0.00012,"GER40":2.0}}}"#;
|
|
let spec: CostSpec = serde_json::from_str(json).expect("map form parses");
|
|
assert_eq!(serde_json::to_string(&spec).expect("serializes"), json);
|
|
let bare: CostSpec = serde_json::from_str(r#"{"constant":{"cost_per_trade":2.0}}"#)
|
|
.expect("scalar form parses");
|
|
assert_eq!(
|
|
serde_json::to_string(&bare).expect("serializes"),
|
|
r#"{"constant":{"cost_per_trade":2.0}}"#,
|
|
"scalar wire form must stay the bare number byte-identically"
|
|
);
|
|
let CostSpec::Constant { cost_per_trade } = &spec else { panic!("constant") };
|
|
assert_eq!(cost_per_trade.resolve("GER40"), Some(2.0));
|
|
assert_eq!(cost_per_trade.resolve("EURUSD"), Some(0.00012));
|
|
assert_eq!(cost_per_trade.resolve("XAUUSD"), None);
|
|
}
|
|
|
|
/// Property (#260): an empty instrument map (`{}`) is refused at
|
|
/// deserialize time — `validate_campaign`'s cross-check skips a knob
|
|
/// whose `instrument_keys()` is empty (that shape also means "scalar"),
|
|
/// so an empty map that slipped past this guard would silently escape
|
|
/// the instrument-coverage check entirely.
|
|
#[test]
|
|
fn cost_value_empty_map_is_refused_at_deserialize() {
|
|
let err = serde_json::from_str::<CostSpec>(r#"{"constant":{"cost_per_trade":{}}}"#)
|
|
.expect_err("an empty instrument map must not parse");
|
|
assert!(
|
|
err.to_string().contains("instrument map is empty"),
|
|
"error names the defect: {err}"
|
|
);
|
|
}
|
|
|
|
/// Property (#260): the intrinsic tier cross-checks every instrument map
|
|
/// against the doc's own data.instruments — a missing instrument and an
|
|
/// unknown extra key are each a fault naming the component; a complete
|
|
/// map is valid. No silent default, no partial coverage.
|
|
#[test]
|
|
fn validate_campaign_cross_checks_cost_instrument_maps() {
|
|
let mk = |cost: &str| {
|
|
let doc = format!(
|
|
r#"{{ "format_version": 1, "kind": "campaign", "name": "t",
|
|
"data": {{ "instruments": ["GER40", "EURUSD"],
|
|
"windows": [ {{ "from_ms": 1, "to_ms": 2 }} ] }},
|
|
"strategies": [ {{ "ref": {{ "content_id": "9f" }},
|
|
"axes": {{ "a": {{ "kind": "I64", "values": [1] }} }} }} ],
|
|
"process": {{ "ref": {{ "content_id": "9f" }} }},
|
|
"cost": [ {cost} ],
|
|
"presentation": {{ "persist_taps": [], "emit": [] }},
|
|
"seed": 1 }}"#
|
|
);
|
|
let parsed = parse_campaign(&doc).expect("parses");
|
|
validate_campaign(&parsed)
|
|
};
|
|
assert!(
|
|
mk(r#"{ "constant": { "cost_per_trade": { "GER40": 2.0, "EURUSD": 0.00012 } } }"#)
|
|
.is_empty(),
|
|
"a complete map must validate"
|
|
);
|
|
let missing = mk(r#"{ "constant": { "cost_per_trade": { "GER40": 2.0 } } }"#);
|
|
assert!(
|
|
missing.iter().any(|f| matches!(
|
|
f,
|
|
DocFault::CostInstrumentKeys { index: 0, .. }
|
|
)),
|
|
"fault names the component: {missing:?}"
|
|
);
|
|
let extra = mk(
|
|
r#"{ "constant": { "cost_per_trade": { "GER40": 2.0, "EURUSD": 1.0, "GER40.cash": 3.0 } } }"#,
|
|
);
|
|
assert!(
|
|
extra.iter().any(|f| matches!(f, DocFault::CostInstrumentKeys { index: 0, .. })),
|
|
"fault names the component: {extra:?}"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn campaign_absent_and_empty_cost_omit_from_canonical_bytes() {
|
|
// The risk precedent's sibling: cost-less documents keep their content ids.
|
|
let doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
assert!(doc.cost.is_empty(), "an absent cost key deserializes to empty");
|
|
let absent = campaign_to_json(&doc);
|
|
assert!(!absent.contains("\"cost\""), "absent cost omits from serialization: {absent}");
|
|
let mut empty = doc.clone();
|
|
empty.cost = vec![];
|
|
assert_eq!(
|
|
content_id_of(&campaign_to_json(&empty)),
|
|
content_id_of(&absent),
|
|
"an explicit empty cost hashes identically to an absent one"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn campaign_with_cost_serializes_and_round_trips_the_components() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.cost = vec![
|
|
CostSpec::Constant { cost_per_trade: CostValue::Scalar(2.0) },
|
|
CostSpec::VolSlippage { slip_vol_mult: CostValue::Scalar(0.5) },
|
|
];
|
|
let out = campaign_to_json(&doc);
|
|
assert!(
|
|
out.contains(r#""cost":[{"constant":{"cost_per_trade":2.0}},{"vol_slippage":{"slip_vol_mult":0.5}}]"#),
|
|
"cost serializes in place as a tagged list: {out}"
|
|
);
|
|
let back: CampaignDoc = serde_json::from_str(&out).unwrap();
|
|
assert_eq!(back.cost, doc.cost);
|
|
}
|
|
|
|
#[test]
|
|
fn validate_campaign_flags_each_bad_cost_component() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.cost = vec![
|
|
CostSpec::Constant { cost_per_trade: CostValue::Scalar(0.0) }, // 0: valid (zero cost is a legal stress point)
|
|
CostSpec::VolSlippage { slip_vol_mult: CostValue::Scalar(-0.5) }, // 1: negative
|
|
CostSpec::Carry { carry_per_cycle: CostValue::Scalar(f64::NAN) }, // 2: non-finite (unreachable via JSON; defensive)
|
|
];
|
|
let faults = validate_campaign(&doc);
|
|
assert!(faults.contains(&DocFault::BadCost { index: 1 }), "{faults:?}");
|
|
assert!(faults.contains(&DocFault::BadCost { index: 2 }), "{faults:?}");
|
|
assert!(!faults.contains(&DocFault::BadCost { index: 0 }), "valid component not flagged: {faults:?}");
|
|
}
|
|
|
|
/// Property (#260): the finiteness/sign check applies to EVERY value
|
|
/// inside a `PerInstrument` map, not only the scalar form — a negative
|
|
/// entry nested in an otherwise fully-keyed map is refused exactly like
|
|
/// a bad scalar (quality-review gap: the map cross-check test above only
|
|
/// exercised valid map values, leaving this path unexercised).
|
|
#[test]
|
|
fn validate_campaign_flags_a_bad_value_inside_an_instrument_map() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.cost = vec![CostSpec::Constant {
|
|
cost_per_trade: CostValue::PerInstrument(std::collections::BTreeMap::from([(
|
|
"GER40".to_string(),
|
|
-1.0,
|
|
)])),
|
|
}];
|
|
let faults = validate_campaign(&doc);
|
|
assert!(faults.contains(&DocFault::BadCost { index: 0 }), "{faults:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn validate_campaign_accepts_a_valid_cost_section() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
doc.cost = vec![CostSpec::Carry { carry_per_cycle: CostValue::Scalar(0.25) }];
|
|
assert!(validate_campaign(&doc).is_empty(), "{:?}", validate_campaign(&doc));
|
|
}
|
|
|
|
#[test]
|
|
fn cost_block_is_describable_beside_risk() {
|
|
let block = describe_block("std::cost").expect("std::cost describable");
|
|
assert_eq!(block.slots.len(), 1);
|
|
assert_eq!(block.slots[0].name, "cost");
|
|
assert!(!block.slots[0].required);
|
|
assert_eq!(
|
|
slot_kind_label(block.slots[0].kind),
|
|
"list of cost components { constant: { cost_per_trade } } | { vol_slippage: { slip_vol_mult } } | { carry: { carry_per_cycle } }; absent = zero costs (net == gross)"
|
|
);
|
|
}
|
|
|
|
/// The intrinsic tier does NOT constrain where a population-transforming
|
|
/// stage sits relative to the annotators (terminal_seen gates only Gate
|
|
/// stages): `[sweep, monte_carlo, walk_forward]` is intrinsically valid.
|
|
/// Execution-shape refusals are the executor preflight's job, one tier up
|
|
/// — this pin is the boundary between the two tiers.
|
|
#[test]
|
|
fn validate_process_permits_walk_forward_after_an_annotator() {
|
|
let doc = parse_process(
|
|
r#"{ "format_version": 1, "kind": "process", "name": "wf-after-mc",
|
|
"pipeline": [
|
|
{ "block": "std::sweep", "metric": "sqn", "select": "argmax" },
|
|
{ "block": "std::monte_carlo", "resamples": 100, "block_len": 5 },
|
|
{ "block": "std::walk_forward", "in_sample_ms": 4000, "out_of_sample_ms": 1000,
|
|
"step_ms": 1000, "mode": "rolling", "metric": "sqn", "select": "argmax" }
|
|
] }"#,
|
|
)
|
|
.unwrap();
|
|
assert_eq!(validate_process(&doc), Vec::new());
|
|
}
|
|
|
|
/// C29 (#316): a present document description passes the shape gate;
|
|
/// absent is never a fault. Both fault arms fire and carry the doc name.
|
|
#[test]
|
|
fn document_description_gate_flags_empty_and_restatement() {
|
|
let base = r#"{"format_version":1,"kind":"process","name":"p","pipeline":[{"block":"std::generalize","metric":"sqn"}]}"#;
|
|
let mut doc: ProcessDoc = serde_json::from_str(base).expect("fixture parses");
|
|
assert!(validate_process(&doc).is_empty(), "no description → no fault");
|
|
doc.description = Some(" ".into());
|
|
assert!(matches!(
|
|
validate_process(&doc).as_slice(),
|
|
[DocFault::BadDescription { subject, fault: DocGateFault::Empty }] if subject == "p"
|
|
));
|
|
doc.description = Some("P".into());
|
|
assert!(matches!(
|
|
validate_process(&doc).as_slice(),
|
|
[DocFault::BadDescription { fault: DocGateFault::RestatesName, .. }]
|
|
));
|
|
doc.description = Some("walk-forward validation methodology".into());
|
|
assert!(validate_process(&doc).is_empty(), "described → clean");
|
|
}
|
|
|
|
/// The campaign side takes the identical gate, exercised over the
|
|
/// crate's existing valid campaign fixture (`CAMPAIGN_FIXTURE`, which
|
|
/// validates clean — pinned by `validate_campaign_accepts_a_valid_risk_section`).
|
|
#[test]
|
|
fn campaign_description_gate_mirrors_process() {
|
|
let mut doc: CampaignDoc = serde_json::from_str(CAMPAIGN_FIXTURE).unwrap();
|
|
assert!(validate_campaign(&doc).is_empty(), "fixture validates clean");
|
|
doc.description = Some("".into());
|
|
assert!(matches!(
|
|
validate_campaign(&doc).as_slice(),
|
|
[DocFault::BadDescription { fault: DocGateFault::Empty, .. }]
|
|
));
|
|
doc.description = Some("GER40 walk-forward over the momentum stack".into());
|
|
assert!(validate_campaign(&doc).is_empty(), "described → clean");
|
|
}
|
|
|
|
/// C29 (#316): a present description participates in the content id
|
|
/// (absent ⇒ byte-identical is pinned by the existing round-trips).
|
|
#[test]
|
|
fn document_description_participates_in_the_content_id() {
|
|
let base = r#"{"format_version":1,"kind":"process","name":"p","pipeline":[{"block":"std::generalize","metric":"sqn"}]}"#;
|
|
let bare: ProcessDoc = serde_json::from_str(base).unwrap();
|
|
let mut described: ProcessDoc = serde_json::from_str(base).unwrap();
|
|
described.description = Some("walk-forward validation methodology".into());
|
|
let bare_id = content_id_of(&process_to_json(&bare));
|
|
let described_id = content_id_of(&process_to_json(&described));
|
|
assert_ne!(bare_id, described_id, "description must move the content id");
|
|
}
|
|
|
|
#[test]
|
|
fn validate_process_accepts_the_fixture_and_reports_each_fault() {
|
|
let ok = parse_process(PROCESS_FIXTURE).unwrap();
|
|
assert_eq!(validate_process(&ok), Vec::new());
|
|
|
|
let empty = ProcessDoc { pipeline: Vec::new(), ..ok.clone() };
|
|
assert_eq!(validate_process(&empty), vec![DocFault::EmptyPipeline]);
|
|
|
|
let bad_metric = parse_process(&PROCESS_FIXTURE.replacen(
|
|
"net_expectancy_r\", \"select\": \"plateau:worst",
|
|
"netto_r\", \"select\": \"plateau:worst",
|
|
1,
|
|
))
|
|
.unwrap();
|
|
assert!(validate_process(&bad_metric)
|
|
.iter()
|
|
.any(|f| matches!(f, DocFault::UnknownMetric { stage: 0, metric } if metric == "netto_r")));
|
|
|
|
let gate_first = ProcessDoc {
|
|
pipeline: vec![StageBlock::Gate {
|
|
all: vec![Predicate { metric: "sqn".into(), cmp: Cmp::Gt, value: 1.0 }],
|
|
}],
|
|
..ok.clone()
|
|
};
|
|
assert!(validate_process(&gate_first).contains(&DocFault::GateFirst));
|
|
|
|
let empty_conj = ProcessDoc {
|
|
pipeline: vec![ok.pipeline[0].clone(), StageBlock::Gate { all: Vec::new() }],
|
|
..ok.clone()
|
|
};
|
|
assert!(validate_process(&empty_conj).contains(&DocFault::EmptyConjunction { stage: 1 }));
|
|
|
|
let gate_after = ProcessDoc {
|
|
pipeline: vec![
|
|
ok.pipeline[0].clone(),
|
|
StageBlock::MonteCarlo { resamples: 100, block_len: 5 },
|
|
StageBlock::Gate {
|
|
all: vec![Predicate { metric: "sqn".into(), cmp: Cmp::Gt, value: 1.0 }],
|
|
},
|
|
],
|
|
..ok.clone()
|
|
};
|
|
assert!(validate_process(&gate_after)
|
|
.contains(&DocFault::GateAfterTerminalStage { stage: 2 }));
|
|
}
|
|
|
|
/// The intrinsic tier's metric-validation branch for `std::sweep` must
|
|
/// skip a `None` selection cleanly (no metric to resolve, so no spurious
|
|
/// `UnknownMetric`) — the terminal-placement rule itself is the
|
|
/// executor preflight's job, not this validator's.
|
|
#[test]
|
|
fn validate_process_accepts_a_selection_free_sweep() {
|
|
let doc = ProcessDoc {
|
|
format_version: FORMAT_VERSION,
|
|
kind: DocKind::Process,
|
|
name: "sweep-only".to_string(),
|
|
description: None,
|
|
pipeline: vec![StageBlock::Sweep { selection: None }],
|
|
};
|
|
assert_eq!(validate_process(&doc), Vec::new());
|
|
}
|
|
|
|
#[test]
|
|
fn walk_forward_parses_both_modes_and_refuses_bad_slots() {
|
|
// "anchored" is the other accepted wire mode
|
|
let anchored = PROCESS_FIXTURE.replacen("\"mode\": \"rolling\"", "\"mode\": \"anchored\"", 1);
|
|
let doc = parse_process(&anchored).expect("anchored parses");
|
|
assert!(matches!(
|
|
&doc.pipeline[2],
|
|
StageBlock::WalkForward { mode: WfMode::Anchored, .. }
|
|
));
|
|
// an unknown mode string refuses through WfMode's serde oracle
|
|
let bad_mode = PROCESS_FIXTURE.replacen("\"mode\": \"rolling\"", "\"mode\": \"expanding\"", 1);
|
|
let err = parse_process(&bad_mode).expect_err("unknown mode refused");
|
|
assert!(matches!(err, DocError::Malformed(msg) if msg.contains("unknown mode \"expanding\"")));
|
|
// the retired 0106 vocabulary ("folds") is an unknown slot now
|
|
let folds = PROCESS_FIXTURE.replacen("\"in_sample_ms\": 4000", "\"folds\": 4", 1);
|
|
let err = parse_process(&folds).expect_err("folds refused");
|
|
assert!(matches!(err, DocError::Malformed(msg) if msg.contains("unknown slot \"folds\"")));
|
|
// a missing required length slot is named
|
|
let missing = PROCESS_FIXTURE.replacen("\"step_ms\": 1000, ", "", 1);
|
|
let err = parse_process(&missing).expect_err("missing step_ms refused");
|
|
assert!(
|
|
matches!(err, DocError::Malformed(msg) if msg.contains("missing required slot \"step_ms\""))
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn validate_process_reports_each_zero_walk_forward_length() {
|
|
let ok = parse_process(PROCESS_FIXTURE).unwrap();
|
|
let zeroed = ProcessDoc {
|
|
pipeline: vec![
|
|
ok.pipeline[0].clone(),
|
|
StageBlock::WalkForward {
|
|
in_sample_ms: 0,
|
|
out_of_sample_ms: 0,
|
|
step_ms: 0,
|
|
mode: WfMode::Rolling,
|
|
metric: "net_expectancy_r".into(),
|
|
select: SelectRule::Argmax,
|
|
},
|
|
],
|
|
..ok.clone()
|
|
};
|
|
assert_eq!(
|
|
validate_process(&zeroed),
|
|
vec![
|
|
DocFault::ZeroWalkForwardLength { stage: 1, field: "in_sample_ms" },
|
|
DocFault::ZeroWalkForwardLength { stage: 1, field: "out_of_sample_ms" },
|
|
DocFault::ZeroWalkForwardLength { stage: 1, field: "step_ms" },
|
|
]
|
|
);
|
|
let one = ProcessDoc {
|
|
pipeline: vec![
|
|
ok.pipeline[0].clone(),
|
|
StageBlock::WalkForward {
|
|
in_sample_ms: 4000,
|
|
out_of_sample_ms: 1000,
|
|
step_ms: 0,
|
|
mode: WfMode::Anchored,
|
|
metric: "net_expectancy_r".into(),
|
|
select: SelectRule::Argmax,
|
|
},
|
|
],
|
|
..ok.clone()
|
|
};
|
|
assert_eq!(
|
|
validate_process(&one),
|
|
vec![DocFault::ZeroWalkForwardLength { stage: 1, field: "step_ms" }]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn validate_campaign_accepts_the_fixture_and_reports_each_fault() {
|
|
let ok = parse_campaign(CAMPAIGN_FIXTURE).unwrap();
|
|
assert_eq!(validate_campaign(&ok), Vec::new());
|
|
|
|
let mut bare = ok.clone();
|
|
bare.data.instruments.clear();
|
|
bare.data.windows.clear();
|
|
let faults = validate_campaign(&bare);
|
|
assert!(faults.contains(&DocFault::EmptyInstruments));
|
|
assert!(faults.contains(&DocFault::NoWindow));
|
|
|
|
let mut inv = ok.clone();
|
|
inv.data.windows[0] = Window { from_ms: 10, to_ms: 10 };
|
|
assert!(validate_campaign(&inv).contains(&DocFault::BadWindow { index: 0 }));
|
|
|
|
let mut none = ok.clone();
|
|
none.strategies.clear();
|
|
assert!(validate_campaign(&none).contains(&DocFault::NoStrategy));
|
|
|
|
let mut no_axes = ok.clone();
|
|
no_axes.strategies[0].axes.clear();
|
|
assert!(validate_campaign(&no_axes).contains(&DocFault::EmptyAxes { strategy: 0 }));
|
|
|
|
let mut empty_axis = ok.clone();
|
|
empty_axis.strategies[0]
|
|
.axes
|
|
.insert("slow".into(), Axis { kind: ScalarKind::I64, values: Vec::new() });
|
|
assert!(validate_campaign(&empty_axis)
|
|
.contains(&DocFault::EmptyAxis { strategy: 0, axis: "slow".into() }));
|
|
|
|
let mut ident = ok.clone();
|
|
ident.process.r#ref = DocRef::IdentityId("aaaa".into());
|
|
assert!(validate_campaign(&ident).contains(&DocFault::ProcessRefMustBeContentId));
|
|
|
|
let mut emit = ok.clone();
|
|
emit.presentation.emit.push("pie_chart".into());
|
|
assert!(validate_campaign(&emit).contains(&DocFault::UnknownEmitKind("pie_chart".into())));
|
|
}
|
|
|
|
#[test]
|
|
fn a_campaign_with_duplicate_instruments_is_refused() {
|
|
let ok = parse_campaign(CAMPAIGN_FIXTURE).unwrap();
|
|
assert_eq!(validate_campaign(&ok), Vec::new());
|
|
|
|
let mut dup = ok.clone();
|
|
let first = dup.data.instruments[0].clone();
|
|
dup.data.instruments.push(first.clone());
|
|
let index = dup.data.instruments.len() - 1;
|
|
assert!(validate_campaign(&dup)
|
|
.contains(&DocFault::DuplicateInstrument { index, instrument: first }));
|
|
}
|
|
|
|
/// #201 decision 1 (cycle 0109): the tap namespace is a CLOSED vocabulary —
|
|
/// the wrap convention's four persisted sink names. A genuinely new
|
|
/// observable is a new vocabulary entry (or an authored blueprint sink),
|
|
/// never an open node-path namespace in the document.
|
|
#[test]
|
|
fn tap_vocabulary_is_the_wrap_conventions_four_sink_names() {
|
|
let ids: Vec<&str> = tap_vocabulary().iter().map(|t| t.id).collect();
|
|
assert_eq!(ids, ["equity", "exposure", "r_equity", "net_r_equity"]);
|
|
}
|
|
|
|
/// Each `presentation.persist_taps` entry outside `tap_vocabulary()` is an
|
|
/// intrinsic fault carrying its index (for path-addressed prose downstream)
|
|
/// and the offending name — mirroring the UnknownEmitKind loop. The
|
|
/// fixture's own "net_r_equity" tap is in-vocabulary, so the clean-fixture
|
|
/// assert in `validate_campaign_accepts_the_fixture_and_reports_each_fault`
|
|
/// stays green unchanged.
|
|
#[test]
|
|
fn validate_campaign_refuses_unknown_taps_by_index() {
|
|
let ok = parse_campaign(CAMPAIGN_FIXTURE).unwrap();
|
|
let mut tap = ok.clone();
|
|
tap.presentation.persist_taps.push("bias".into());
|
|
assert_eq!(
|
|
validate_campaign(&tap),
|
|
vec![DocFault::UnknownTap { index: 1, tap: "bias".into() }]
|
|
);
|
|
// every in-vocabulary name passes
|
|
let mut all = ok.clone();
|
|
all.presentation.persist_taps = tap_vocabulary().iter().map(|t| t.id.to_string()).collect();
|
|
assert_eq!(validate_campaign(&all), Vec::new());
|
|
}
|
|
|
|
/// The campaign `data.bindings` block (#231): serde-ADDITIVE (a
|
|
/// binding-less document serializes with NO "bindings" key — every stored
|
|
/// campaign's content id is byte-stable — and legacy text parses to an
|
|
/// empty map), round-trips when present, and value-checks against the
|
|
/// closed column vocabulary at the intrinsic tier.
|
|
#[test]
|
|
fn bindings_are_serde_additive_and_value_checked() {
|
|
let legacy = format!(
|
|
concat!(
|
|
r#"{{"format_version":1,"kind":"campaign","name":"c","#,
|
|
r#""data":{{"instruments":["GER40"],"windows":[{{"from_ms":1,"to_ms":2}}]}},"#,
|
|
r#""strategies":[{{"ref":{{"content_id":"{id}"}},"axes":{{"len":{{"kind":"I64","values":[2]}}}}}}],"#,
|
|
r#""process":{{"ref":{{"content_id":"{id}"}}}},"#,
|
|
r#""seed":1,"presentation":{{"persist_taps":[],"emit":[]}}}}"#
|
|
),
|
|
id = "a".repeat(64),
|
|
);
|
|
let doc = parse_campaign(&legacy).expect("legacy campaign parses");
|
|
assert!(doc.data.bindings.is_empty());
|
|
assert!(!campaign_to_json(&doc).contains("bindings"));
|
|
assert!(validate_campaign(&doc).is_empty());
|
|
|
|
let with = legacy.replace(
|
|
r#""data":{"instruments""#,
|
|
r#""data":{"bindings":{"price":"open"},"instruments""#,
|
|
);
|
|
assert_ne!(with, legacy, "the fixture splice must hit");
|
|
let doc = parse_campaign(&with).expect("bindings campaign parses");
|
|
assert_eq!(doc.data.bindings.get("price").map(String::as_str), Some("open"));
|
|
assert!(campaign_to_json(&doc).contains(r#""bindings":{"price":"open"}"#));
|
|
assert!(validate_campaign(&doc).is_empty());
|
|
|
|
let bad = legacy.replace(
|
|
r#""data":{"instruments""#,
|
|
r#""data":{"bindings":{"price":"hl2"},"instruments""#,
|
|
);
|
|
let doc = parse_campaign(&bad).expect("parses (values are validate-tier)");
|
|
assert_eq!(
|
|
validate_campaign(&doc),
|
|
vec![DocFault::UnknownBindingColumn {
|
|
role: "price".to_string(),
|
|
column: "hl2".to_string()
|
|
}]
|
|
);
|
|
}
|
|
|
|
/// The `std::presentation` persist_taps slot advertises the closed tap
|
|
/// vocabulary through the describe path (`describe_block` +
|
|
/// `slot_kind_label`); the label is cross-pinned against `tap_vocabulary()`
|
|
/// so the static label and the validator cannot drift apart.
|
|
#[test]
|
|
fn persist_taps_slot_advertises_the_tap_vocabulary() {
|
|
let block = describe_block("std::presentation").expect("presentation describable");
|
|
let slot = block
|
|
.slots
|
|
.iter()
|
|
.find(|s| s.name == "persist_taps")
|
|
.expect("presentation has a persist_taps slot");
|
|
assert_eq!(slot.kind, SlotKind::TapKinds);
|
|
assert_eq!(
|
|
slot_kind_label(slot.kind),
|
|
format!(
|
|
"list of: {}",
|
|
tap_vocabulary().iter().map(|t| t.id).collect::<Vec<_>>().join(" | ")
|
|
)
|
|
);
|
|
assert_eq!(
|
|
slot_kind_label(slot.kind),
|
|
"list of: equity | exposure | r_equity | net_r_equity"
|
|
);
|
|
}
|
|
|
|
/// A draft missing its `presentation` section is pointed at the section
|
|
/// AND the closed tap vocabulary (the guide never advertises an open
|
|
/// namespace the validator would refuse). The hint is cross-pinned
|
|
/// against `tap_vocabulary()` — like `persist_taps_slot_advertises_the_
|
|
/// tap_vocabulary` above — so a fifth tap cannot leave this draft hint
|
|
/// silently stale.
|
|
#[test]
|
|
fn presentation_open_slot_hint_names_the_tap_vocabulary() {
|
|
let draft = r#"{ "format_version": 1, "kind": "campaign", "name": "draft",
|
|
"data": { "instruments": ["GER40"], "windows": [ { "from_ms": 1, "to_ms": 2 } ] },
|
|
"strategies": [ { "ref": { "content_id": "9f3a" },
|
|
"axes": { "slow": { "kind": "I64", "values": [10] } } } ],
|
|
"process": { "ref": { "content_id": "4e2d" } },
|
|
"seed": 1 }"#;
|
|
let slots = open_slots_campaign(draft).unwrap();
|
|
let pres = slots
|
|
.iter()
|
|
.find(|s| s.path == "presentation")
|
|
.expect("presentation slot must be open");
|
|
assert_eq!(
|
|
pres.hint,
|
|
format!(
|
|
"required section: persist_taps ({}) + emit",
|
|
tap_vocabulary().iter().map(|t| t.id).collect::<Vec<_>>().join(" | ")
|
|
)
|
|
);
|
|
assert_eq!(
|
|
pres.hint,
|
|
"required section: persist_taps (equity | exposure | r_equity | net_r_equity) + emit"
|
|
);
|
|
}
|
|
|
|
/// #256 fork B: the fieldless enumerate-only stage round-trips through
|
|
/// the schema-strict parser, and any slot on it is refused (its slot
|
|
/// list is empty, so the generic unknown-slot check covers every key).
|
|
#[test]
|
|
fn grid_block_round_trips_and_refuses_slots() {
|
|
let json = serde_json::to_string(&StageBlock::Grid).expect("serialize");
|
|
assert_eq!(json, r#"{"block":"std::grid"}"#);
|
|
let back: StageBlock = serde_json::from_str(&json).expect("parse back");
|
|
assert_eq!(back, StageBlock::Grid);
|
|
let err = serde_json::from_str::<StageBlock>(
|
|
r#"{"block":"std::grid","metric":"sqn"}"#,
|
|
)
|
|
.expect_err("a slot on the fieldless std::grid must be refused");
|
|
assert!(err.to_string().contains("unknown slot"), "got: {err}");
|
|
}
|
|
|
|
#[test]
|
|
fn vocabularies_enumerate_every_block_with_typed_slots() {
|
|
let ids: Vec<&str> = process_vocabulary().iter().map(|b| b.id).collect();
|
|
assert_eq!(
|
|
ids,
|
|
vec![
|
|
"std::sweep",
|
|
"std::gate",
|
|
"std::walk_forward",
|
|
"std::monte_carlo",
|
|
"std::generalize",
|
|
"std::grid"
|
|
]
|
|
);
|
|
for b in process_vocabulary().iter().chain(campaign_vocabulary()) {
|
|
assert!(!b.doc.is_empty(), "block {} has no doc line", b.id);
|
|
// std::grid is the one legitimate fieldless block (#256); every
|
|
// other block keeps its documented-slots guard.
|
|
assert!(
|
|
b.id == "std::grid" || !b.slots.is_empty(),
|
|
"block {} has no slots",
|
|
b.id
|
|
);
|
|
for s in b.slots {
|
|
assert!(!slot_kind_label(s.kind).is_empty());
|
|
}
|
|
}
|
|
let sweep = describe_block("std::sweep").expect("sweep describable");
|
|
assert!(sweep.slots.iter().any(|s| s.name == "metric" && !s.required));
|
|
assert!(sweep.slots.iter().any(|s| s.name == "deflate" && !s.required));
|
|
let wf = describe_block("std::walk_forward").expect("walk_forward describable");
|
|
let names: Vec<&str> = wf.slots.iter().map(|s| s.name).collect();
|
|
assert_eq!(
|
|
names,
|
|
vec!["in_sample_ms", "out_of_sample_ms", "step_ms", "mode", "metric", "select"]
|
|
);
|
|
let mode = wf.slots.iter().find(|s| s.name == "mode").expect("mode slot");
|
|
assert_eq!(slot_kind_label(mode.kind), "one of: rolling | anchored");
|
|
assert!(describe_block("std::strategy").is_some());
|
|
assert!(describe_block("std::nope").is_none());
|
|
}
|
|
|
|
/// A campaign process reference is content-id-only: `validate_campaign`
|
|
/// refuses an `identity_id` process ref (`ProcessRefMustBeContentId`), and
|
|
/// the block's own doc line says "(content id)". So the `std::process_ref`
|
|
/// describe output — the `describe_block` + `slot_kind_label` composition
|
|
/// the `--block` CLI verb renders — must not advertise an `identity_id`
|
|
/// form the validator would reject. The `--unwired` hint is already
|
|
/// narrowed (see `open_slots_campaign`); this pins the parallel describe
|
|
/// path to the same content-id-only contract. The narrowing is
|
|
/// process-ref-specific: a `std::strategy` ref legitimately accepts either
|
|
/// id form and must keep advertising both.
|
|
#[test]
|
|
fn process_ref_describe_advertises_content_id_only() {
|
|
let block = describe_block("std::process_ref").expect("process_ref describable");
|
|
let ref_slot =
|
|
block.slots.iter().find(|s| s.name == "ref").expect("process_ref has a ref slot");
|
|
let label = slot_kind_label(ref_slot.kind);
|
|
assert!(
|
|
!label.contains("identity_id"),
|
|
"process_ref advertises an identity_id form the validator refuses: {label}"
|
|
);
|
|
assert!(
|
|
label.contains("content"),
|
|
"process_ref describe must still name the content-id form: {label}"
|
|
);
|
|
// #329: the label must state the TAGGED shape ({ content_id: ... }) the
|
|
// parser actually requires, not read like a bare id string — mirroring
|
|
// the `{ content_id } | { identity_id }` bracket notation std::strategy
|
|
// already uses, narrowed to the one key process.ref accepts.
|
|
assert!(
|
|
label.contains("{ content_id }"),
|
|
"process_ref describe must state the tagged {{ content_id }} shape, not a bare id: {label}"
|
|
);
|
|
|
|
let strategy = describe_block("std::strategy").expect("strategy describable");
|
|
let strat_ref =
|
|
strategy.slots.iter().find(|s| s.name == "ref").expect("strategy has a ref slot");
|
|
let strat_label = slot_kind_label(strat_ref.kind);
|
|
assert!(
|
|
strat_label.contains("identity_id") && strat_label.contains("content_id"),
|
|
"strategy ref must keep advertising both id forms: {strat_label}"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn open_slots_report_partial_documents_by_path() {
|
|
assert_eq!(open_slots_process(PROCESS_FIXTURE).unwrap(), Vec::new());
|
|
// #216/#234: a complete but risk- and cost-less campaign has exactly
|
|
// TWO open slots — the two optional axes, in section order.
|
|
assert_eq!(
|
|
open_slots_campaign(CAMPAIGN_FIXTURE).unwrap(),
|
|
vec![
|
|
open_with_notes(
|
|
"risk",
|
|
"optional, list of stop regimes { vol: { length, k } } | { vol_tf: { period_minutes, length, k } }; absent = one default regime",
|
|
vec![
|
|
"vol.length smooths the per-cycle vol estimator; it does not set the stop's timescale.".to_string(),
|
|
"vol.k scales the stop distance (the risk-unit lever).".to_string(),
|
|
"vol_tf computes the same estimator over completed period_minutes buckets: period_minutes IS the stop's timescale; length smooths in buckets; k scales the distance.".to_string(),
|
|
],
|
|
),
|
|
open_with_notes(
|
|
"cost",
|
|
"optional, list of cost components { constant: { cost_per_trade } } | { vol_slippage: { slip_vol_mult } } | { carry: { carry_per_cycle } }; absent = zero costs (net == gross)",
|
|
vec![
|
|
"constant.cost_per_trade is in price units, not R (charged per close as cost/|entry-stop| in R).".to_string(),
|
|
"vol_slippage.slip_vol_mult is a multiplier on the per-cycle vol estimate (charged in R likewise).".to_string(),
|
|
"carry.carry_per_cycle is in price units per held cycle, not R (accrues over the hold, emitted in R likewise).".to_string(),
|
|
"each knob takes one number for all instruments, or an instrument-keyed map { \"GER40\": 2.0, ... } covering exactly the campaign's instruments.".to_string(),
|
|
],
|
|
),
|
|
]
|
|
);
|
|
|
|
let partial = r#"{ "format_version": 1, "kind": "process",
|
|
"pipeline": [ { "block": "std::sweep", "metric": "sqn" } ] }"#;
|
|
let slots = open_slots_process(partial).unwrap();
|
|
assert!(slots.iter().any(|s| s.path == "name"));
|
|
assert!(!slots.iter().any(|s| s.path == "pipeline[0].select"));
|
|
assert!(!slots.iter().any(|s| s.path == "pipeline[0].metric"));
|
|
|
|
let draft = r#"{ "format_version": 1, "kind": "campaign", "name": "draft",
|
|
"data": { "instruments": ["GER40"], "windows": [ { "from_ms": 1, "to_ms": 2 } ] },
|
|
"strategies": [ { "ref": { "content_id": "9f3a" },
|
|
"axes": { "slow": { "kind": "I64", "values": [] } } } ],
|
|
"seed": 1,
|
|
"presentation": { "persist_taps": [], "emit": [] } }"#;
|
|
let slots = open_slots_campaign(draft).unwrap();
|
|
assert!(slots.iter().any(|s| s.path == "process.ref"
|
|
&& s.hint == "required, { content_id }: content id of a process document"));
|
|
assert!(slots.iter().any(|s| s.path == "strategies[0].axes.slow"
|
|
&& s.hint == "axis declared empty — a P1 axis is a non-empty finite set"));
|
|
|
|
assert!(matches!(open_slots_process("nope"), Err(DocError::NotJson(_))));
|
|
}
|
|
|
|
/// Property: in the open-slot probe, a ref placeholder — `"ref": {}` or
|
|
/// `"ref": null` — is a drafting affordance that reports the SAME open slot
|
|
/// (same path, same existing hint) the omitted-key form reports, on both a
|
|
/// strategy entry and `process.ref`, and never aborts the probe. It lets one
|
|
/// draft file both validate-so-far and enumerate its open slots (fieldtest
|
|
/// 0106 F4 / #195). This pins only the probe; the strict `parse_campaign`
|
|
/// tier keeps refusing placeholders (canonical-form byte stability outranks
|
|
/// draft leniency) and is deliberately not exercised here.
|
|
#[test]
|
|
fn open_slots_report_placeholder_refs_as_open_slots() {
|
|
let draft = r#"{ "format_version": 1, "kind": "campaign", "name": "draft",
|
|
"data": { "instruments": ["GER40"], "windows": [ { "from_ms": 1, "to_ms": 2 } ] },
|
|
"strategies": [ { "ref": null,
|
|
"axes": { "slow": { "kind": "I64", "values": [10, 20] } } } ],
|
|
"process": { "ref": {} },
|
|
"seed": 1,
|
|
"presentation": { "persist_taps": [], "emit": [] } }"#;
|
|
// Errors on neither placeholder form (the probe stays a probe).
|
|
let slots = open_slots_campaign(draft).expect("placeholder refs must not abort the probe");
|
|
// The `null` strategy ref reports the strategy-ref open slot with its
|
|
// existing both-id-forms hint...
|
|
assert!(
|
|
slots.iter().any(|s| s.path == "strategies[0].ref"
|
|
&& s.hint == "required, one of: content_id, identity_id"),
|
|
"strategy `ref: null` placeholder not reported as an open slot: {slots:?}"
|
|
);
|
|
// ...and the `{}` process ref reports the narrower content-id-only hint.
|
|
assert!(
|
|
slots.iter().any(|s| s.path == "process.ref"
|
|
&& s.hint == "required, { content_id }: content id of a process document"),
|
|
"process `ref: {{}}` placeholder not reported as an open slot: {slots:?}"
|
|
);
|
|
}
|
|
|
|
/// #216/#234: each optional slot is listed only while unbound — binding
|
|
/// risk leaves exactly the cost slot open; binding both closes the probe
|
|
/// (a complete bound document has no open slots at all).
|
|
#[test]
|
|
fn open_slots_omit_bound_risk_and_cost_slots() {
|
|
let with_risk = CAMPAIGN_FIXTURE.replacen(
|
|
"\"seed\": 1,",
|
|
"\"seed\": 1,\n \"risk\": [ { \"vol\": { \"length\": 3, \"k\": 2.0 } } ],",
|
|
1,
|
|
);
|
|
assert_ne!(with_risk, CAMPAIGN_FIXTURE, "replacen must match the fixture's seed field");
|
|
assert_eq!(
|
|
open_slots_campaign(&with_risk).unwrap(),
|
|
vec![open_with_notes(
|
|
"cost",
|
|
"optional, list of cost components { constant: { cost_per_trade } } | { vol_slippage: { slip_vol_mult } } | { carry: { carry_per_cycle } }; absent = zero costs (net == gross)",
|
|
vec![
|
|
"constant.cost_per_trade is in price units, not R (charged per close as cost/|entry-stop| in R).".to_string(),
|
|
"vol_slippage.slip_vol_mult is a multiplier on the per-cycle vol estimate (charged in R likewise).".to_string(),
|
|
"carry.carry_per_cycle is in price units per held cycle, not R (accrues over the hold, emitted in R likewise).".to_string(),
|
|
"each knob takes one number for all instruments, or an instrument-keyed map { \"GER40\": 2.0, ... } covering exactly the campaign's instruments.".to_string(),
|
|
],
|
|
)]
|
|
);
|
|
let with_both = CAMPAIGN_FIXTURE.replacen(
|
|
"\"seed\": 1,",
|
|
"\"seed\": 1,\n \"risk\": [ { \"vol\": { \"length\": 3, \"k\": 2.0 } } ],\n \"cost\": [ { \"constant\": { \"cost_per_trade\": 2.0 } } ],",
|
|
1,
|
|
);
|
|
assert_ne!(with_both, CAMPAIGN_FIXTURE, "replacen must match the fixture's seed field");
|
|
assert_eq!(open_slots_campaign(&with_both).unwrap(), Vec::new());
|
|
}
|
|
|
|
#[test]
|
|
fn sweep_selection_group_is_all_or_nothing() {
|
|
let free = serde_json::json!({ "block": "std::sweep" });
|
|
assert_eq!(
|
|
stage_from_value(&free).unwrap(),
|
|
StageBlock::Sweep { selection: None }
|
|
);
|
|
let metric_only = serde_json::json!({ "block": "std::sweep", "metric": "sqn" });
|
|
let err = stage_from_value(&metric_only).unwrap_err();
|
|
assert!(err.contains("all-or-nothing"), "{err}");
|
|
let select_only = serde_json::json!({ "block": "std::sweep", "select": "argmax" });
|
|
let err = stage_from_value(&select_only).unwrap_err();
|
|
assert!(err.contains("all-or-nothing"), "{err}");
|
|
let deflate_only = serde_json::json!({ "block": "std::sweep", "deflate": true });
|
|
let err = stage_from_value(&deflate_only).unwrap_err();
|
|
assert!(err.contains("needs the selection group"), "{err}");
|
|
}
|
|
|
|
#[test]
|
|
fn selection_free_sweep_round_trips_and_hashes_distinctly() {
|
|
let doc = ProcessDoc {
|
|
format_version: FORMAT_VERSION,
|
|
kind: DocKind::Process,
|
|
name: "sweep".to_string(),
|
|
description: None,
|
|
pipeline: vec![StageBlock::Sweep { selection: None }],
|
|
};
|
|
let text = process_to_json(&doc);
|
|
// the absent group leaves ONLY the block id on the wire
|
|
assert!(text.contains("\"block\":\"std::sweep\""), "{text}");
|
|
assert!(!text.contains("metric"), "{text}");
|
|
assert!(!text.contains("select"), "{text}");
|
|
let back = parse_process(&text).expect("selection-free sweep parses");
|
|
assert_eq!(back, doc);
|
|
// a selected sibling hashes differently
|
|
let selected = ProcessDoc {
|
|
pipeline: vec![StageBlock::Sweep {
|
|
selection: Some(SweepSelection {
|
|
metric: "sqn_normalized".to_string(),
|
|
select: SelectRule::Argmax,
|
|
deflate: false,
|
|
}),
|
|
}],
|
|
..doc.clone()
|
|
};
|
|
assert_ne!(content_id_of(&text), content_id_of(&process_to_json(&selected)));
|
|
}
|
|
}
|