lode: Reimplementando el core de DVC en Go sin romper el formato

Hay un tipo de proyecto open source que me genera respeto inmediato: el que define con claridad lo que no hace. lode es uno de esos.

Cuando leí el README por primera vez, la frase que me frenó fue esta: "lode never invents a format; your repo stays a DVC repo." En un ecosistema donde cada herramienta nueva quiere ser el centro de gravedad, ese nivel de renuncia intencional es raro. Y es exactamente la decisión técnica que quiero diseccionar acá.

Mi tesis: la compatibilidad de formato no es una feature de marketing. Es una gestión de riesgo operativo. En equipos de ML donde DVC ya está integrado en pipelines, scripts de CI y flujos de auditoría, adoptar una herramienta que inventa su propio formato de artefactos exige una migración con ventana de congelamiento. lode evita ese costo completamente, y eso tiene un precio: pipelines y dvc repro quedan fuera de scope. El trade-off es honesto.

El problema que lode atacó

DVC es el estándar de facto para versionar datasets y modelos en proyectos de ML. El problema no es conceptual: es el runtime. Cuando tenés un directorio con 20.000 archivos y corrés dvc add big/, DVC hashea secuencialmente en Python, con toda la fricción del intérprete. El README del repo muestra una medición concreta sobre el mismo repo:

$ time dvc add big/      # 20,000 archivos
real    0m5.79s

$ time lode add big/     # mismo repo, resultado idéntico byte por byte
real    0m0.44s

Eso es una diferencia de ~13× en ese caso. No voy a universalizar ese número como garantía de performance general: depende del hardware, el sistema de archivos, el tamaño de los archivos individuales y cuántos ya están en el state DB. Lo que sí es reproducible es el mecanismo: Go compila a binario nativo sin overhead de VM, el hashing corre con NumCPU goroutines en paralelo, y el state DB (bbolt, bajo internal/hashfile) guarda (inode, mtime, size) → md5 para saltear archivos que no cambiaron. Esa combinación tiene sentido técnico independientemente del número exacto.

La fricción del hot path importa más de lo que parece en flujos de ML. Un dvc status lento hace que los data scientists lo eviten, lo que lleva a commits sin pointer files actualizados, lo que lleva a reproductibilidad rota. Acelerar el camino feliz tiene impacto real en disciplina del equipo.

La invariante que no se negocia

Lo que más me interesó del repo fue leer docs/ARCHITECTURE.md y encontrar esto escrito como principio cardinal:

Byte-compatibility with DVC. Anything that changes a serialized artifact (.dvc, .dir, cache/remote layout) must keep the oracle test (tests/oracle/, which runs the real dvc and compares bytes) green.

No es un comentario en el README. Es una invariante de diseño que atraviesa toda la arquitectura. El paquete internal/dvcfile lee y escribe archivos .dvc byte-exact con DVC 3.x. El paquete internal/hashfile reimplementa la serialización del .dir manifest para que matchee exactamente con json.dumps de Python (que tiene un orden de claves específico). El paquete internal/lock implementa locking compatible con DVC para que ambas herramientas puedan coexistir en el mismo repo sin corromperse.

La arquitectura está organizada para que el riesgo de formato esté concentrado en lugares específicos:

internal/
├── dvcfile/   # Lee/escribe .dvc — compatibilidad byte-exacta con DVC 3.x
├── hashfile/  # MD5 paralelo + serialización .dir (el detalle más delicado de compat)
├── cache/     # Object store content-addressed: files/md5/<2>/<rest>
├── remote/    # Backend S3-compatible via minio-go
├── transfer/  # Push/fetch con verificación de integridad
├── checkout/  # Materialización: reflink → hardlink/symlink → copy
└── lock/      # Locking DVC-compatible (flock global + rwlock JSON)

Cada paquete tiene una responsabilidad única y el código de mayor riesgo de formato está aislado en internal/dvcfile e internal/hashfile/tree.go. Eso facilita razonar sobre dónde puede romperse la compatibilidad si DVC cambia su formato en una versión futura.

El CI tiene un job oracle que instala el DVC real (via pipx install "dvc[s3]") y corre go test ./tests/oracle/... para comparar bytes. Si la invariante se rompe, el pipeline falla. No hay ambigüedad.

El trade-off honesto: qué acelerás y qué dejás afuera

lode implementa el data layer: add, status, push, pull, fetch, checkout, gc, remote, doctor, verify. Eso cubre el hot path diario de un equipo que versiona datasets.

Lo que no está en scope: dvc repro, dvc run, pipelines, DAGs de transformación. La arquitectura no fingió que eso era sencillo de reimplementar con compatibilidad byte-identical. Optaron por definir un perímetro claro y ejecutarlo bien, en lugar de hacer un clon parcial de todo DVC.

Mirá el README: "For ML pipelines (dvc repro), keep using DVC — lode accelerates the data layer and coexists with it." Esa frase no es una disculpa. Es una decisión de diseño. Los dos tools conviven porque comparten el mismo lock (internal/lock usa flock global + rwlock JSON compatible con DVC) y el mismo formato de artefactos. Podés correr lode add y después dvc repro sin ninguna capa de sincronización adicional.

El riesgo principal que veo con cualquier reimplementación de formato es la deriva: si DVC 4.x cambia el schema del .dvc file o el orden de claves del .dir JSON, lode tiene que actualizarse en paralelo o la compatibilidad se rompe silenciosamente. El oracle test mitiga esto, pero solo para la versión de DVC que está instalada en CI. Eso no es un defecto del diseño de lode; es el costo estructural de ser compatible con un formato que no controlás. Un equipo que lo adopte debería planear ese seguimiento.

El state DB: optimización con degradación grácil

El mecanismo que más me gustó del diseño es cómo piensan el state DB. La arquitectura lo dice explícitamente:

The state DB (inode, mtime, size) -> md5 is an optimization, never a source of truth. It can produce a false "up to date" only if a file's content changes while all three keys stay identical (e.g. NFS quirks, restored backups that reset mtimes, recycled inodes). For those cases --rehash (and a corrupt/unreadable state DB) degrade to a full re-hash — the always-correct path.

Eso es un contrato claro sobre los límites de la optimización. El estado corrupto o un edge case de NFS no rompen la correctness: degradan a la ruta lenta pero siempre correcta. El flag --rehash existe exactamente para eso. En sistemas de archivos de red o entornos de CI donde los inodes pueden reciclarse, es algo a tener en cuenta.

Lo que me parece un buen indicador de madurez técnica es que este límite está documentado en la arquitectura, no escondido en un issue de GitHub. Un equipo que lo adopte sabe exactamente cuándo lode status puede mentir (y cómo forzar la ruta correcta).

El binario estático como argumento operativo

CGO_ENABLED=0 en el build significa un binario sin dependencias dinámicas. Eso tiene implicaciones prácticas en MLOps:

make build       # binario único sin CGO, sin runtime externo
make test-short  # unit + oracle, sin servicios externos
make test        # suite completa — necesita MinIO y dvc real

En una imagen Docker de entrenamiento, instalar Python + DVC + dependencias S3 agrega capas que pueden sumar cientos de MB y minutos de build. Un binario estático es COPY lode /usr/local/bin/lode y terminó. El release pipeline usa goreleaser con SBOM (via syft), firma keyless con cosign (OIDC) y attestation de build provenance (SLSA). Para un proyecto recién armado, ese nivel de rigor en la cadena de supply chain es una señal positiva sobre cómo piensan el mantenimiento a largo plazo.

Mi postura

No compro el claim de "drop-in compatible" de forma absoluta: lode es drop-in compatible para el data layer. Si el workflow del equipo depende de dvc repro, hay una parte del flujo que sigue en DVC. Eso no es un problema, pero hay que nombrarlo honestamente para no generar expectativas incorrectas.

Lo que sí acepto sin reservas: el enfoque de coexistencia es técnicamente correcto. La alternativa de inventar un formato propio trasladaría el costo de la performance a un costo de migración y lock-in. En equipos de ML donde los artefactos de datos son también evidencia de auditoría (reproducibilidad de experimentos, trazabilidad de modelos), cambiar el formato de esos artefactos tiene un costo que va más allá del tiempo de ingeniería.

El trade-off que me parece honesto: lode resuelve el problema de performance del hot path con una restricción que en la mayoría de los casos es tolerable. El riesgo es la deriva de formato cuando DVC actualice su spec. El oracle test en CI es el mecanismo de detección, pero requiere disciplina de mantenimiento activo.

Si manejás repos DVC con datasets grandes y el tiempo de dvc add o dvc push es un cuello de botella real, lode merece una evaluación. El hecho de que lode verify y dvc status puedan correr sobre los mismos artefactos y dar el mismo resultado es el contrato que hace que la evaluación sea reversible sin costo.

¿Qué harías vos si el formato de DVC cambia en una minor version y rompe silenciosamente la compatibilidad en producción? ¿Tenés un oracle test que lo detecte, o lo descubrís en el próximo dvc repro?

Repo analizado: getlode/lode @ commit b6e6d34

Este artículo fue publicado originalmente en juanchi.dev