コンテンツにスキップ

YAML Audit Rationale

What this audit does

scripts/yaml_audit.sh scans aegis_v3/aegis-bt-rs/src/**/*.rs for top-level Rust constant declarations and compares the resulting inventory with .yaml-audit/allowed_consts.yaml.

Strict mode is what CI runs:

bash scripts/yaml_audit.sh

Report mode prints the full inventory and never fails:

bash scripts/yaml_audit.sh --report

Why this exists: the Python -> Rust migration plan requires a YAML-first configuration posture for trading semantics. Operators should be able to inspect the effective trade policy in YAML without reading Rust source.

Classification rule

Use this question first:

Does changing this constant alter what we trade, when we trade, how we price, or how we risk-manage positions?

If the answer is yes, it is trading-semantic and should live in YAML. If the answer is no, and the constant is a schema/version/path/protocol/runtime wiring invariant, it can stay in Rust.

Examples that may stay in Rust

  • PARITY_LOG_SCHEMA_VERSION: artifact schema contract for parity readers.
  • PT_STATE_VERSION: persisted state format version.
  • DEFAULT_STATE_ROOT: shared filesystem location for LT runtime artifacts.
  • BALANCE_STREAM_REFERENCE_ID: Saxo streaming subscription identity.
  • CONTRACT_MULTIPLIER: OCC contract invariant.
  • EXCHANGE_PRIORITY: resolver routing preference list.

These are infrastructure or code-wiring contracts. Moving them to YAML would not make trade policy more auditable.

Examples that should prefer YAML

  • DEFAULT_DTE_MIN
  • DEFAULT_DTE_MAX
  • DEFAULT_RPM_MARKET
  • DEFAULT_SCAN_INTERVAL_SECS
  • ABSOLUTE_CREDIT_FLOOR
  • EXIT_ESCALATION_MAX_ATTEMPTS
  • RISK_FREE_RATE
  • LOOKBACK_DAYS

These values change runtime or analytical behavior in ways an operator may want to inspect and tune without recompiling Rust.

Why the allowlist is intentionally pragmatic today

Current main still contains legacy hardcoded semantics that have not yet been moved to YAML. If CI rejected every one of those immediately, this task would break the branch without fixing the underlying migration work.

So the initial allowlist does two jobs:

  • It records the infrastructure constants that are expected to remain in code.
  • It temporarily records semantic constants that still need Phase 2 migration.

This means allowlist membership does not automatically mean "good forever". Some entries are there only so the inventory is explicit and future additions do not slip in unnoticed.

How to fix a CI failure

  1. Run bash scripts/yaml_audit.sh --report.
  2. Find the constant under Unlisted (would fail strict mode).
  3. Decide whether it is infrastructure-only or trading-semantic.
  4. If it is trading-semantic, move the value to the correct YAML under aegis_v3/configs/.
  5. If it is truly infrastructure-only, add it to .yaml-audit/allowed_consts.yaml with a brief Why comment.
  6. Re-run bash scripts/yaml_audit.sh.

When a temporary allowlist entry is acceptable

A temporary allowlist entry is acceptable only when all of the following are true:

  • The code already exists on main and this task is only making it explicit.
  • Moving it to YAML in the same PR would require Rust behavior changes.
  • The inline comment says it is a Phase 2 TODO.

Temporary allowlisting should not be used to hide brand-new trading policy.

Phase 2 TODO bucket

The current allowlist marks several entries as Temporary TODO. That bucket should shrink over time. Priority examples:

  • LT runtime cadence and breaker defaults
  • quote collector DTE / RPM defaults
  • pricing and execution guardrails
  • IV rank analytical windows
  • GEX enrichment thresholds and near-zero regime bands
  • synthetic generator anchor dates and pricing baseline

Each time one of those values moves into YAML, remove the Rust constant from the allowlist in the same change.

CI workflow behavior

.github/workflows/yaml-audit.yml runs on PRs and pushes to main when any of these paths change:

  • aegis_v3/aegis-bt-rs/src/**/*.rs
  • scripts/yaml_audit.sh
  • .yaml-audit/allowed_consts.yaml
  • .github/workflows/yaml-audit.yml

The workflow does two things:

  • Runs the audit in strict mode and fails fast on unlisted constants.
  • Publishes the full inventory into the GitHub Actions step summary.

Local reviewer checklist

  • New constant added: ask whether it is really YAML-owned policy.
  • Allowlist change added: require a concrete Why comment.
  • Temporary TODO added: require a follow-up migration plan.
  • Rust code unchanged in this task: expected for the G5 audit handoff.