guía

Federación

Traducción asistida por agentes de IA. Ante cualquier diferencia, prevalece la página en inglés. Si encuentra algún problema en el texto, abra un issue o envíe un pull request.

La federación permite que los equipos consulten conjuntamente capas de contexto con responsables distintos, sin fusionarlas ni transferir la responsabilidad de mantenerlas vigentes.

Por qué componer en lugar de centralizar

Una capa de contexto se mantiene vigente porque sus responsables la leen y corrigen mientras trabajan. Centralizar el contenido de otro equipo lo aleja de las personas que responden de él. La federación deja intactos cada repositorio, cada responsable y cada flujo de revisión. La justificación lo argumenta por extenso.

Qué es un montaje hermano

Una hermana es la capa de contexto de otro equipo, declarada por la anfitriona en federation.mounts. La declaración fija el commit completo e inmutable que lee la anfitriona y registra la responsabilidad y el enrutamiento por tarea. El utillaje materializa en una caché ignorada la proyección de la capa que define el manifiesto de la hermana en esa fijación. Nunca copia contenido de la hermana dentro de la anfitriona.

La proyección es la unión de lo que el propio manifiesto de la hermana hace legible en la fijación: su leji.json, su raíz del contexto, su perfil de arranque, sus archivos de índice de categoría, los perfiles que nombran sus vinculaciones de agents, sus árboles de perfiles de agente y de registros de decisión, su índice y su registro de cambios para máquinas, y toda ruta gobernada que enumere su índice generado, estén donde estén.

Una hermana suele estar dentro de un repositorio de producto mayor, así que ese límite es lo que evita que un montaje incorpore el producto entero para leer su contexto.

Un montaje es una referencia, no una bifurcación ni una concesión de acceso. La hermana sigue siendo la autoridad y su control de versiones sigue decidiendo quién puede leerla. Montar hace legible la relación y la revisión elegida para quienes ya tienen acceso.

"federation": {
   "mounts": [
      {
         "name": "product-context",
         "source": "https://github.com/acme/product-context",
         "pin": "7d3f2a19c4e8b6a0d5f1c2e9b8a7f6d5c4b3a2e1", // id de commit completo: la versión de referencia
         "trackingRef": "refs/heads/main",                    // la desactualización se determina respecto a esta referencia
         "owner": { "name": "Product team", "contact": "product@acme.example" },
         "role": "product-side context, owned by the product team",
         // enrutamiento: cuándo es relevante este montaje para una tarea
         "categories": ["domain", "decisions"],
         "requiredWhen": ["a task changes how a plan or entitlement is represented"]
      }
   ]
}

Las actualizaciones de fijación son cambios revisados de leji.json. La anfitriona declara la relación; la hermana conserva su propio repositorio, responsable, proceso de revisión y aprobación, registro de cambios y declaración de conformidad.

Trabajar con los montajes

leji mounts hydrate --fetch      # materializa la proyección de cada hermana en su fijación
leji mounts status               # disponibilidad, integridad y retraso de cada fijación
leji mounts update-pin <name>    # adelanta una fijación hasta el commit observado
leji mounts locate <name>        # ubicación desde la que un lector debe leer la hermana

Use hydrate --fetch para materializar cada proyección en su fijación, con una descarga de red explícita. Use status para inspeccionar la disponibilidad, la integridad y el retraso de las fijaciones. Use locate para obtener la ruta gestionada por el resolutor donde un lector debe abrir una hermana.

Para mantener un montaje al día, repita ese mismo ciclo: hydrate --fetch para observar los orígenes, status para comprobar cuánto se ha retrasado cada fijación, update-pin para adelantar una fijación hasta el commit observado por el resolutor y, después, hydrate de nuevo para materializar la proyección en la nueva fijación. Mover la fijación y materializarla son actos separados, de modo que la reescritura produce un diff que puede revisarse antes de que cambie el contenido que se está utilizando.

update-pin funciona offline de forma predeterminada: avanza hasta la última referencia observada en una ejecución y lo indica expresamente en la salida, sin dar a entender que esté vigente. Añada --fetch para observar el origen declarado durante la ejecución, lo que contacta con ese origen y con nada más; si alguna parte de eso falla, la ejecución se niega y deja leji.json intacto. La fijación solo avanza. Un destino que no sea descendiente de la fijación actual se rechaza salvo que usted lo nombre explícitamente con --to <oid> y añada --allow-non-fast-forward. Una rama de origen que fue reescrita es el motivo habitual para recurrir a ese par de opciones; una vuelta atrás deliberada a un commit anterior también las necesita, porque lo que se comprueba es la ascendencia y no si se reescribió el historial. Esa combinación siempre genera un aviso y queda anotada en la salida JSON, porque mueve una fijación a un commit al que la actual no llega. Use --dry-run para ver la comparación y la reescritura sin reescribir el manifiesto; combinado con --fetch sigue realizando los actos de almacén y de red de esa opción, así que los objetos y las referencias descargados sí acaban en el almacén gestionado.

Solo se reescriben los bytes de la propia fijación, así que el orden de sus campos, su formato y cualquier clave que el esquema no modele sobreviven a la edición sin cambios. La entrada de caché de la fijación antigua se queda donde está: está direccionada por contenido, así que sencillamente deja de estar referenciada. No hay comando de recorte; elimine a mano las entradas antiguas bajo .leji/mounts/ cuando quiera recuperar el espacio.

La hidratación no publica ninguna proyección parcial. La caché vive bajo .leji/mounts/, que init añade al .gitignore de la raíz. Trate esa ruta como un detalle de implementación: locate informa de dónde leer una hermana, y fijar en el código una ruta de caché se rompe cuando cambia la publicación.

El visor muestra el mismo estado sin terminal. leji viewer genera una página de manifiesto que representa gráficamente la anfitriona y sus hermanas, y después muestra una fila por montaje: disponibilidad, desviación, responsable, fijación y origen. Vuelva a generarla después de hidratar.

Declarar federated

Un montaje sin hidratar es un aviso, nunca un fallo de compilación. La integración continua puede exigir la disponibilidad explícitamente con leji validate --federation=available|required. La validación ordinaria no descarga ni exige todos los montajes.

La disponibilidad local no es conformidad. La fijación debe ser alcanzable desde una referencia anunciada de source, lo que requiere red. Ejecute leji conformance --federation=verify para esa comprobación. Si la comprobación no puede alcanzar el origen, informa unknown; unknown nunca otorga el nivel.

La verificación es necesaria, no suficiente. federated exige además que esta capa de contexto sea a su vez consumida por otro repositorio como montaje fijado, que haya informe de fijaciones desactualizadas en funcionamiento, y que el perfil de arranque y el índice generado expongan a todas las hermanas.

Los dos primeros se atestiguan por proceso, así que verifiedLevel nunca los afirma en su nombre. Materializar en una máquina no es una entrada de conformidad.

Elija primero el patrón de distribución

Un submódulo de git de solo documentación permite que muchos repositorios consuman una capa de contexto. La federación conecta varios equipos que ya poseen una cada uno. Estos patrones responden a preguntas distintas, así que la federación no sustituye al submódulo. La guía de adopción conserva el procedimiento completo del submódulo.

Lea distribución para el cierre normativo de la proyección, el límite de fallo y las reglas completas de federación.