Saltar a contenido

MATVARD Runtime Contract (M/A/T/V/A/R/D)#

Documento técnico único del contrato de salida runtime para MATVARD en SDP.

Fecha de corte: 2026-04-02

1. Objetivo#

Definir de forma estable qué campos debe persistir details_json en decisiones MATVARD y qué campos expone:

  • GET /ops/strategy/matvard/hypotheses
  • GET /ops/strategy/matvard/hypotheses/top

2. Estrategia/Modo canónico#

  • strategy_name: autopilot:matvard_advanced_shadow

3. Bloques semánticos MATVARD#

M - Marco mental#

  • mental_frame.bias
  • mental_frame.alignment
  • mental_frame.confidence
  • mental_frame.narrative_state
  • mental_frame.profile
  • mental_frame.session_ready

A - Análisis de narrativa#

  • prac.previa.*
  • prac.condicion_direccion.*
  • hypothesis.scenario

T - TPO/Subasta#

  • session_context.tpo.key_levels.tpo_poc|tpo_vah|tpo_val
  • session_context.tpo.opportunity.type|shape|confidence
  • value_development.tpo_opportunity.*

V - Valor en desarrollo#

  • value_development.session_vwap
  • value_development.value_area.low|high|poc|vah|val
  • value_development.dva_migration.daily|weekly|monthly|alignment
  • value_development.in_value_area
  • value_development.value_state

A - Aceptación y ritmo#

  • acceptance_state.label
  • acceptance_state.in_value_area
  • acceptance_state.value_state
  • acceptance_state.rhythm_state
  • acceptance_state.acceptance_kind

R - Riesgo#

  • risk_state.risk_pct
  • risk_state.rr_estimate
  • risk_state.max_hold_bars
  • risk_state.timeout_bars
  • risk_state.stop_distance
  • risk_state.net_edge_pct
  • risk_state.edge_quality
  • risk_state.profile
  • risk_state.blocked
  • risk_state.block_reason

D - Documentación#

  • documentation_state.contract
  • documentation_state.runtime_strategy_name
  • documentation_state.summary
  • documentation_state.hypothetical_side
  • documentation_state.invalidation_type
  • documentation_state.why_not_trade[]
  • documentation_state.quality_flags

4. Ranking operativo#

Cada hipótesis expone score:

  • score.value
  • score.band (high|medium|low)
  • score.components.net_edge_pct|confidence|quality_score
  • score.weights (actual: 0.50, 0.30, 0.20)

5. Endpoint GET /ops/strategy/matvard/hypotheses#

Filtros#

  • hours
  • limit
  • top_n
  • strategy_name
  • symbols
  • status
  • risk_profile
  • tpo_type
  • score_band
  • min_score

Ordenación#

  • sort_by=created_at|net_edge_pct|confidence|score
  • sort_order=asc|desc

Respuesta relevante#

  • filters
  • sort
  • aggregates.count_by_status
  • aggregates.count_by_risk_profile
  • aggregates.count_by_tpo_type
  • aggregates.count_by_score_band
  • items[] (contrato por hipótesis)

6. Endpoint GET /ops/strategy/matvard/hypotheses/top#

Vista rápida para Control Tower.

Defaults actuales: - hours=24 - top_n=10 - sort_by=score - sort_order=desc

Acepta los filtros operativos del endpoint base (risk_profile, tpo_type, score_band, min_score).

7. Snapshot diario recomendado#

Script operativo: - scripts/run_matvard_hypotheses_snapshot.py

Salida: - storage/reports/matvard/matvard_hypotheses_top_latest.json - storage/reports/matvard/matvard_hypotheses_top_latest.md

8. Compatibilidad#

Cambios futuros: - Añadir campos es compatible. - Renombrar/eliminar campos requiere actualizar este documento y tests de backend/tests/test_ops_strategy_performance.py.