sei.lock — estado de deriva

✅ Estable

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

---

Qué ancla sei.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 seigarrena-core/src/lock.rs. A continuación se muestra la forma ilustrativa de un sei.lock real (los valores de hash son ficticios):

sei.lock (forma ilustrativa)

{
  "schema_version": "seigarrena.dev/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 (seigarrena.dev/v1alpha1).
program_uid	string	UUID del programa de riesgos (la sección risk de sei.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 sei status detecta deriva sin recomputar

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

1. 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).
2. Compara cada input_hash de sections con el hash actual de la entrada correspondiente.
3. Las secciones cuyo hash ha cambiado se marcan como Stale { reason, change_class } con la clase de deriva correspondiente.
4. 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. sei status devuelve exit ≠ 0 si alguna sección está stale (gate de frescura) o si algún control bloqueante del último bundle falla (gate de riesgo).

# Detectar deriva sin recomputar — útil en CI/CD como gate rápido
sei 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 sei run; la clasificación del sistema y las mediciones independientes del dataset se reutilizan.

---

Serialización canónica

El fichero sei.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

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

• sei.lock es el ancla de frescura: indica cuándo hay que re-ejecutar.
• .sei/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 sei.lock vincula ambos artefactos: es el SHA-256 del bundle que se escribió en el mismo sei run.

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