Añadir un escenario (.json)

✅ Estable

El arnés e2e de Venturalítica es dirigido por datos: cada caso de uso vive en un fichero tests/scenarios/<nombre>.json. El código del arnés es el módulo completo tests/scenario/ (mod.rs + runner.rs + assertions.rs + env.rs + fixtures.rs, orquestado por mod.rs); es compartido por todos los escenarios y nunca se modifica al añadir uno nuevo.

Añadir un caso de uso = añadir un .json (y sus recursos) + una función #[test] de una línea que lo nombre. No se escribe ningún pilot_*.rs.

Estructura de un escenario

Un fichero de escenario tiene tres secciones de nivel superior:

{
  "name": "mi-sistema",
  "description": "Descripción del caso de uso y lo que se prueba.",
  "resource_dir": "mi-sistema",
  "steps": [
    { "do": "git_init" },
    { "do": "uv_init", "deps": ["venturalitica==0.6.11", "mlcroissant>=1.0", "dvc>=3"] },
    { "do": "copy", "from": "froga.yaml", "to": "froga.yaml" },
    { "do": "compile", "expect": { "exit": "ok" } },
    { "do": "run", "expect": { "exit": "fail", "gate": "red" } },
    { "do": "verify", "expect": { "exit": "ok" } }
  ]
}

Campo	Tipo	Descripción
`name`	string	Identificador del escenario (coincide con el nombre del `.json`).
`description`	string	Texto libre que describe el propósito y las invariantes del escenario. Se imprime en la traza.
`resource_dir`	string	Subdirectorio bajo `tests/resources/` que contiene los ficheros de fixture del escenario.
`steps`	array	Lista ordenada de pasos. Todo lo que ocurre en disco es un paso explícito.

Verbos de paso (`do`)

El runner entiende los siguientes verbos. Cada paso puede incluir un bloque expect con aserciones.

Verbos de entorno

Verbo	Efecto
`git_init`	`git init` + identidad del repo de fixture.
`uv_init`	Escribe `pyproject.toml` con las `deps` indicadas y ejecuta `uv sync`.
`dvc_init`	`dvc init`.
`copy`	Copia `from` (relativo a `resource_dir`) a `to` (en el repo temporal).
`dvc_add`	`dvc add <path>` — versiona el fichero con DVC.
`commit`	`git add -A && git commit -m <message>`.
`edit_sei`	Sustituye literales en `froga.yaml` (simula un cambio versionado).

Verbos de CLI `froga`

Verbo	Comando equivalente
`compile`	`froga compile` — programa de riesgos (sección `risk:` de `froga.yaml`) → `assessment_plan.oscal.yaml`.
`run`	`froga run` — reproduce el pipeline, ancla y firma la evidencia. El exit refleja la barrera de riesgo.
`status`	`froga status` — barreras de frescura + riesgo, sin recomputar.
`verify`	`froga verify` — verifica la firma del bundle.
`reconstruct`	`froga reconstruct [--out]` — reconstruye el ciclo ISO 23894 por replay de git.
`conformance`	`froga conformance --standard <id> [--out]` — proyecta el bundle al catálogo del estándar.
`approve`	`froga approve --by <by>` — aprobación de dirección con trailer `Froga-Approved-by`.
`impact`	`froga impact` — evaluación de impacto y mal uso previsible (ISO 42001 §6.1.4).
`assess`	`froga assess` — stub honesto (el KAG, asistente de identificación, es línea futura).

Verbos DVC (exploración RDD)

Verbo	Efecto
`dvc_exp`	`dvc exp run [--set-param ...]` — explora un candidato de tratamiento como experimento (git-stashed, sin commitear). Acepta `expect_metrics` para asegurar que el candidato cerraría la barrera.

El bloque `expect`

Cada paso puede declarar aserciones en su campo expect. El runner verifica cada una y falla el test si alguna no se cumple.

{
  "do": "run",
  "expect": {
    "exit": "fail",
    "gate": "red",
    "classification_tier": "high",
    "risks_nonempty": true,
    "pipeline_lock_present": true,
    "control_count": 10,
    "controls": {
      "unfair-credit-exclusion": {
        "passed": false,
        "enforcement_mode": "block",
        "severity": "high",
        "operator": "lt",
        "actual_gt": 0.03,
        "frameworks": ["eu/dora@2022#art-6"]
      }
    },
    "gate_failures": ["unfair-credit-exclusion"],
    "risk_analysis": {
      "risk.unfair-credit-exclusion": {
        "inherent_overall": "HIGH",
        "requires_treatment": true,
        "cycle": "open"
      }
    }
  }
}

Campo `expect`	Qué verifica
`exit`	`"ok"` o `"fail"` — el exit code del comando.
`gate`	`"green"` o `"red"` — el estado de la barrera de riesgo en el bundle.
`classification_tier`	Nivel de clasificación del sistema (p.ej. `"high"`).
`risks_nonempty`	El bundle contiene al menos un riesgo.
`pipeline_lock_present`	`pipeline_lock_digest` en el bundle empieza por `sha256:`.
`control_count`	Número exacto de controles en `control_results`.
`controls`	Por control: `passed`, `enforcement_mode`, `severity`, `operator`, `actual_gt/lt`, `frameworks`.
`gate_failures`	Lista exacta de controles bloqueantes en rojo (sin aceptados).
`drift`	Por sección: el texto de derive esperado en stdout (p.ej. `"recomputado (clase B)"`).
`stdout_contains`	Lista de cadenas que deben aparecer en stdout.
`risk_analysis`	Por riesgo: `inherent_overall`, `residual_overall`, `requires_treatment`, `cycle`.
`overall_residual`	Residual global del bundle: `level`, `evaluation`, `contributing`.
`treatment_events`	Recuento y contenido de eventos de tratamiento en el bundle.
`froga_artifacts`	Rutas relativas a `.froga/` que deben existir, ser JSON válido y tener firma verificable.

Un escenario por backend, misma loan

Para añadir un nuevo backend MLOps sobre el escenario loan, basta con crear un fichero .json que copie froga_<backend>.yaml como froga.yaml y sustituya el fichero de definición del pipeline. Los recursos (compliance_eval.py, train.py, german_credit.*) son los mismos porque residen en resource_dir: loan; el programa de riesgos vive en la sección risk: del propio froga.yaml.

Las tres variantes de backend del escenario loan (loan.json = DVC, loan_mlflow.json = MLflow, loan_dagster.json = Dagster) son la referencia de este patrón (hoy hay 8 escenarios JSON en total). Consulta Integrar tu flujo de trabajo para el detalle de cada backend.

Tras crear el .json y los recursos, añade una función de una línea en tests/scenarios.rs:

#[test]
fn mi_sistema() {
    run_scenario("mi-sistema");
}

No se toca ningún otro fichero Rust.

Recursos del escenario

Cada escenario declara su resource_dir. El runner busca los ficheros copiados (copy) en tests/resources/<resource_dir>/. Puedes reutilizar el directorio loan para nuevos backends del mismo escenario, o crear un directorio propio para sistemas distintos.

tests/
  scenarios/
    mi-sistema.json        ← el escenario
  resources/
    mi-sistema/
      froga.yaml             ← manifiesto + programa de riesgos (sección risk:)
      compliance_eval.py
      train.py
      data/mi-dataset.csv
      data/mi-dataset.croissant.json

Referencias

Integrar tu flujo de trabajo — cómo conectar DVC, MLflow o Dagster al seam Reproducer
Referencia froga.yaml — campos del manifiesto
Referencia del CLI froga — detalle de subcomandos