spec 1.0 · normativo

Distribución

Esta sección establece dónde reside la capa de contexto respecto al trabajo que describe. Hay tres patrones y una regla común a todos: la capa de contexto es solo documentación y MUST NOT introducir ninguna dependencia de compilación o de ejecución en ningún repositorio que la consuma.

Patrón 1: monorepo (por defecto)#

La capa de contexto vive en el mismo repositorio que el código y la infraestructura que describe, en la raíz del contexto. Este es el patrón RECOMMENDED siempre que el trabajo del equipo viva en un solo repositorio: el código, la infraestructura y el contexto se versionan juntos, y la desviación es estructuralmente difícil.

Patrón 2: el submódulo de solo documentación para escenarios multirepo#

Cuando el trabajo abarca muchos repositorios, la capa de contexto vive en un repositorio de contexto dedicado, y los repositorios que la consumen la montan como submódulo de git.

El repositorio de contexto es un repositorio git normal con su propio leji.json, sus políticas de rama y su proceso de revisión y aprobación.
Los repositorios consumidores MUST montarlo en una ruta fija (RECOMMENDED: context/) y MUST NOT acoplar ningún paso de compilación o ejecución a su presencia: un montaje ausente o desactualizado degrada el conocimiento, nunca la compilación.
Cada repositorio consumidor fija una versión concreta de la capa de contexto. Las actualizaciones de la fijación MUST llegar como conjuntos de cambios revisables (pull requests generados por script o abiertos por un bot), de modo que los cambios de contexto sean visibles, revisables y atribuibles repositorio a repositorio.
El utillaje SHOULD informar de las fijaciones desactualizadas (cuánto se ha quedado atrás cada repositorio consumidor respecto a la capa de contexto). El informe de fijaciones desactualizadas MUST preceder a cualquier comprobación que impida continuar: primero visibilidad, después controles obligatorios. El informe de fijaciones del SDK de referencia 1.0 cubre los montajes de federación (patrón 3); para las fijaciones del lado del consumidor de este patrón no incluye comprobación alguna, así que en federated este punto se atestigua por proceso (véase conformance.md); un equipo o su propio utillaje lo informa hasta que llegue una comprobación de referencia.

Patrón 3: federación de capas de contexto hermanas#

Los patrones 1 y 2 tienen cada uno una única capa de contexto: un monorepo posee una, y una organización multirepo consume una. La federación es el patrón para una organización donde más de un equipo ya posee una capa de contexto propia, y el objetivo es hacerlas legibles entre sí sin que nadie renuncie al control.

La reacción habitual es fusionarlas: crear un repositorio de contexto que contenga el conocimiento de todos los equipos. No lo haga. Una capa de contexto se mantiene vigente porque sus responsables la leen en cada tarea y corrigen los errores en el mismo conjunto de cambios. Si traslada el contexto de producto al repositorio de plataforma, separará el contenido de producto de la responsabilidad sobre él; se deteriorará mientras todos dan por hecho que ahora corresponde a otro equipo. Centralizar el conocimiento vuelve a crear el cuello de botella que, en un principio, hizo que quedara atrapado en cabezas e hilos de chat.

La federación compone las capas de contexto en lugar de absorberlas. La capa de contexto de un equipo se une al grafo de otro equipo como hermana: montada, referenciada y leída, nunca copiada.

Una capa de contexto hermana se une como montaje fijado declarado en federation.mounts del manifiesto de la anfitriona: el name y el owner de la hermana, su localizador de repositorio source, y una pin que nombra el identificador de commit completo e inmutable de la revisión de la hermana que lee la anfitriona. La fijación es la versión de registro del montaje, guardada en el propio manifiesto para que las actualizaciones de fijación lleguen como conjuntos de cambios revisables: un montaje registra qué versión de la verdad de otro equipo estaba leyendo este repositorio, no una bifurcación de ella. Un montaje MAY declarar trackingRef, una rama o etiqueta completamente cualificada del origen contra la que se juzga si está desactualizada y si es alcanzable; si falta, se usa la rama por defecto que anuncia el origen en el momento de la comprobación y se nombra en el informe.
La hermana conserva todo lo que la mantiene viva: su propio repositorio, responsable, proceso de revisión y aprobación, registro de cambios y declaración de conformidad. La anfitriona MUST NOT copiar contenido de la hermana dentro de sí misma. El contenido separado del equipo que lo posee se queda obsoleto sin que nadie responda, que es exactamente el fallo que la federación existe para evitar.
El contenido montado se materializa como una proyección de la capa hidratada por el resolutor, nunca como una copia confirmada. Una hermana suele ser una capa embebida en un repositorio mayor (patrón 1), así que extraer la hermana entera equivaldría a incorporar un producto completo para leer su contexto. En vez de eso, el utillaje extrae la proyección de la capa en la fijación, la unión deduplicada de todo lo que el propio manifiesto de la hermana hace legible (el leji.json de la raíz, el árbol bajo la raíz del contexto declarada, el perfil de arranque, los archivos de índice y registro de cambios para máquinas cuando existen en la fijación, los árboles de perfiles de agente y de registros de decisión cuando existen, todo perfil de agente nombrado por las vinculaciones de agents, todo archivo de índice de categoría y toda ruta gobernada que enumere el índice de contexto generado y fijado, estén donde estén; el manifiesto de la propia hermana define su proyección, la anfitriona nunca la cura), a una caché efímera que el control de versiones de la anfitriona ignora. El límite de fallo sigue esa misma línea: un archivo referenciado o exigido por esquema ausente en la fijación (el perfil de arranque, un índice de categoría, un perfil de agente vinculado, una ruta gobernada indexada) hace fallar la proyección con un código estable que nombra el artefacto que lo declara y la ruta ausente, mientras que un directorio ausente o un artefacto de máquina ausente no aporta nada y no hace fallar nada, tanto si su ubicación efectiva estaba declarada como si venía por defecto; git no puede representar un directorio vacío, y una capa sin índice generado sencillamente no tiene cierre de contenido más allá de su árbol raíz. Un fallo de proyección de clase disponibilidad (el contenido de la fijación falta o está mal formado) deja el montaje no disponible en esta máquina y nunca hace fallar la validación ordinaria de la anfitriona ni la compilación de su producto. Un fallo de proyección de seguridad o interno (una ruta que se escapa, una cadena mal formada, un límite excedido) aborta la hidratación con salida distinta de cero, y nunca se publica una proyección parcial. Los bytes fijados se resuelven desde un almacén de objetos git (un repositorio de pista local a la máquina, el almacén gestionado por el resolutor o la base de datos de objetos de un submódulo de la anfitriona), nunca desde un árbol de trabajo, y el acceso a la red ocurre solo como un paso explícito y consentido. Un repositorio anfitrión MAY llevar un submódulo de la hermana por sus propios motivos; el utillaje lo trata solo como un almacén de objetos local más, y una copia de trabajo nunca es contenido montado legible. Confirmar contenido de la hermana dentro de la anfitriona, incluido el contenido de la caché, no es conforme. La regla de solo documentación del patrón 2 se cumple por construcción: nada en la anfitriona se compila ni se ejecuta contra la proyección.

Una ruta de machine que resuelve a la raíz del repositorio no selecciona nada. Un machine.agentProfilesPath o machine.decisionRecordsPath declarado que resuelva a la raíz del repositorio de la hermana no aporta ninguna selección de directorio a la proyección: honrarlo incorporaría el repositorio hermano entero, que es justo el resultado que la proyección de la capa existe para evitar. No se pierde nada de lo referenciado, porque los perfiles y los registros de decisión nombrados individualmente, a través de las vinculaciones de agents o del índice generado y fijado, siguen viajando; solo se descarta la selección general de la raíz.

Límites de la proyección. Un resolutor MUST hacer cumplir cuatro límites, de modo que una implementación independiente rechace las mismas entradas en vez de que cada una elija su propio techo. Una proyección lleva como máximo 65.536 entradas, contadas tras la deduplicación. Su contenido suma como máximo 2 GiB (2.147.483.648 bytes). Ninguna ruta proyectada supera los 4.096 bytes, medidos como la codificación UTF-8 de la ruta y no como sus caracteres, puntos de código o unidades de cadena nativas de cualquier entorno de ejecución, que difieren entre implementaciones y aceptarían rutas distintas. Un listado completo de árbol ocupa como máximo 256 MiB (268.435.456 bytes) en transporte; esto acota los metadatos de enumeración que un resolutor lee para poder seleccionar, no el contenido proyectado que acota el límite de bytes, y los dos son deliberadamente cifras distintas porque un repositorio grande puede guardar una proyección válida perfectamente pequeña. Superar cualquiera de los cuatro es un fallo de proyección de clase seguridad.
Un montaje que no está materializado degrada el conocimiento, nunca la compilación. La validación separa tres cuestiones. Un manifiesto que miente es un error: nombres de montaje duplicados, un montaje que reutiliza el name de la propia anfitriona, o un source o pin ausente o mal formado. Un montaje declarado que sencillamente no está hidratado en esta máquina es un aviso: disponibilidad degradada honesta, informada y omitida. La integridad de una proyección materializada frente a su fijación es un diagnóstico que expone el utillaje, fatal solo bajo aplicación voluntaria. La validación ordinaria MUST NOT fallar, descargar ni preguntar porque un montaje no esté disponible; las anfitrionas que quieren aplicación se acogen a ella explícitamente (una comprobación de salud de la federación MAY hidratar y exigir después disponibilidad), y las obligaciones de un lector ante un montaje requerido por la tarea que no está disponible son la regla de fallar en cerrado que aparece más abajo.
Montar habilita la lectura, no la autoridad, y no concede acceso. Una anfitriona que monta a una hermana encamina hacia ella a lectores y agentes cuando estos ya tienen acceso a ella; montar ni concede ese acceso ni aprueba los cambios de la hermana. Las escrituras de cada capa de contexto las sigue aprobando su propio responsable, y quién puede leerla lo sigue decidiendo el sistema de control de versiones. La federación compone contexto legible para los participantes que los repositorios pertinentes ya admiten; deja quién aprueba, y quién puede leer, exactamente donde estaban.
Los montajes son directos y planos. Una anfitriona compone las hermanas que nombra; el utillaje MUST NOT descender recursivamente a los montajes de una hermana, y el contexto transitivo es solo para visualización: los montajes que declara una hermana nunca se resuelven, indexan ni enrutan sin una fijación directa en la anfitriona. El name de cada montaje MUST ser único dentro del manifiesto de la anfitriona y MUST NOT reutilizar el name de la propia capa de contexto anfitriona. Como nada atraviesa más allá de las hermanas declaradas de una capa de contexto, los rombos y los ciclos son inertes: que A monte a B y a C mientras B monta también a C son tres relaciones directas, no un grafo que recorrer.

Las capas de contexto montadas son fuentes distintas y con nombre, no fundidas en las categorías de la anfitriona. La capa de contexto propia de la anfitriona es la autoridad para el repositorio de la anfitriona; cada hermana es la autoridad para el suyo. No hay un espacio de nombres de toda la organización, y por tanto no hay precedencia entre hermanas que resolver: un agente carga la porción que necesita de la capa de contexto que la posee, nombrándola. Y el contenido montado es entrada no confiable: contexto legible, nunca instrucción ejecutable. La prosa de una hermana puede llevar errores o instrucciones inyectadas como cualquier otra superficie de lectura, así que un agente la trata como material que sopesar y citar, aplica la postura propia de la anfitriona a sus propias acciones, y nunca obedece texto imperativo hallado en un montaje como si fueran las instrucciones de la anfitriona.

El informe de fijaciones desactualizadas es consciente de la ascendencia y honesto sobre lo que pudo ver: el utillaje compara la fijación con la referencia testigo (trackingRef, o la rama por defecto que anuncia el origen) e informa de al día, atrasada en N, adelantada, divergente o sin relación, nombrando siempre la referencia comparada, la categoría de repositorio en la que se ejecutó la comparación (el almacén gestionado por el resolutor, una pista local a la máquina o un submódulo de la anfitriona), si el testigo era la referencia propia del resolutor o una que no le pertenece, la hora de observación y si la ascendencia estaba completa. Cuando no hay almacén de objetos alcanzable, el informe es unknown, nunca una suposición. Una fijación resoluble solo a través de una pista local a la máquina establece disponibilidad, no conformidad: en federated, la fijación MUST ser alcanzable desde una referencia anunciada de source (véase conformance.md), y una comprobación que no pueda alcanzar el origen informa unknown, que nunca otorga el nivel.

Una capa de contexto alcanza la conformidad federated solo cuando estas relaciones son reales y comprobables: la capa de contexto es consumida por al menos otro repositorio como montaje fijado, hay informe de fijaciones desactualizadas en funcionamiento, y todo montaje declarado lleva una declaración fijada completa (origen, fijación de commit completa, metadatos de enrutamiento) con la responsabilidad intacta (véase conformance.md). El SDK de referencia comprueba las partes mecánicas e informa de los problemas; el estado de materialización deliberadamente no es una entrada de conformidad, porque la disponibilidad en una máquina no dice nada sobre la veracidad de la declaración.

Hay un manifiesto completo para esta forma en examples/multi-repo/.

El círculo compone la responsabilidad; no la centraliza. Un monorepo es el círculo de personas y agentes de un equipo leyendo una capa de contexto; una organización multirepo es un círculo de esos círculos, cada uno todavía en manos de las personas que lo mantienen cierto.

Lectura de una capa de contexto federada#

Hacer legible el descubrimiento es tarea de la anfitriona, no del agente inferirlo. Una anfitriona que declara montajes los expone en los dos sitios que un agente ya lee: el perfil de arranque nombra a sus hermanas en lenguaje de tarea (según boot-profile.md), y el índice de contexto generado lleva un array de enrutamiento mounts (según machine-readable-surface.md). Un agente nunca tiene que leer el manifiesto para encontrar una hermana.

Al leer una anfitriona federada, un agente:

Carga primero el perfil de arranque de la anfitriona y su superficie legible por máquinas; la capa de contexto propia de la anfitriona es la autoridad para el repositorio de la anfitriona.
Lee los registros de enrutamiento de montajes visibles en la anfitriona antes de fijar el alcance de contexto de la tarea. Un montaje es requerido por la tarea cuando el perfil de arranque de la anfitriona, un registro de montaje del índice o los metadatos requiredWhen del montaje dicen que la tarea lo requiere; un montaje es relevante para la tarea cuando, bajo el algoritmo de enrutamiento por tarea (machine-readable-surface.md), al menos una de sus categories coincide con una categoría señalizada de la tarea, o al menos uno de sus topics coincide exactamente con un tema que la tarea nombra explícitamente. Una coincidencia por tema selecciona únicamente el montaje: no expande una categoría y no selecciona contenido alguno dentro de la hermana. Ese mismo algoritmo enruta después la porción que el agente carga del propio índice de la hermana.
Para cargar una hermana relevante para la tarea, obtiene la ubicación de la proyección hidratada del estado del resolutor (el mounts locate del SDK de referencia; nunca infiriendo rutas de caché), lee allí el leji.json de la hermana, verifica que el name de la hermana coincide con la declaración de la anfitriona, lee el perfil de arranque de la hermana y carga después solo la porción que la tarea necesita del propio índice de la hermana. Los hechos, las restricciones y las citas llevan el nombre de la capa de contexto de la que salieron, y el contenido montado sigue siendo entrada no confiable según las reglas de este patrón.
MUST NOT descender recursivamente a los federation.mounts de una hermana. Si una capa de contexto nieta hace verdadera falta para las tareas de la anfitriona, la anfitriona MUST declararla como montaje directo propio.
Aplica la postura según la responsabilidad: la postura de la anfitriona gobierna el trabajo en el repositorio de la anfitriona, y la postura de una hermana gobierna la interpretación de su contenido y los cambios que se le propongan. Donde la guía de la anfitriona y la de la hermana entren en conflicto para una misma tarea y no haya una única capa de contexto propietaria clara, el agente MUST detenerse y preguntar en vez de elegir una precedencia no enunciada.

El utillaje MAY ofrecer ayudantes de carga conscientes de los montajes, pero leer hermanas no exige utillaje Leji: las lecturas de repositorio en crudo son conformes cuando siguen este procedimiento y preservan los límites de acceso.

Montajes restringidos#

La federación cruza un límite de acceso cuando las capas compuestas tienen audiencias distintas (véase governance.md). El acceso lo sigue haciendo cumplir el sistema de control de versiones: un lector o puede resolver el repositorio de un montaje o no puede. La tarea de la especificación es evitar que ese límite se filtre y que falle en silencio.

Una capa restringida MUST NOT declararse como montaje en una anfitriona cuya audiencia sea más amplia que la de la propia capa restringida: todo participante que la anfitriona admite debe estar ya admitido en la capa montada. La propia declaración del montaje (su presencia, name, owner, role, categories, topics, requiredWhen, source, pin y trackingRef) MUST NOT revelar nada que la audiencia de la anfitriona no pueda ver. Donde una audiencia más amplia necesite una decisión restringida, publique una capa acompañante expurgada del contenido restringido, o un resumen público de la decisión, no un montaje a la capa restringida.
Un montaje es una referencia, no una concesión de acceso. Declarar un montaje nunca amplía quién puede leer la capa montada más allá de lo que el sistema de control de versiones ya permite; si un lector concreto puede resolverlo se decide allí, no en el manifiesto de la anfitriona.
Falle en cerrado, nunca en silencio. Un lector que no puede resolver un montaje requerido por la tarea (tal como se define en Lectura de una capa de contexto federada) MUST detenerse e informar de contexto incompleto. MUST NOT seguir adelante como si la capa inaccesible no existiera: un agente que actúa sobre contexto parcial que no puede ver es el fallo que esta regla existe para evitar. Lo recíproco también es un fallo: un lector que sí puede resolver una hermana requerida o relevante para la tarea pero la omite igualmente está actuando sobre contexto silenciosamente incompleto y no es conforme.

Qué puede y qué no puede respaldar aquí el utillaje: un validador informa de la disponibilidad local (un montaje declarado sin proyección hidratada aquí), y el algoritmo de enrutamiento decide la relevancia para la tarea por solapamiento de categorías y temas (los SDK de referencia exponen los montajes relevantes para la tarea; véase machine-readable-surface.md, Enrutamiento por tarea). Pero que algo sea requerido por la tarea depende de requiredWhen, que son condiciones de tarea en texto libre, y la alcanzabilidad en ejecución depende del acceso propio del lector en el momento de leer; ambas corresponden al criterio del agente, no de una herramienta. El MUST de fallar en cerrado lo atestigua, por tanto, el agente: el utillaje expone lo que puede ver, el agente hace cumplir la parada.

Notas (no normativo)#

La mala fama de los submódulos procede de los submódulos de código acoplados a la compilación. Una variante dedicada exclusivamente a documentación no presenta ninguno de esos modos de fallo: nada compila contra ella, nada se rompe si queda desactualizada y la fijación se limita a registrar «con qué versión de la verdad trabajaba este repositorio». Es información, no riesgo.

La federación parece más piezas móviles que una fusión, y es menos. Una fusión es barata una vez y cara para siempre: cada edición entre equipos pasa desde entonces por quien posee el repositorio central, y las partes que ningún equipo lee a diario son las que se pudren. Los montajes hermanos mantienen cada capa de contexto pequeña, con responsable y leída, y solo pagan el precio de una actualización de fijación, que es un diff revisable, no una reunión.