La historia: causalidad registrada y qué habilita en un producto

Lo que distingue a Automerge de la mayoría de sus alternativas no es cómo fusiona, sino qué conserva después de fusionar. Otras bibliotecas de la familia tratan la historia como un residuo del algoritmo que conviene descartar en cuanto deja de hacer falta; aquí la historia es un producto de primera clase, con su propia API, y está pensada para que la consultes en tiempo de ejecución desde tu aplicación. Cada cambio lleva un hash criptográfico que lo identifica, la lista de hashes de los cambios de los que depende, el actor que lo produjo, una marca de tiempo y un mensaje opcional. Con eso, el documento deja de ser un estado y pasa a ser un grafo dirigido acíclico que puedes recorrer, del que puedes extraer una vista en cualquier punto y sobre el que puedes preguntar qué cambió entre dos versiones. Esta lección recorre esa API con precisión, y sobre todo delimita hasta dónde llega la respuesta a la pregunta que todo el mundo hace primero: quién hizo qué.

Qué queda registrado en cada cambio

Un cambio no es un diff de texto ni una fotografía del estado: es un paquete de operaciones con identidad propia. Sus campos son pocos y todos cumplen una función. El hash lo identifica de forma única y se calcula sobre su contenido, de modo que dos réplicas que produzcan el mismo cambio producen el mismo hash y la deduplicación es automática. Las dependencias son la lista de hashes de los cambios que el autor ya conocía cuando lo produjo, y son lo que codifica la causalidad. El actor identifica la sesión de escritura que lo generó, la secuencia lo ordena dentro de esa sesión, y la marca de tiempo y el mensaje son metadatos informativos.

Las dependencias merecen atención porque son el mecanismo entero. Al declarar de qué cambios depende, cada cambio dice implícitamente «esto ocurrió después de aquello», sin necesidad de ningún reloj compartido. Dos cambios que no se alcanzan mutuamente recorriendo el grafo hacia atrás son concurrentes por definición, y esa definición es puramente estructural: no depende de en qué momento se escribieron ni de qué hora marcaba cada máquina. Todo lo que los niveles anteriores construyeron sobre relojes lógicos y vectores de versión está aquí resuelto de raíz, porque el grafo es el reloj.

Conviene apreciar lo que eso elimina. Un sistema que ordena por marca de tiempo hereda todos los problemas de los relojes: dispositivos desajustados, cambios de horario, usuarios que ajustan la hora a mano, y el caso patológico en que un reloj adelantado hace que una escritura futura gane para siempre contra todas las demás. Aquí la marca de tiempo existe pero es puramente informativa: sirve para enseñarla en una interfaz y no participa en ninguna decisión de fusión. Si mañana descubres que la mitad de tus dispositivos tenían la hora mal, tus documentos siguen siendo correctos.

flowchart LR
A[cambio raiz] --> B[cambio de ana]
A --> C[cambio de luis]
B --> D[fusion]
C --> D
D --> E[cabeza actual]
style C fill:#f9e2af,color:#11111b
style B fill:#f9e2af,color:#11111b
style E fill:#a6e3a1,color:#11111b

Las dos ramas amarillas del diagrama son concurrentes y lo son por estructura: ninguna aparece en el pasado de la otra. El nodo verde es la cabeza, y aquí conviene fijar el término porque es el que usa toda la API. Las cabezas de un documento son el conjunto de cambios que ningún otro cambio tiene como dependencia, es decir, las puntas del grafo. Normalmente hay una sola, pero justo después de recibir trabajo concurrente y antes de escribir encima puede haber varias, y ese conjunto de hashes es lo que identifica una versión del documento de forma exacta y portátil.

import * as A from "@automerge/automerge";

// Las cabezas identifican una version concreta. Guardalas si quieres volver.
const antes = A.getHeads(doc);

const despues = A.change(doc, { message: "renombrar el proyecto" }, (d) => {
  d.nombre = new A.ImmutableString("Proyecto Fenix");
});

// Estadisticas internas del documento: util para vigilar el crecimiento.
const s = A.stats(despues);
console.log(s.numChanges, s.numOps, s.numActors);

Recorrer el pasado y comparar dos puntos

Con las cabezas en la mano, las dos operaciones fundamentales sobre la historia son situarse y comparar. Situarse produce una vista inmutable del documento tal como estaba en ese punto; comparar produce la lista de modificaciones que llevan de un punto a otro.

// Vista del documento en un punto del pasado.
// Es una copia muy barata porque comparte memoria con el original.
const vistaAntigua = A.view(doc, antes);
console.log(vistaAntigua.nombre);

// Que cambio entre dos versiones: una lista de parches.
const parches = A.diff(doc, antes, A.getHeads(doc));

// Metadatos de todos los cambios posteriores a un punto.
const meta = A.getChangesMetaSince(doc, antes);
for (const c of meta) {
  console.log(c.hash, c.actor, c.time, c.message);
}

// Detalle completo de un cambio concreto, incluidas sus operaciones.
const detalle = A.inspectChange(doc, meta[0].hash);

Hay dos detalles de comportamiento que la documentación señala y que conviene no descubrir en producción. El primero: la vista es de solo lectura y no se puede pasar a la función de cambio, precisamente porque comparte memoria con el documento original en lugar de duplicarlo, que es lo que la hace tan barata. El segundo: si alguno de los hashes que pasas no está en el documento, situarse lanza un error mientras que comparar devuelve una lista vacía. Esa diferencia de trato importa cuando reconstruyes una versión a partir de cabezas guardadas hace tiempo en un dispositivo que puede no haber recibido todavía esos cambios.

Quién hizo qué, y hasta dónde llega esa respuesta

Aquí es donde hay que ser preciso, porque es el punto donde más gente construye una funcionalidad sobre una garantía que no existe. Cada cambio lleva un actor, y es tentador leerlo como «el usuario que hizo esto». No lo es. El actor es un identificador de sesión de escritura, generado localmente, que por defecto es aleatorio y puede cambiar entre sesiones del mismo usuario. Puedes fijarlo tú al inicializar el documento, y mucha gente lo hace poniendo el identificador de usuario, pero eso solo traslada el problema: nada en el documento verifica que quien escribió ese cambio fuera realmente quien dice ser.

La distinción es la que existe entre atribución y procedencia. La atribución es una etiqueta que el propio autor se pone y que sirve perfectamente para colaborar entre gente que confía entre sí: mostrar colores por autor, agrupar cambios, escribir un registro de actividad. La procedencia es una afirmación verificable sobre quién produjo un cambio, resistente a que alguien mienta, y requiere firmas criptográficas que la biblioteca no aplica hoy. El equipo trabaja de forma visible en añadir procedencia de autoría al núcleo, ligada a su capa de control de acceso, porque es también el requisito que faltaba para poder revocar permisos de forma coherente. Mientras eso no esté cerrado, la regla es sencilla: la autoría del documento vale para la interfaz, no para decidir a quién se le permite qué.

Qué habilita todo esto en un producto

La utilidad práctica de tener la historia dentro del documento es que un conjunto de funcionalidades que normalmente exigen infraestructura dedicada pasan a ser consultas locales. El historial de versiones deja de necesitar una tabla de auditoría en el servidor: guardas las cabezas en el momento que te interese y reconstruyes la vista cuando haga falta. La comparación entre dos versiones deja de necesitar un servicio que almacene instantáneas y las diferencie: la produce la biblioteca a partir de dos conjuntos de hashes. El registro de actividad deja de necesitar eventos emitidos a un sistema aparte: está implícito en los metadatos de los cambios.

Hay dos funcionalidades más que suelen pasar desapercibidas y que son las que de verdad justifican el modelo en ciertos dominios. La primera es el trabajo por ramas: como una versión es un conjunto de hashes y la fusión es una función pura, puedes dejar que alguien trabaje sobre una versión fija durante días y luego integrar, con la garantía de que la integración no puede fallar. Eso es lo que permite construir revisión de cambios sobre datos que no son código. La segunda es la reproducibilidad: ante un informe de error puedes reconstruir exactamente el estado que el usuario tenía al ocurrir, sin depender de que alguien hubiera pensado en registrarlo.

// Un historial de versiones completo cabe en muy poco codigo.
function historial(doc, desde) {
  return A.getChangesMetaSince(doc, desde).map((c) => ({
    id: c.hash,
    autor: c.actor,
    cuando: new Date(c.time),
    resumen: c.message ?? "sin descripcion",
  }));
}

// Y restaurar consiste en leer una vista antigua
// y volver a escribir su contenido como un cambio nuevo,
// nunca en borrar cambios del pasado.
function restaurar(doc, cabezasAntiguas) {
  const antiguo = A.view(doc, cabezasAntiguas);
  return A.change(doc, { message: "restaurar version anterior" }, (d) => {
    A.updateText(d, ["cuerpo"], antiguo.cuerpo);
  });
}

La segunda función merece un comentario porque encierra el patrón correcto para deshacer en esta arquitectura. Restaurar no es retroceder: es avanzar hacia un estado que se parece a uno anterior. El cambio que restaura se añade a la historia como cualquier otro, con su autor y su mensaje, y por eso se puede a su vez deshacer, sincronizar y fusionar sin sorpresas. Intentar implementar el deshacer eliminando cambios del grafo es el error que rompe la convergencia, porque cualquier réplica que todavía los tenga los volverá a introducir en la siguiente sincronización.