Cuándo elegirlo: el perfil que encaja y el que no

Después de cuatro lecciones sobre lo que la biblioteca hace bien, la más útil del nivel es la que delimita dónde deja de ser la respuesta correcta. Automerge no es una base de datos con sincronización ni un sustituto general de tu capa de persistencia: es un tipo de dato con forma de documento y con historia, y todo su perfil de aptitudes se deriva de esas dos palabras. Cuando tu problema tiene esa forma, la biblioteca resuelve de golpe cosas que de otro modo costarían meses de infraestructura: trabajo sin conexión, fusión garantizada, ramas, historial, funcionamiento entre pares sin servidor. Cuando tu problema no tiene esa forma, cada una de esas mismas propiedades se convierte en un impuesto que pagas sin recibir nada. Esta lección traza la frontera con precisión, la contrasta con las alternativas que el track ya ha recorrido y termina con un criterio de decisión que puedes aplicar en una tarde.

El perfil donde encaja

Hay cuatro rasgos que, cuando aparecen juntos, hacen de Automerge la mejor opción disponible y no solo una opción viable. El primero es que el dato tenga una frontera natural de documento: una nota, un diseño, un proyecto, un tablero, un cuaderno. Algo que una persona abre, que tiene un tamaño acotado por su propia naturaleza y que se comparte como unidad. Si al describir tu dominio usas espontáneamente la palabra archivo o la palabra documento, es buena señal.

El segundo es que la historia sea una funcionalidad y no un residuo. Si tu producto quiere mostrar versiones anteriores, comparar dos estados, atribuir cambios, permitir ramas o deshacer selectivamente, entonces estás obteniendo gratis lo que en otra arquitectura tendrías que construir con tablas de auditoría e instantáneas. Si tu producto no quiere nada de eso, estás pagando el almacenamiento de la historia a cambio de nada.

El tercero es que el trabajo sin conexión o con conexión mala sea normal y no excepcional. El cuarto es que la topología no esté fijada: que quieras poder sincronizar contra un servidor hoy, entre pares mañana y por un archivo compartido pasado, sin cambiar el modelo de datos. Los ejemplos reales del ecosistema ilustran bien el patrón: colaboración en proyectos de motores de videojuegos con ramas y fusiones que convive con el control de versiones tradicional, coedición en tiempo real de archivos de texto locales desde cualquier editor, o un rastreador de incidencias donde todas las incidencias de un proyecto viven en un único documento que muchos agentes editan en paralelo desde máquinas distintas.

Hay un quinto rasgo que no suele aparecer en las listas y que en la práctica decide muchas adopciones: la longevidad. Un documento es un archivo binario autocontenido con un formato estable y documentado, que no necesita el servicio que lo creó para abrirse. Si tu producto promete que los datos del usuario le pertenecen —y ese es el compromiso que da nombre al movimiento local-first— entonces necesitas un formato que sobreviva a tu empresa, y muy pocas capas de sincronización te lo dan. Que la versión 3 pudiera rehacer el motor entero sin romper la compatibilidad de los archivos de la versión 2 es la mejor evidencia disponible de que esa promesa se puede sostener.

Dónde el modelo de documento se queda corto

Los límites son tres y ninguno se arregla con configuración, porque los tres son consecuencias directas de que la unidad sea el documento.

El primero es la granularidad. El documento se carga entero, se sincroniza entero y se comparte entero. No hay carga parcial de una sección, no hay consulta que devuelva un subconjunto sin materializar el resto, y no hay forma de compartir la mitad de un documento con alguien. En cuanto tu colección crece, la salida es trocear en muchos documentos pequeños con un documento índice que los referencia, y ahí empieza el problema de verdad: acabas reconstruyendo a mano lo que una base de datos te daba hecho, incluidos los índices secundarios, la paginación y la coherencia entre documentos. Los proyectos serios del ecosistema trabajan con miles de documentos abiertos a la vez, y eso funciona, pero es una arquitectura que hay que diseñar deliberadamente y no algo que emerja solo.

// El patron de documento indice, que acabaras escribiendo si creces.
// Un documento raiz que solo guarda referencias y metadatos ligeros.
const indice = A.from({
  proyectos: {
    // clave: identificador del documento hijo
    // valor: solo lo que necesitas para listar sin abrirlo
    "automerge:2akvofn6L1o4RMUEMQi7qzwRjKWZ": {
      nombre: new A.ImmutableString("Rediseno del portal"),
      actualizado: new Date(),
      archivado: false,
    },
  },
});

// Cada proyecto vive en su propio documento y se carga solo al abrirlo.
// El coste de esta arquitectura: los metadatos del indice estan
// duplicados y hay que mantenerlos coherentes a mano en cada escritura.

Ese fragmento parece inocente y contiene el trabajo entero. En cuanto duplicas el nombre del proyecto en el índice tienes dos fuentes de verdad que pueden divergir, y mantenerlas coherentes exige que cada escritura sobre el documento hijo actualice también el padre, con el problema añadido de que ambas escrituras no son atómicas entre sí. Cuando además quieras filtrar, ordenar por un campo que no está en el índice o contar elementos que viven dentro de los hijos, descubrirás que has empezado a escribir un motor de consultas. No es un argumento contra la arquitectura, es un aviso de a qué te estás comprometiendo.

El segundo es la ausencia de consultas. No hay lenguaje de consulta, no hay agregación entre documentos y no hay transacciones que abarquen más de uno. Si tu producto necesita responder «cuántos elementos cumplen esta condición en toda la colección», tendrás que mantener tú el índice, actualizarlo en cada cambio y asegurarte de que converge, lo cual es un CRDT adicional que ahora te toca diseñar. Este es el punto donde los niveles del track dedicados a SQLite en el cliente vuelven a ser relevantes, porque resuelven exactamente lo que aquí falta.

El tercero es el control de acceso. Cualquier réplica que tenga el documento puede escribir en él lo que quiera, y como vimos en la tercera lección la autoría registrada es una etiqueta que el propio autor se pone, no una afirmación verificable. No hay validación del lado del servidor de forma natural, porque no hay un lado del servidor privilegiado en el modelo. Existe una capa de control de acceso en desarrollo activo, con cifrado de extremo a extremo y con el trabajo de procedencia de autoría que hace posible revocar permisos, pero a día de hoy es trabajo en curso y no una casilla que se marque.

Frente a las alternativas

El track ha recorrido las opciones que compiten aquí, así que el contraste se puede hacer en términos ya conocidos. Frente a SQLite ejecutándose en el cliente, la diferencia es consultas contra fusión: la base de datos te da un lenguaje de consulta, índices y colecciones grandes, y te deja a ti el problema de la reconciliación; Automerge te da la reconciliación demostrada y te deja a ti el problema de las consultas. Elegir es decidir cuál de los dos problemas prefieres tener, y la respuesta honesta depende de si tu dominio es más parecido a un editor o más parecido a un catálogo.

Frente a las bibliotecas centradas en edición en vivo, la diferencia es la historia. Esas bibliotecas son más pequeñas, arrancan más rápido y en muchos casos consumen menos, porque tratan la historia como algo prescindible una vez fusionado. Si lo único que necesitas es que varios cursores editen a la vez y nadie va a pedir nunca una versión anterior, esa renuncia es una ventaja y no un defecto. Si en cambio la historia es parte del producto, reconstruirla encima de una biblioteca que no la conserva es un proyecto en sí mismo.

Frente al servidor autoritativo con última escritura ganadora, la pregunta es si la autoridad central existe de verdad. Si tu dominio ya tiene un árbitro legítimo —un sistema de pagos, un inventario, un expediente regulado— entonces el modelo sin coordinación te está resolviendo un problema que no tienes y complicándote uno que sí tienes. Y frente a los algoritmos de la familia de los registros de eventos que vimos en el nivel anterior, la diferencia está en el perfil de memoria en reposo para documentos de texto con historias muy largas, un terreno donde aquellos siguen teniendo ventaja estructural aunque la versión 3 haya recortado buena parte de la distancia.

Conviene añadir un eje de comparación que las tablas técnicas omiten y que pesa mucho en un proyecto real: qué te dan hecho más allá del tipo de dato. Aquí el ecosistema incluye una capa de repositorio que resuelve almacenamiento, compactación y transporte con adaptadores intercambiables, integración con interfaces reactivas, un sistema de sincronización de servidor en evolución con transportes tanto cliente-servidor como entre pares, y herramientas de diagnóstico como el anonimizador que permite compartir un documento problemático conservando su estructura exacta pero eliminando su contenido. Ese último detalle dice más sobre la madurez operativa del proyecto que cualquier banco de pruebas: existe porque alguien tuvo que depurar documentos reales de usuarios reales que no se podían enseñar.

flowchart TD
A[tiene el dato frontera natural de documento] -->|no| B[base de datos en el cliente con capa de sincronizacion]
A -->|si| C[la historia es parte del producto]
C -->|no| D[biblioteca de edicion en vivo mas ligera]
C -->|si| E[existe una autoridad central legitima]
E -->|si| F[servidor autoritativo con cache optimista]
E -->|no| G[Automerge]
style G fill:#a6e3a1,color:#11111b
style B fill:#89b4fa,color:#11111b
style D fill:#89b4fa,color:#11111b
style F fill:#89b4fa,color:#11111b

El criterio de decisión

Cuatro preguntas bastan, y conviene responderlas por escrito y por tipo de dato antes de comprometer nada. La primera: ¿el dato tiene una frontera natural de documento y un tamaño acotado por su naturaleza? Si para responder tienes que inventar una partición artificial, la respuesta es no. La segunda: ¿la historia es algo que el producto muestra o algo que el sistema soporta? Si nadie va a mirarla nunca, estás pagando por almacenarla sin razón.

La tercera: ¿existe una autoridad legítima que pueda decidir en caso de discrepancia? Si existe, revisa muy en serio si necesitas fusión sin coordinación. La cuarta: ¿puedes escribir hoy tu política de retención y de permisos y comprobar que es realizable sobre una estructura que no olvida y que no autoriza? Si esa comprobación falla, el problema no es de implementación y no va a mejorar con el tiempo.

// Una plantilla para responderlas por escrito, entidad por entidad.
const clasificacion = [
  {
    entidad: "documento de nota",
    arbitro: null,              // nadie puede decidir por los dos
    frontera: "la nota",        // natural y acotada
    historiaVisible: true,      // el usuario ve versiones
    retencionExigida: false,    // no hay datos personales dentro
    decision: "Automerge",
  },
  {
    entidad: "linea de facturacion",
    arbitro: "servicio de cobros",
    frontera: null,             // habria que inventarla
    historiaVisible: false,
    retencionExigida: true,     // hay obligacion de suprimir
    decision: "base de datos con servidor autoritativo",
  },
];

La columna que más discusión genera es la del árbitro, y es la que hay que rellenar primero porque anula a todas las demás. Si existe un árbitro legítimo, ninguna de las otras respuestas importa. Solo cuando la casilla queda vacía tiene sentido seguir bajando por la lista, y esa es la razón de que el árbol de decisión de esta lección la ponga al final y no al principio: para llegar a ella ya has descartado los casos donde la pregunta no procede.

Termina con una nota de contexto para calibrar el riesgo de adopción. El proyecto ronda las ochenta y cinco mil descargas semanales, tiene un núcleo mantenido activamente, una capa de sincronización en evolución, una capa de control de acceso en desarrollo y un ecosistema pequeño pero real de productos que lo usan en serio. Es una tecnología madura en lo que lleva años estabilizado —el modelo de datos, el formato, la semántica de fusión— y todavía en movimiento en lo que rodea a esos cimientos. Adoptarla es una apuesta razonable si tu dependencia principal está en la parte estable y no en la que aún se está escribiendo.