froga.lock — estado de deriva

✅ Estable

froga.lock es el fichero de anclaje de frescura que el motor escribe en la raíz del repositorio tras cada ejecución de froga run. Contiene los digests de las entradas del pipeline en el momento del último recómputo. froga status lo lee sin ejecutar ningún script para determinar qué secciones han quedado obsoletas.

Qué ancla `froga.lock`

El núcleo del fichero es la terna anclada (triple), que identifica de forma determinista el estado del repositorio en el momento del recómputo:

Campo de `triple`	Qué mide	Cómo se calcula
`code`	Versión del código	SHA-1 de `HEAD` (via gix, in-process)
`model`	(reservado)	Vacío en `GitDvcVersionResolver` (`model: String::new()`); la versión del modelo se ancla indirectamente vía `pipeline_lock_digest` (`dvc.lock`/métricas)
`dataset`	Versión del dataset	SHA-256 compuesto de los hashes DVC de `data/*.dvc`

Además de la terna, el campo pipeline_lock_digest ancla el estado del pipeline reproducible:

Para el backend DVC (cat. 1): SHA-256 del fichero dvc.lock tras dvc repro — ancla deps + params + outs del recómputo.
Para MLflow (cat. 2): SHA-256 canónico de las métricas del run (content-addressed).
Para Dagster (cat. 3): SHA-256 del fichero de métricas tras la materialización de assets.

El pipeline_lock_digest entra en la evidencia firmada (EvidenceBundle.pipeline_lock_digest) como procedencia del recómputo (Anexo IV §1).

Estructura del fichero

El esquema está en froga-core/src/lock.rs. A continuación se muestra la forma ilustrativa de un froga.lock real (los valores de hash son ficticios):

{
  "schema_version": "venturalitica.ai/v1alpha1",
  "program_uid": "550e8400-e29b-41d4-a716-446655440000",
  "triple": {
    "code": "4280c0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7",
    "model": "",
    "dataset": "dvc:a1b2c3d4e5f6..."
  },
  "sections": {
    "classification": {
      "status": "valid",
      "input_hash": "sha256:abc123...",
      "edge_type": "scope"
    },
    "measurement_data": {
      "status": "valid",
      "input_hash": "sha256:def456...",
      "edge_type": "data"
    },
    "measurement_model": {
      "status": "valid",
      "input_hash": "sha256:789abc...",
      "edge_type": "impl"
    }
  },
  "signed_bundle_digest": "sha256:deadbeef..."
}

Campos del nivel raíz

Campo	Tipo	Descripción
`schema_version`	string	Versión del esquema del lock (`venturalitica.ai/v1alpha1`).
`program_uid`	string	UUID del programa de riesgos (la sección `risk` de `froga.yaml`) en el momento del run, derivado del nombre del sistema (ancla el contexto normativo).
`triple`	objeto	Terna anclada `(code, model, dataset)` — ver tabla anterior.
`sections`	mapa	Grafo de dependencias tipado: cada sección tiene su `input_hash`, `status` y `edge_type`.
`signed_bundle_digest`	string	SHA-256 del bundle de evidencia firmado emitido por este run (`None` en el camino sin pipeline).

Entradas de `sections` (`LockEntry`)

Cada entrada del mapa sections tiene tres campos:

Campo	Tipo	Valores	Descripción
`status`	string	`"valid"`	Estado de la sección en el momento del run.
`input_hash`	string	`sha256:…`	Hash de las entradas de esta sección. Cuando cambia, la sección queda `stale`.
`edge_type`	string	`"scope"`, `"impl"`, `"data"`	Tipo de arista en el grafo de dependencias (ver abajo).

Tipos de arista (`EdgeType`)

El campo edge_type determina qué cambios activan la recomputación de cada sección:

`edge_type`	Valor en código	Qué dispara la recomputación
`scope`	`EdgeType::Scope`	Cambio de finalidad o triaje del sistema (Deriva A). La clasificación de riesgo debe rehacerse.
`impl`	`EdgeType::Impl`	Cambio del script de evaluación o del modelo (Deriva B). Solo se re-mide; no se re-triaja si la finalidad no varía.
`data`	`EdgeType::Data`	Cambio del dataset (Deriva C, EU AI Act Art. 10). Solo la medición dependiente de datos se recomputa.

Esta tipología corresponde directamente a las clases A, B y C de la deriva tipada. Consultar Deriva tipada para la descripción completa del modelo.

Cómo `froga status` detecta deriva sin recomputar

froga status compara los hashes actuales con los almacenados en froga.lock sin ejecutar ningún script:

Resuelve la terna actual del repositorio (HEAD git + hashes DVC; el campo model queda reservado/vacío — la versión del modelo se refleja en pipeline_lock_digest).
Compara cada input_hash de sections con el hash actual de la entrada correspondiente.
Las secciones cuyo hash ha cambiado se marcan como Stale { reason, change_class } con la clase de deriva correspondiente.
Las secciones sin cambios se marcan como Reused.

El resultado es un informe de deriva por sección con su clase (A, B o C) y la razón del cambio. froga status devuelve exit ≠ 0 si alguna sección está stale (barrera de frescura) o si algún control bloqueante del último bundle falla (barrera de riesgo).

# Detectar deriva sin recomputar — útil en CI/CD como barrera rápida
froga status

La staleness es selectiva: si solo cambia el dataset (edge_type: data), únicamente las secciones de medición de datos se recalculan en el siguiente froga run; la clasificación del sistema y las mediciones independientes del dataset se reutilizan.

Serialización canónica

El fichero froga.lock utiliza BTreeMap ordenado y serialización determinista: el mismo estado del repositorio produce siempre los mismos bytes. Esto garantiza que los digests firmados sean reproducibles entre máquinas.

Relación con el bundle de evidencia

froga.lock y .froga/bundle.json son complementarios:

froga.lock es el ancla de frescura: indica cuándo hay que re-ejecutar.
.froga/bundle.json es la evidencia firmada: contiene los resultados de la última ejecución, los veredictos de los controles y el pipeline_lock_digest.

El campo signed_bundle_digest de froga.lock vincula ambos artefactos: es el SHA-256 del bundle que se escribió en el mismo froga run.

Ver también: Referencia del CLI froga, Los artefactos .froga/*.

froga.lock — estado de deriva

Qué ancla froga.lock