Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

aggrega pull

aggrega pull resuelve todas las dependencias de una Release y escribe un lockfile que fija cada dependencia a una versión y un digest de contenido exactos. Un aggrega build posterior usa lo que fija el lockfile, lo verifica y se detiene nombrando cualquier cosa que necesite y que no esté fijada ahí, de modo que las builds son reproducibles y pueden funcionar sin conexión.

Todo lo que consume una build se fija en este único momento. Las entidades del catálogo, los artefactos fuente a los que una Recipe dirige un provider y los documentos remotos que un provider pide mientras renderiza se resuelven con el mismo comando y se registran en la misma escritura del lockfile. aggrega pull es el paso que toca la red; la build no. Esa es toda la regla, y el resto de esta página es lo que se deriva de ella.

Qué hace

aggrega pull resuelve tres tipos de dependencia en una sola pasada:

  • Entidades del catálogo — los Components, Features, Recipes, FeatureRecipes, bibliotecas de esquemas y de mapeo, y plugins Wasm a los que hace referencia la Release, resueltos de forma transitiva (mediante extends:, implements:, aggregate:, las vinculaciones de Feature y los puntos $import: / $ref: de las bibliotecas) y obtenidos del registry cuando no están ya en local.
  • Artefactos de origen — la source: remota a la que una Recipe o FeatureRecipe concreta dirige un provider: un chart de Helm (OCI o HTTPS clásico) o un fragmento de Compose sobre HTTPS. Cada uno se obtiene, se almacena en caché y se fija.
  • Entradas externas — los documentos remotos que un provider solicita al host mientras renderiza, como un $ref en el values.schema.json de un chart que apunta a una URL. Cada una se obtiene, se almacena bajo su digest de contenido y se fija.

Dos de los tres se leen de los documentos que escribiste. El tercero no: las entradas externas se encuentran renderizando la Release, y por eso este comando realiza un renderizado. Ejecutar el comando no requiere nada de eso — Cómo encuentra la resolución las entradas externas lo explica por completo, junto con lo que cuesta el renderizado, lo que ocurre cuando no puede completarse y cómo se relaciona con ello un build que rellena su propio lockfile.

Una entidad del catálogo nombrada sin registry se obtiene a través del default_registry del espacio de trabajo, y una ruta de repositorio que incluya ese valor predeterminado es el lugar del que se obtiene. Con default_registry: ghcr.io/acme, core/api-server se obtiene de ghcr.io/acme/component/core/api-server — donde aggrega push lo publica mediante el mismo valor predeterminado — y es allí donde se busca su firma. La ruta solo indica la ubicación: la firma que exige un pull, las claves e identidades en las que confía y la credencial que presenta son las que se guardan para el host, de modo que la entrada registries para ghcr.io rige todas las rutas de ese host. El lockfile registra una entidad así por su identidad, su versión y sus digests, igual que registra una obtenida solo de un host. La forma de escribir una ruta se explica en cómo se escribe un host de registry.

El comando escribe el resultado en <release-stem>.lock junto a la Release. Un espacio de trabajo que vincula un plugin que devuelve un veredicto de aceptación o rechazo obtiene además un segundo archivo en ese directorio — el registro de confianza de plugins.

Un pull al que se le pide fijar escribe un tipo de archivo más. Junto a cada Recipe y FeatureRecipe de tus directorios de catálogo que importa un archivo de artefacto, apunta a una source: remota que escribiste por completo o lee una source: situada junto a ella, hay un entity.lock que registra el digest de ese contenido. Registrarlo es el paso del autor de la entidad, aggrega pin, y de forma predeterminada un pull no lo realiza: contrasta el lock de cada una de esas entidades con lo que el paso registraría, y se detiene donde falta un pin. aggrega pull --pin-sources, o un espacio de trabajo que establece pin_sources_at_pull: true, ejecuta el paso en su lugar — y entonces el efecto de un pull llega más allá del directorio en el que está la Release, aunque nunca se escribe en los archivos de entidad que creaste. El lock de la entidad describe ese archivo, y Vista previa de lo que escribiría un pull muestra el conjunto completo para tu espacio de trabajo antes de que nada cambie.

Un pull rechazado porque una referencia no se resolvió en nada indica de dónde se leen las entidades locales, dondequiera que se ejecute. El rechazo incluye la explicación del propio espacio de trabajo sobre los directorios de los que leyó entidades locales y qué cambiar para que se lea la entidad — la nota que muestra De dónde se leen las entidades locales — y la incluye desde este comando, desde un build que resuelve primero sus dependencias, desde la herramienta de pull de aggrega mcp e igualmente desde la resolución de dependencias de un editor, porque la compone la resolución que todos ellos ejecutan. El rechazo de la herramienta de pull también indica el código corto y el código descriptivo de la condición, igual que un terminal imprime el código corto al principio del rechazo. Un archivo de esos directorios que declara una apiVersion de Aggrega — una línea que empieza, sin sangría, con apiVersion: y un valor que comienza por aggrega.ai/ — y que no se pudo cargar, por ejemplo uno que no se puede analizar como YAML, se nombra en el mismo rechazo, entre los archivos de catálogo omitidos al cargar, con el motivo que da el propio analizador: ese archivo puede ser el que declara la entidad que nombra la referencia, y no se puede leer nada de él que diga qué entidad declara. Un archivo YAML que declara otra apiVersion, o ninguna, no es un documento de Aggrega y nunca se nombra allí.

El lockfile

El lockfile fija cada dependencia a su URI, su versión resuelta y su digest de contenido. Tiene secciones para las entidades del catálogo, las bibliotecas de esquemas y de mapeo (cada una con referencias inversas a los Components y las Features que la consumen), los plugins Wasm, los artefactos de origen, las entradas externas (cada una indexada por URL y con los plugins que la solicitaron) y los propios archivos de la Release. El archivo se escribe en una forma canónica y determinista.

Una entidad se registra por lo que contiene una publicación de ella. El digest de la fila de una entidad abarca su documento y cada archivo que nombra junto a él — la source: local de una Recipe o FeatureRecipe, cada archivo que nombra un $import:, el entity.lock que tiene al lado, cada archivo de esquema que importa un Component o una Feature — el mismo conjunto que publica aggrega push. Cada archivo aporta su ruta y sus bytes, y nada más aporta: ni cómo se comprimió un archivo comprimido, ni una marca de tiempo, ni un bit de permisos, incluido el bit de ejecución. Una entidad que no nombra ningún archivo se registra como ese único documento. Así, la misma entidad registra el mismo digest tanto si se leyó de tu directorio de catálogo como si se obtuvo de un registry, y un lockfile confirmado desde un checkout se verifica en otro checkout del mismo commit sea cual sea su umask, y tanto si el sistema de ese checkout registra qué archivos son ejecutables como si no. Un chart editado bajo una Recipe, un archivo añadido a una fuente que esta declara y un entity.lock modificado cambian cada uno el digest; un script cuyo bit de ejecución cambió, y una nota junto a la entidad que nada nombra, no. El Aggregate y el Manifest que nombra la Release se registran del mismo modo, cada uno como su único documento. Una biblioteca se registra por el digest de sus bytes, que son su documento dondequiera que se lea.

Cada Recipe y FeatureRecipe que asocia el Manifest es una fila, sea cual sea el nivel que la asocia. Una realización que el nivel name del Manifest elige para una sola instancia o una sola vinculación se adquiere y se registra exactamente igual que una que su nivel type elige para cada instancia de un tipo, y el campo referenced_from de su fila nombra la entrada que la asocia — manifest.spec.mappings.components.name.<instance> o manifest.spec.mappings.features.name.<attachment>. Un build la contrasta con esa fila, de modo que un lockfile que no la registra detiene el build, nombrando la realización y esa entrada. Consulta Mapeo plano de URI para los dos niveles.

Las vinculaciones de una conexión son dependencias exactamente igual que las de un componente. La Feature que nombra una vinculación en una conexión — escrita en una entrada uses: de un componente en el Aggregate, o en una entrada de conexión en la Release — se adquiere y se registra como la Feature de una vinculación escrita en el propio componente, y el campo referenced_from de su fila nombra la entrada de conexión que escribió el autor, terminada en .uses.<socket>.<alias>.features.<slot>.type. La realización que el Manifest le asocia también es una fila, tanto si la asocia features.type como features.name indexado por el nombre de la vinculación, <alias>.<slot>. Un build contrasta ambas con sus filas: un lockfile sin una de ellas detiene el build nombrando la referencia y la entrada que la solicita, y una Feature cuyo contenido cambió desde el pull lo detiene nombrando ambos digests. Consulta la entrada de conexión del Aggregate para la vinculación en sí.

Una base que un Component o una Feature extiende es una fila, tanto si otra cosa la nombra como si no. El pull sigue cada extends: hasta el final de su cadena y registra cada base bajo su propio tipo de entidad, y el referenced_from de su fila nombra el spec.extends de la entidad que la extiende — component(<name>:<version>).spec.extends. Un build lee la base de esa fila, así que un Manifest mapea el tipo propio de un envoltorio y no necesita ninguna línea para su base. Una base que ningún directorio de catálogo, caché ni registry contiene se informa donde se fusiona la cadena — consulta An extends: chain cannot be assembled (No se puede ensamblar una cadena).

La Release se registra por su contenido, no solo por su nombre. Todo lo que pide la Release — a qué versión de chart se resuelve una fuente, qué componentes acaban en qué frontera — se resuelve a partir de lo que contiene el archivo, por lo que release_documents registra el digest de la Release y de cada Release que extiende, junto a release, que la nombra. Edita la Release después del pull y el siguiente build se detiene antes de renderizar nada, nombrando el archivo que editaste e indicándote que vuelvas a hacer pull; un simple aggrega pull --release <release> registra la edición respetando todos los demás pins. El digest abarca los bytes del archivo tal como son, así que un cambio en un comentario o en los espacios también cuenta, exactamente igual que para el Aggregate y el Manifest. Un archivo que la Release importa mediante parameters no se registra así.

Un pull busca un marcador de obsolescencia en cada artefacto cuya firma comprueba, e indica lo que encontró. Un marcador cuya propia firma se verifica frente a un firmante que el pull acepta — el propio firmante del artefacto, o una identidad de trusted_deprecation_identities del registro — se registra y se anuncia con su gravedad y el firmante del marcador. Un marcador que el pull encontró y no pudo aceptar — ilegible, sin firmar, firmado por alguien en quien la política no confía, o con una firma que no se pudo comprobar — se informa como marker present but not honored, con el motivo, y no se registra. Una consulta que no pudo terminar — el pull no pudo abrir el registro del artefacto, o el listado de lo que tiene adjunto no respondió — se informa como marker lookup did not complete, con el motivo, y no registra nada, porque el pull no averiguó nada sobre si existe un marcador. Con un registro cuya propia política de confianza exige una firma para el tipo del artefacto y no es advisory, cualquiera de esos dos casos detiene el pull en lugar de informarse. Un artefacto sin marcador no produce ninguna línea, y donde la verificación de firmas está desactivada, para el espacio de trabajo o para el registro del artefacto, no se busca ningún marcador.

Confirma <release-stem>.lock junto con la Release, como confirmas cualquier manifiesto de dependencias fijadas. Un diff del lockfile muestra a los revisores exactamente qué versiones y digests de dependencias cambiaron; un cambio en el digest de una biblioteca nombra a los consumidores a los que afecta.

Lo que hizo un pull concreto — si cada entidad se obtuvo de nuevo de un registry (fetched-fresh), reutilizó una ranura de la caché (cache-reuse), se encontró en un catálogo local (local), se sirvió desde la copia incluida en el binario del compilador (in-binary) o era externa (external: el Aggregate o el Manifest propios de la Release, leídos del archivo o la entrada que nombra la Release en lugar de resolverse como una de sus dependencias; un Aggregate que el pull obtuvo de un registry es fetched-fresh en su lugar) — es un diagnóstico transitorio del evento de pull que --detail imprime en stdout, y nunca se escribe en el lockfile. Qué fuente sirvió una entidad depende del estado local de la máquina que hace el pull, por lo que persistirlo rompería la identidad byte a byte del lockfile entre máquinas. Informa de lo que hizo este pull, algo irrecuperable después (una entidad recién obtenida queda en caché en la siguiente ejecución); para el estado de resolución posterior al pull de las dependencias de una Release, usa aggrega inspect.

El lock de la entidad

Una Recipe o FeatureRecipe puede depender de bytes ajenos a su propio documento: un chart o fragmento obtenido de una source: remota, un archivo que una entrada artifacts — o una entrada del boundary.artifacts de una Recipe — incorpora con $import, o los archivos de una source: que nombra un directorio o un archivo junto a ella. El digest de cada uno de ellos se registra en un archivo llamado entity.lock, en el mismo directorio que el archivo de la entidad. Nunca se escribe en el archivo de entidad que escribiste; lo derivado vive a su lado. El esquema del lock de la entidad describe el archivo campo por campo.

Quién lo escribe. Lo escribe un único paso: aggrega pin, que ejecuta el autor de la entidad, no necesita ninguna Release y registra todas las clases de pin que contiene el lock. aggrega pull --pin-sources y aggrega push --pin-sources ejecutan ese mismo paso en nombre del autor y escriben los mismos bytes. Un pull al que no se le pidió fijar no escribe ningún lock: para cada Recipe y FeatureRecipe que la Release construye a partir de tus directorios de catálogo, compara lo que el paso registraría con lo que contiene el lock, y se detiene donde falta un pin o ya no coincide con su entrada, nombrando la entidad, cada entrada y su clase, y aggrega pin. Los archivos de una fuente local se contrastan con sus pins como un único conjunto: un lock que no registra ninguno detiene el pull, y también lo hace un archivo añadido, modificado o eliminado desde el pin. La clave del espacio de trabajo pin_sources_at_pull hace que fijar sea el comportamiento predeterminado de cada pull, y --pin-sources=false restablece la detención para una ejecución. Fijar es un deber de autoría, así que una detención en el primer pull de un consumidor significa que quien publicó la entidad nunca la fijó; el remedio del consumidor es esa clave y no una edición manual del directorio de otra persona. aggrega pin lo expone por completo.

Qué contiene. Tres listas, en las que cada fila nombra una entrada:

  • sourceDigests — una fila por cada source: remota cuyas coordenadas escribiste por completo, sin plantilla en kind, url, chart, module_subdir, version ni ref. La fila incluye el kind y la url de la fuente, su chart o module_subdir cuando lo tiene, la versión a la que se resolvió — para una fuente git, el commit que nombraba su ref — y el digest de contenido del archivo comprimido obtenido, además del digest del manifiesto para un chart obtenido mediante OCI.
  • artifactDigests — una fila por cada entrada artifacts o boundary.artifacts proporcionada por un archivo importado con $import, que nombra la entrada y el digest de los bytes del archivo. Una entrada artifacts se nombra por su clave, y una entrada boundary.artifacts como boundary/<key>, de modo que una entrada de cada bloque escrita bajo la misma clave se fija por separado.
  • localSourceDigests — una fila por cada archivo que una source: que nombra un directorio o un archivo junto a la entidad aporta a lo que contiene una publicación de la entidad, que nombra la ruta del archivo junto a la entidad y el digest de sus bytes. Para una fuente así no se obtiene nada; el digest de sus archivos se calcula tal como están. Una fuente escrita como plantilla aporta todos los archivos del directorio de la entidad, así que cada uno de ellos tiene una fila.

Qué no contiene:

  • Una fuente remota cuyas coordenadas se rellenan a partir de una plantilla — una version leída de .infra, por ejemplo. Qué artefacto nombra lo decide cada Release que usa la entidad, así que cada versión a la que se resuelve se fija en el lockfile de esa Release, y nada sobre ella se escribe junto a la entidad.
  • Una entrada artifacts o boundary.artifacts en línea, que forma parte del archivo de la entidad, y una entrada tomada de una ArtifactLibrary, cuyo contenido queda fijado por la versión de la biblioteca que registra el lockfile.

Una entidad sin nada que fijar no recibe ningún entity.lock, y el paso, ejecutado sobre una entidad que ya no lo necesita, lo elimina.

Confírmalo junto a la entidad. Cada Recipe y FeatureRecipe usa el mismo nombre de archivo, y el directorio en el que se encuentra indica a qué entidad pertenece, así que el lock viaja con ese directorio. No lleva marca de tiempo y sus filas se mantienen en un orden fijo, así que el paso sobre entradas sin cambios lo deja idéntico byte a byte, y un diff sobre él nombra la fuente, el archivo importado o el archivo de la fuente local que cambió. Un directorio contiene un solo lock, por lo que el paso rechaza una Recipe o FeatureRecipe que tenga cualquier otra entidad al lado — cada tipo tiene su propio directorio excepto Aggregate, Release y Manifest — y un pull al que se le pide fijar rechaza una entidad así antes de resolver nada; Una entidad por directorio expone la regla. Un pull que no fija no escribe nada junto a una entidad ni juzga su directorio.

aggrega build contrasta tus archivos con él. Un build lee el lock y realiza tres comparaciones:

  • Se vuelve a calcular el digest de cada archivo importado y se compara con su fila, un archivo boundary.artifacts exactamente igual que un archivo artifacts. Un archivo editado después de fijarse detiene el build con [CATALOG_ERROR E0026], nombrando el artefacto tal como lo nombra su fila, el archivo importado y ambos digests.
  • Se vuelve a calcular el digest de los archivos de una fuente local y se compara con sus filas, como un único conjunto, antes de que el provider lea la fuente. Un archivo editado, añadido o eliminado desde el pin detiene el build con E0305 bajo la instancia de componente cuya fuente es, nombrando cada uno de esos archivos y ambos digests; un archivo junto a la entidad que la fuente no aporta no se compara. Un lock que no registra ninguna fila para una fuente local no deja nada que comparar, como describe A local source no longer matches the pins recorded beside its Recipe (Una fuente local ya no coincide con los pins registrados junto a su Recipe).
  • Cada fila de fuente se compara con el digest que el lockfile de la Release registra para la misma fuente. Un desacuerdo detiene el build con [FETCH_ERROR E0135], nombrando el lock y ambos digests. Los dos archivos los escriben dos resoluciones de la misma fuente — la del paso de pin y la del pull — así que discrepan cuando esas resoluciones obtuvieron bytes distintos, o cuando se editó uno de los dos archivos. Bytes distintos bajo una misma versión es el aspecto que tiene un upstream que volvió a publicar una versión.

Un lockfile escrito antes del cambio provoca la detención primero, y un pull nombra el archivo. El lockfile registra la entidad por lo que contiene, y el lock y cada archivo que leen estas comparaciones forman parte de ello, así que un build — o aggrega pull --verify — que usa un lockfile escrito antes de que cambiaran un archivo importado, un archivo de una fuente local o el propio lock se detiene antes de que se ejecute ninguna de las tres comparaciones: The lockfile no longer matches what the release resolves to (El lockfile ya no coincide con aquello a lo que se resuelve la release), nombrando la entidad y ambos digests. Un simple aggrega pull nombra entonces el archivo, porque contrasta el lock con lo que registraría el paso de pin y rechaza la entrada cuyo pin ya no coincide: An entity reads an input the lock beside it records no pin for (Una entidad lee una entrada para la que el lock que tiene al lado no registra ningún pin).

Donde el lockfile no tiene ningún registro del contenido propio de la entidad, son las tres comparaciones lo que encuentra un build. Una Recipe o FeatureRecipe que el Manifest nombra mediante una referencia que es también el nombre de un Component o una Feature que alcanza la Release no tiene entrada propia: la entrada del lockfile para esa referencia registra el Component o la Feature, así que nada cambia en el lockfile cuando cambian los archivos de la Recipe, y un build y un pull de verificación informan del archivo cambiado con el código anterior. La comparación de filas de fuente es también lo que encuentra un build cuando la entrada source_artifacts del lockfile es el registro que cambió mientras que el lock junto a la entidad no.

Responder a la detención. Si cambiaste el archivo importado a propósito, ejecuta aggrega pin sobre la entidad: el paso registra el nuevo digest del archivo y el siguiente build lo acepta. Si no, restaura el archivo. Una fuente local que cambió admite las mismas dos respuestas: vuelve a fijar la entidad o restaura los archivos que nombra la detención. Para una fila de fuente que discrepa del lockfile, restaura entity.lock desde el control de versiones, o ejecuta aggrega pin sobre la entidad para reescribirlo.

aggrega pull --verify también lo comprueba. Un pull de verificación realiza las mismas tres comparaciones sobre los locks junto a las Recipes y FeatureRecipes que la Release alcanza en tus directorios de catálogo, informa de cada pin que un build rechazaría con el mismo código y con las mismas palabras, termina con un código distinto de cero si hay alguno, y no escribe ningún lock.

Donde no se compara ningún lock. Una Recipe o FeatureRecipe resuelta desde un registry en lugar de desde uno de tus directorios de catálogo no tiene ningún lock que lea un build; sus fuentes se contrastan solo con el lockfile de la Release. Y una fuente escrita en un ref: de git se registra en el lock en el commit al que se resolvió ese ref, mientras que un build busca el pin de la fuente en la versión que nombra la entidad, así que esa fila nunca se compara — ni en un build ni en un pull de verificación. El lockfile sigue fijando el commit, y cada build verifica el archivo comprimido en caché contra él.

El registro de confianza de plugins

Algunos plugins que vincula el espacio de trabajo nunca dan forma a la salida renderizada. Una vinculación plugins.governance en un rol ir-verdict o render-verdict, y toda vinculación plugins.linter, devuelven un veredicto de aceptación o rechazo y nada más — ninguno de sus bytes llega a un artefacto. Por eso no forman parte de lo que un build reproduce byte a byte, y el lockfile, que fija exactamente eso, no es el lugar adecuado para ellos.

Sus identidades van en cambio en un segundo archivo confirmado: plugins-trust.yaml, junto al lockfile. Contiene una entrada por cada plugin de ese tipo, que registra la coordenada de identidad del plugin, la versión seleccionada para él y el digest de contenido del artefacto resuelto — además de la firma que el pull verificó para ese artefacto, cuando verificó una, y, cuando quien lo publica ha marcado ese artefacto como obsoleto desde su publicación, el marcador que el pull encontró y verificó. El esquema del registro de confianza de plugins describe el archivo campo por campo.

Confirma plugins-trust.yaml junto con el lockfile, por la misma razón por la que confirmas el lockfile: un registro guardado fuera del control de versiones es uno que nadie puede revisar y con el que nada se puede comparar. Confirmado, es una única declaración compartida de a qué plugin se resolvió cada una de esas vinculaciones, y un diff sobre él nombra la identidad que cambió.

El archivo aparece solo cuando hay algo que registrar. Un espacio de trabajo que no vincula ningún plugin que devuelva veredictos no resuelve ninguna identidad de ese tipo, así que el pull no escribe ningún archivo y no dice nada al respecto — una ausencia, no un archivo que falta. Cuando el pull lo crea, nombra el archivo que creó y te indica que lo confirmes. Un pull posterior añade una identidad que el registro aún no contiene y deja cada identidad ya registrada exactamente como está.

Cada cambio en este archivo se anuncia, y nada más se anuncia. Un pull que modifica el registro imprime una línea por cada entrada modificada, nombrando el plugin y qué cambio fue: una identidad registrada por primera vez, una identidad adoptada en lugar de la existente (nombrando ambas, para que veas qué se sustituyó), una obsolescencia registrada sobre el artefacto que ya nombra una entrada, una obsolescencia retirada de una entrada, una firma registrada en una entrada o retirada de ella, o la entrada eliminada. La línea de creación anterior es independiente y trata del archivo y no de una entrada, así que una primera resolución dice ambas cosas: este archivo es nuevo y debe confirmarse, y estas son las identidades que contiene ahora.

Un pull que deja el registro exactamente como estaba no dice nada al respecto. Así que una línea sobre este archivo significa que el archivo confirmado ha cambiado y que vale la pena leer su diff — lo que aquí importa más que en el lockfile. Todo lo que fija el lockfile forma parte también de lo que un build reproduce byte a byte, así que un cambio ahí tiene un segundo lugar donde aparecer; la identidad de un plugin de veredicto no tiene ninguno. Este archivo es el único lugar donde queda constancia de una compuerta sustituida.

aggrega pull --dry-run no anuncia nada de esto, porque no cambia nada. En su lugar, incluye el registro entre los archivos que escribiría, como describe Vista previa de lo que escribiría un pull.

Una obsolescencia se añade a una entrada que el registro ya contiene, y eso no es lo mismo que reescribirla. Si quien publica marca como obsoleto un plugin en el que ya confías, el siguiente aggrega pull registra el marcador en la entrada existente de ese plugin — la coordenada, la versión y el digest no se tocan, porque el artefacto no ha cambiado y no se adopta nada nuevo. Así que un simple pull puede añadir un bloque deprecation, y solo una actualización explícita cambia una identidad. Un marcador se registra solo sobre el artefacto que la entrada ya nombra, y ningún pull persigue uno que haya dejado de publicarse: un marcador registrado solo desaparece con la entrada que lo contenía, es decir, cuando esa entrada se elimina o cuando una actualización explícita vuelve a resolver el plugin y no encuentra ningún marcador en los bytes que la entrada ya registra.

La firma verificada se registra en una entrada de la misma manera, y cada pull vuelve a responderla. El pull verifica en cada ejecución la firma de cada uno de estos plugins según la política de confianza de su registry — un plugin que sirve un registry se obtiene cada vez por su versión, ya que nada lo fija — y registra lo que verificó en la entrada del plugin, de nuevo sin tocar la identidad: el modo, el firmante que coincidió y el digest del bundle de firma que almacenó en caché, la misma signature que contiene una entrada del lockfile. A diferencia de un marcador, la respuesta sustituye lo que contenía la entrada, y donde el pull no verificó ninguna firma — el plugin no lleva ninguna y no se exige ninguna, o skip_signature_verification o un registry advisory lo admitió — la entrada no registra ninguna. El bundle de firma verificado también se vuelve a almacenar en caché, y una copia en caché que ya no coincide con su digest se reescribe. Así, una entrada que perdió su firma, una entrada que lleva una firma copiada de la de otro plugin, una entrada cuyo bundle de firma en caché se eliminó o alteró, o un registro eliminado o escrito antes de que se registrara una firma, se repara con el siguiente aggrega pull simple. Un build contrasta cada uno de estos plugins con ese hecho: consulta El registro de confianza de plugins en la página del build.

Una identidad resuelta que discrepa de la registrada detiene el pull. Una entrada registrada nombra tanto una versión como un digest, así que el cambio de cualquiera de los dos es el mismo evento: el plugin que se ejecutaría no es el plugin para el que se revisó el registro. El diagnóstico nombra el plugin, lo que contiene el registro y lo que informó esta resolución, en ambos ejes a la vez — y el pull se detiene sin tocar el registro, de modo que la identidad revisada sigue ahí para compararla. Se detiene solo por la versión (una nueva publicación cuyos bytes no cambiaron) exactamente igual que se detiene solo por el digest (un nuevo push en la misma versión).

aggrega pull --verify realiza la misma comparación. No escribe ninguno de los archivos que confirma un pull, así que no adopta nada; informa de si esos archivos siguen describiendo lo que un pull resolvería hoy, y el registro es uno de ellos. También contrasta la firma de cada entrada con la que da la propia verificación del plugin por parte del pull, e informa de una entrada cuya firma un pull registraría, sustituiría o retiraría — y de un plugin para el que el registro no contiene ninguna entrada cuando un build lo rechaza por no registrar ninguna firma — como describe Compara las firmas registradas, en ambos archivos.

Para adoptar una nueva identidad, pídela por su nombre: aggrega pull --upgrade --release <release> <plugin>, nombrando el plugin como lo nombra la vinculación de tu .aggrega-config.yaml, sin ningún sufijo de versión. Eso vuelve a resolver solo ese plugin y reescribe su entrada, sin tocar ninguna otra dependencia fijada ni ninguna otra identidad registrada — y funciona aunque el plugin no tenga pin en el lockfile, porque un destino nombrado también puede nombrar una de esas vinculaciones. Un aggrega pull --upgrade sin destinos, que vuelve a resolver todas las dependencias, también vuelve a resolver y reescribe todas las identidades registradas. Lo mismo hace aggrega build --upgrade, que ejecuta un pull de actualización completa sin destinos y no tiene forma de nombrar un único destino.

Para retirar una identidad, pídelo también por su nombre. Desvincular un plugin de .aggrega-config.yaml no borra su entrada, y es deliberado: un simple aggrega pull nunca retira ninguna. Ejecuta aggrega pull --upgrade --release <release> <plugin>, nombrando el plugin como lo nombra el registro — su coordenada de identidad, que es la cadena que imprime la detención descrita más abajo — y la entrada se elimina, sin tocar ninguna otra dependencia fijada ni ninguna otra identidad registrada. Un aggrega pull --upgrade sin destinos elimina cada entrada que ya no nombra ninguna vinculación de veredicto, en la misma pasada que vuelve a resolver todo lo demás.

Eliminar la última entrada deja el archivo en su sitio y vacío en lugar de borrarlo. Un registro vacío no contiene nada, así que no fija nada ni detiene nada — igual que no tener registro — y conservar el archivo hace que la eliminación aparezca en su diff como una eliminación.

Un registro que no cumple su esquema detiene todo comando que lo lea — un build, un lint de ámbito de release y un pull, incluido un pull que no tiene nada propio que registrar. Un registro vaciado y uno dañado son deliberadamente distintos: vaciarlo es la forma de eliminar la última entrada, y un registro vaciado permanece en silencio, mientras que un archivo cuyo contenido ya no se puede analizar es un fallo y no un registro vacío — leerlo como vacío haría que truncar el archivo fuera una forma de desactivar la comparación. Restáuralo desde el control de versiones para recuperar las identidades revisadas.

Un plugin servido desde la copia incluida en el binario del compilador no se registra. El pull registra lo que adquirió — obtenido de un registry o leído de la caché — y del binario no se adquiere nada: esos bytes se identifican por la versión del compilador que los incluye, así que no hay una resolución propia que registrar. Por tanto, vincular un plugin que el binario ya incluye no produce ninguna entrada para él. Eso es el registro ciñéndose a los artefactos adquiridos, no una resolución que falló.

Un build, un lint de ámbito de release y una validación de ámbito de release contrastan la configuración del espacio de trabajo con el registro. Antes de que se ejecute cualquiera de esas vinculaciones, aggrega build, aggrega lint --release y aggrega validate --release — y las mismas operaciones alcanzadas mediante aggrega serve y aggrega mcp — comparan las vinculaciones de veredicto que nombra la configuración con las entradas que contiene el registro. Un plugin cuyo digest de artefacto resuelto no es el registrado se rechaza en lugar de ejecutarse. Una entrada del registro de la que no da cuenta ninguna vinculación de veredicto configurada detiene la ejecución: una compuerta que se revisó y que ahora falta deja una salida indistinguible de una salida que esa compuerta aprobó, que es exactamente lo que no puede ver quien lee la salida. La detención nombra el plugin y ofrece los dos remedios que difieren según lo que pretendías — vuelve a vincular el plugin si la eliminación fue un error, o ejecuta la actualización explícita anterior si fue intencionada — e imprime esa actualización lista para ejecutarse. La dirección inversa — una vinculación que el registro aún no contiene — es la primera detección descrita antes, y ninguna de las dos comparaciones se detiene por ella; el requisito de firma es la única exigencia de la que no escapa una vinculación sin entrada. Las mismas tres superficies contrastan cada plugin que leen de la caché con la firma que registra su entrada, cuando lo cargan, como describe la página del build para un build. Los ámbitos de lint de todo el catálogo y de una sola entidad no consultan ningún registro.

Una validación se contrasta con el registro porque ejecuta las mismas comprobaciones que un build. aggrega validate --release alcanza todas las comprobaciones que alcanza aggrega build salvo la escritura de los artefactos, plugins de compuerta incluidos — eso es lo que hace que «esto valida» signifique lo mismo que «esto compila» — así que la identidad del plugin que ejecuta se compara con el registro exactamente igual que la de un build. Los demás ámbitos de aggrega validate no se contrastan con él: validar todo el catálogo, una sola entidad o un binario de plugin no lee en absoluto las vinculaciones de plugins del espacio de trabajo, así que en ellos no se ejecuta ningún plugin de veredicto y no hay nada que un registro pueda sujetar.

Contrastar una configuración con el registro establece presencia e identidad, y nada más allá. Establece que cada compuerta que nombra el registro sigue vinculada, y que cada una se ejecuta desde el artefacto registrado para ella. No establece que una compuerta que se ejecutó haya devuelto realmente un veredicto, y hay un caso de esto que no se detecta en ninguna parte: una vinculación cuya function nombra una exportación que el plugin sí declara, que no es la exportación de veredicto que lee su socket, y cuya salida no lleva ningún campo de nivel superior fuera de la forma que espera ese socket — el objeto vacío es el caso más sencillo — se ejecuta, no devuelve nada por lo que rechazar y deja pasar el build. Su salida es indistinguible de la de una compuerta que aprueba, y ninguna comparación con el registro puede notarlo, porque nada del registro es incorrecto: el plugin que se ejecutó es exactamente el registrado, y simplemente no ejecutó nada. Dos casos vecinos sí se detienen, así que el límite no es más amplio de lo que parece — una function que nombra una exportación que el plugin no declara se rechaza al cargar el plugin, y una salida que lleva un campo de nivel superior que la forma del socket no declara se rechaza en lugar de leerse como una lista de veredictos que resulta estar vacía. Así que una identidad registrada no basta por sí sola para que una compuerta haya juzgado algo.

El digest registrado rige los plugins que el espacio de trabajo resuelve desde la caché que llena aggrega pull, y nada de lo que resuelve de otra forma. Esa es la resolución que sigue normalmente una vinculación de veredicto — nada la fija en el lockfile, así que sus bytes vienen de la caché, y es en esa lectura donde el digest resuelto se compara con el registrado. Un plugin de veredicto que el espacio de trabajo resuelve de otra forma nunca llega a esa lectura, y lo rige lo que rija la forma en que se resolvió y no el registro: los bytes servidos desde la copia incluida en el binario del compilador se identifican por la versión del compilador que los incluye, un .wasm situado junto a su entidad del catálogo es un archivo de tu propio directorio de catálogo, una ruta explícita del sistema de archivos es la ruta que nombraste, y un plugin que lleva un pin en el lockfile lo rige ese pin. La otra mitad de contrastar una configuración con el registro no está acotada así: cada entrada que contiene el registro debe seguir justificada por una vinculación configurada, se resuelva como se resuelva ese plugin. Así que el registro establece que las compuertas que nombra siguen vinculadas, sea lo que sea lo que las sirva, y establece la identidad de artefacto de las que se sirven desde la caché.

Respetar o actualizar

De forma predeterminada, aggrega pull respeta un lockfile existente: una dependencia ya fijada se resuelve exactamente en su versión fijada (verificada con su digest fijado), solo se resuelven y añaden las referencias que aún no están fijadas, y se eliminan los pines de las referencias que la Release ya no alcanza. Así, un nuevo pull de una Release sin cambios no hace nada: reproduce el mismo lockfile byte a byte (incluido generated_at). Añadir una nueva dependencia, o hacer pull después de que una edición manual eliminara un pin, resuelve solo esa carencia y deja intactos todos los demás pines.

Una dependencia que un nuevo pull lee de la caché se registra exactamente como la registró el pull que la descargó. Su fila conserva la versión, el digest del contenido y el manifest_digest —este último tomado del manifest almacenado junto al contenido en la caché—, junto con la signature y la deprecation que ese pull verificó en el registry. Nada de eso se vuelve a consultar mientras un build aceptaría la fila, y --detail informa de esa dependencia como cache-reuse, de modo que un nuevo pull cuyas dependencias están todas en caché, sobre un lockfile que registra todas las firmas que exige la configuración de confianza y solo firmas que un build acepta, escribe el mismo lockfile tanto si se puede llegar al registry como si no.

Un nuevo pull vuelve a consultar una firma exactamente donde un build rechazaría la fila, y hay dos filas de ese tipo.

  • Una firma exigida que el lockfile no registra. Cuando la configuración de confianza exige una firma para una dependencia que sirve la caché y la fila del lockfile no registra ninguna —la fila se editó, el lockfile se escribió desde cero sobre una caché que llenó un pull anterior, o el requisito se añadió después del pull que escribió la fila—, el nuevo pull pide su firma al registry de esa dependencia, mediante el digest del manifest almacenado junto a ella en la caché, exactamente como hace con una dependencia que descarga, y registra la firma verificada en la fila. Esa fila es la que un build rechaza (No verified signature is recorded for an artifact that requires one (No hay ninguna firma verificada registrada para un artefacto que la requiere)), así que volver a hacer pull es lo que elimina ese rechazo. Un registry que no adjunta ninguna firma, o una firma que la configuración de confianza no acepta, detiene el nuevo pull igual que detiene un pull que descargó la dependencia. Los ajustes que permiten a un pull admitir una dependencia sin firma dejan esa fila como está y no preguntan nada sobre ella: skip_signature_verification en el nivel superior, el mismo interruptor en la entrada propia del registry salvo para un tipo que la política de firma de todo el workspace exige, y un registry marcado como advisory.
  • Una firma registrada que un build no acepta. Cuando la fila registra una firma cuyo paquete de firma en caché se eliminó o alteró después del pull que lo almacenó en caché —o una signature copiada de otra fila, cuyo paquete está intacto pero se creó para otro artefacto—, un build rechaza la fila diga lo que diga el requisito de firma (A cached signature bundle does not match the digest recorded for it (Un paquete de firma en caché no coincide con el digest registrado para él), A recorded signature was made for a different artifact (Una firma registrada se creó para un artefacto diferente)). Por eso el nuevo pull vuelve a preguntar al registry de esa dependencia por su firma, diga lo que diga el requisito, mediante la misma verificación que recibe una dependencia que descarga: lo que esa verificación confirma sustituye la firma de la fila, y el paquete que nombra se vuelve a almacenar en caché, reescribiendo una copia en caché que ya no coincide con su digest, de modo que la fila y la caché contienen lo que dejó el pull que descargó la dependencia. Una firma que la configuración de confianza no acepta detiene el nuevo pull igual que detiene un pull que descargó la dependencia, y lo mismo hace un registry que no adjunta ninguna donde se exige una firma. Cuando la verificación no registra ninguna —skip_signature_verification donde se aplica, que no pregunta nada, un registry que no adjunta ninguna firma donde no se exige ninguna, o un registry advisory donde no se verifica nada—, la firma de la fila se borra, algo que un build admite con los mismos ajustes.

Una fila cuya firma registrada acepta un build no se vuelve a consultar, ni tampoco una fila que no registra ninguna y para la que nada exige una firma.

Una dependencia nombrada sin registry, en un workspace que ya no nombra ningún default_registry, no se puede consultar. Su fila quedó vinculada a un registry por el pull que registró su firma, y sin uno predeterminado no hay ningún registry al que preguntar. Cuando esa fila registra una firma que un build no acepta, el nuevo pull se detiene con el propio rechazo del build, indicando que no hay ningún registry configurado para volver a consultar la fila, y deja el lockfile como estaba. Configurar como default_registry el registry del que procede la dependencia y volver a hacer pull lo repara.

Lo que rige ese respeto es lo que sirve un registry o la caché. Una entidad que proporciona un directorio de catálogo local se resuelve desde ese directorio, en la versión que declara su archivo, y la entrada que el lockfile registra para ella no se consulta por el camino. El lockfile registra igualmente esa entidad, así que la verás allí, pero editar esa entrada a mano no mantiene la entidad en la versión que escribiste, y la siguiente reconciliación reescribe la entrada para que coincida con el archivo. Para cambiar qué versión de una entidad proporcionada localmente resuelve una Release, edita el archivo del catálogo en lugar del lockfile.

Un pin nombra bytes, no un lugar, así que una entrada de la caché que ya no contiene su pin se descarta en lugar de considerarse fiable. Una entidad editada en su sitio —un nuevo cuerpo bajo la misma version— deja en la caché de contenido el cuerpo anterior bajo ese nombre y esa versión. Un directorio de catálogo se lee primero, así que una entidad que alguno de ellos aún proporciona se fija desde su archivo y la entrada obsoleta nunca se lee. El renderizado que ejecuta el pull para descubrir las entradas externas de la Release lee cada pin como lo hace un build, desde el directorio de catálogo que contiene los bytes fijados, e informa de la entrada descartada con el aviso que imprime aggrega build. Cuando ningún directorio de catálogo proporciona la entidad y se puede llegar a un registry, el pull vuelve a descargar la versión fijada, reescribe la entrada y lo indica en la salida de error estándar, nombrando la entrada y ambos digests:

reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)

Los bytes descargados se contrastan con el pin como cualquier descarga bajo un pin, así que un registry que sirve otros bytes bajo esa versión detiene el pull, como se describe más abajo. Cuando ninguna fuente contiene los bytes fijados —ningún directorio de catálogo proporciona la entidad, la entrada de la caché contiene otros bytes, y ningún registry sirve la versión fijada o la ejecución no llega a ninguno—, el pull y aggrega pull --verify se detienen con E0135 —o E0133 cuando el manifest de la entrada de la caché no es el que fija el lockfile—, nombrando cada fuente que leyeron y lo que contenía; cuando la ejecución no llegó a ningún registry, la detención también nombra el paso que vuelve a descargar la versión fijada.

Para actualizar las versiones fijadas, ejecuta aggrega pull --upgrade --release <release>: descarta los pines existentes y vuelve a resolver todas las dependencias a las últimas versiones que cumplen las restricciones. Actualizar es el acto explícito; el comportamiento predeterminado nunca hace flotar una dependencia fijada. Esto refleja la convención de npm ci / cargo / go build (el predeterminado materializa el lock; actualizar es opcional), y es lo que hace seguro el pull automático de aggrega build: el build resuelve exactamente lo que fija el lockfile, sin mover nunca una versión en silencio.

Esa forma sin objetivos descarta todos los pines registrados, así que pide confirmación antes de hacer nada. Respóndela de antemano con --yes para el uso no interactivo; si la entrada estándar no es un terminal y no hay --yes, se niega en lugar de esperar una respuesta que nadie puede dar. Nombrar objetivos (aggrega pull --upgrade --release <release> <uri>) conserva todos los pines que no nombró, así que esa forma no pregunta nada. aggrega build --upgrade ejecuta la forma sin objetivos y está sujeto a las mismas condiciones.

Si los bytes de una versión fijada en el registry ya no coinciden con el digest que registró el lockfile (una violación de la inmutabilidad aguas arriba), pull se detiene con un error de integridad en lugar de adoptar en silencio los bytes modificados: ejecuta --upgrade para volver a fijar deliberadamente.

Comprobar un lockfile sin escribirlo

aggrega pull --verify --release <release> responde a una pregunta: ¿ejecutar aggrega pull ahora cambiaría el lockfile, o el registro de confianza de plugins que está a su lado? Realiza la resolución que realizaría un pull, compara con ella el lockfile y el registro, y se detiene antes de que se escriba nada de lo que un pull confirma: el lockfile, el registro de confianza de plugins y cada entity.lock quedan como están. Termina con un código distinto de cero si falta el lockfile y ante cualquier diferencia, nombrando cada una. Los marcadores de obsolescencia no se comparan, como se describe más abajo. Se rechaza junto con --upgrade, con --dry-run y con --pin-sources, sea cual sea el valor que se dé a esa opción: una verificación ni registra un pin que falta en un entity.lock ni se detiene por él, así que la opción no cambiaría nada.

Respeta los pines registrados exactamente como lo hace un pull. Una dependencia que el lockfile fija se resuelve en su versión fijada y se comprueba con su digest fijado, y una entidad que proporciona un directorio de catálogo local se resuelve desde ese directorio, como describe Respetar o actualizar. Así:

  • Una referencia cuyo registry ha publicado una versión más reciente desde el pull no es una deriva. Un pull mantendría su pin, así que el lockfile sigue siendo el que escribiría un pull; aggrega pull --upgrade es la forma de adoptar la versión más reciente.
  • Un registry que ahora sirve bytes distintos bajo una versión fijada detiene la verificación con el error de integridad que detiene un pull, en lugar de informar del cambio como una deriva.
  • Se informa de cada una de estas: una fila del lockfile editada a mano, una Release editada y una entidad editada en un directorio de catálogo local, porque cada una es una diferencia entre el lockfile y lo que un pull resuelve ahora.

Lee y llena la caché como lo hace un pull. Una entrada que la caché contiene bajo su pin —una entidad de catálogo o el .wasm de un plugin— se lee de allí sin preguntar a ningún registry, que es lo que permite ejecutar una verificación en modo sin conexión sobre un workspace que llenó un pull conectado. Una entrada que la caché no contiene se descarga, como la descarga un pull, y una que ya no coincide con su pin se trata exactamente como la trata un pull. Así, una verificación puede añadir contenido a la caché, y nunca mueve un pin.

Compara las firmas registradas, en ambos archivos

La firma que un pull verificó para un artefacto forma parte de lo que escribe: la signature de una entrada del lockfile, y la de una entrada de plugins-trust.yaml para un plugin vinculado a un rol de veredicto. Una vez que los pines coinciden, una verificación contrasta cada firma registrada con la que un pull registraría ahora, e informa de cada una que un pull registraría donde no hay ninguna registrada, sustituiría o borraría, bajo A recorded signature is not the one a pull would record (Una firma registrada no es la que registraría un pull). Cada una de esas entradas, en cualquiera de los dos archivos, se nombra en la misma ejecución.

Qué entradas del lockfile consulta es decisión del propio pull. Un nuevo pull pregunta a un registry por la firma de una entrada exactamente donde describe Respetar o actualizar, y una verificación sigue esa misma decisión:

  • De dos se informa sin preguntar a ningún registry, porque un pull las reescribe responda lo que responda el registry: una entrada que sirve la caché y que no registra ninguna firma donde la configuración de confianza exige una —el pull registra la firma del artefacto, o se detiene donde no se puede establecer ninguna— y una entrada cuya firma registrada se creó para otro artefacto, que el pull sustituye por la del propio artefacto.
  • Sobre cualquier otra entrada que un pull volvería a consultar se pregunta, porque solo la respuesta del registry indica si el pull la cambiaría: una entrada cuyos bytes descargó esta verificación, y una entrada cuyo paquete de firma en caché se eliminó, es ilegible o se alteró. La verificación pregunta al registry, como haría el pull, e informa de la entrada donde la respuesta registra, sustituye o borra su firma. El paquete de firma que verificó se almacena en caché como lo almacena un pull, así que una entrada cuyo paquete en caché se eliminó, mientras su registry sigue sirviendo la firma registrada, supera la verificación y deja la caché reparada.

Una entrada cuya firma registrada acepta un build, y una entrada que no registra ninguna y para la que nada exige una firma, no se consultan, ni por un pull ni por una verificación.

El registro de confianza de plugins se contrasta con el mismo pull. Cada pull verifica en su registry la firma de cada plugin vinculado a un rol de veredicto, y lo mismo hace una verificación, que informa de una entrada cuya firma esa verificación registraría, sustituiría o borraría. Se informa de un plugin para el que el registro no contiene ninguna entrada donde un build lo rechaza por no registrar ninguna firma, porque un pull escribe una entrada que lleva su firma y el build rechaza el plugin hasta entonces. Cualquier otro es un primer avistamiento, del que una verificación no informa, igual que no informa de ninguna identidad que el registro aún no contiene. En modo sin conexión, una verificación no pregunta a ningún registry sobre estos plugins, y Sin conexión describe de qué informa en su lugar.

Los marcadores de obsolescencia no se comparan. Un marcador adjuntado a un artefacto después del pull es estado del registry, y cambia sin que cambie nada en el workspace; una verificación que fallara por él haría fallar una comprobación sobre archivos que no tocaste. Por la misma razón, un marcador registrado advierte a un build en lugar de detenerlo. Así, un pull puede registrar un marcador en una entrada que una verificación superó.

Vista previa de lo que escribiría un pull

aggrega pull --dry-run --release <release> resuelve las dependencias exactamente como un pull ordinario y luego, en lugar de escribir, imprime lo que habría escrito: un encabezado que nombra la ruta de cada archivo, seguido del contenido que tendría ese archivo.

aggrega pull --dry-run --release release.yaml

Nombra cada archivo, no solo el lockfile. El lockfile, el entity.lock junto a cada Recipe y FeatureRecipe cuyos pines registrados se moverían con --pin-sources, y el registro de confianza de plugins aparecen todos en el mismo informe, porque una vista previa que mostrara solo el lockfile te enseñaría que el lockfile es lo único que se mueve. Un pull que se detendría ante una entidad sin fijar también se detiene con --dry-run, por la misma razón: lo que muestra una vista previa es lo que haría el pull. Los archivos que un pull dejaría idénticos byte a byte no aparecen en absoluto: un nombre en el informe significa que ese archivo está a punto de cambiar. La última línea los cuenta, y un workspace que un pull no cambiaría informa de un recuento de cero.

Nada se mueve en el disco. No se escribe ni se crea ningún lockfile, no se escribe ni se elimina ningún lock de entidad, y no se crea ni se modifica ningún registro de confianza. Cuando una capacidad la sirve más de un plugin de provider y nada ha elegido entre ellos, la ejecución se detiene nombrando qué hay que proporcionar en lugar de ofrecerse a escribir la elección en tu configuración: una vista previa no edita un archivo de configuración de paso.

La resolución en sí se ejecuta igualmente, así que la caché se llena igualmente. Qué entradas externas consume una Release es un producto de su renderizado, y una ejecución que renunciara a resolver no tendría nada de lo que informar, así que --dry-run descarga y almacena exactamente como lo hace un pull. El contenido bajo .aggrega/cache solo se lee a través de los pines que registra un lockfile, así que llenarlo no cambia nada de lo que resuelve un build; lo que muestra un dry run es lo que escribiría un pull.

Un --upgrade sin objetivos no pregunta nada con esta opción. La confirmación existe porque una actualización completa descarta todos los pines registrados, y una vista previa no descarta ninguno, así que aggrega pull --dry-run --upgrade --release <release> es la forma que hay que usar cuando lo que quieres saber es lo que te costaría una actualización, y se ejecuta sin respuesta.

No se acepta junto con --verify, que ya no escribe ninguno de esos archivos. El par dejaría la opción sin hacer nada mientras parecería que ha hecho algo, así que se rechaza en lugar de ignorarse.

Una cosa que una vista previa con fijación no siempre puede mostrar completa, y lo dice cuando ocurre. Un pull al que se le pide fijar reescribe el entity.lock junto a cada Recipe y FeatureRecipe y luego renderiza la Release para descubrir sus entradas externas; una vista previa deja esos locks como están, así que donde un pin registrado en ellos ha quedado obsoleto —por ejemplo, editaste un archivo importado desde que se fijó—, ese renderizado se contrasta con el digest obsoleto que el lock no escrito aún registra, y se detiene. Todo lo demás del informe es exactamente lo que escribiría un pull; solo faltan los pines de entradas externas del lockfile del que se informa. La ejecución lo indica tanto en su salida como en sus diagnósticos en lugar de entregarte un lockfile que parece completo. Una primera resolución de un workspace no se ve afectada, porque aún no hay ningún digest registrado respecto al que algo pueda estar obsoleto.

La composición que describen estos pines

Un lockfile fija lo que consumirá un build de esta Release, así que la resolución traza la composición que traza ese build: resuelve los documentos, aplica las transformaciones que declaran las vinculaciones del workspace y somete el resultado a las comprobaciones que un build hace sobre un grafo terminado. De ello se derivan dos cosas, y ambas aparecen en la pasada que escribe el lockfile y no en el primer build que lo lee.

Una composición que esas comprobaciones rechazan detiene el pull. Una arista uses: cuyo destino no cumple el selector: de su socket, una Feature vinculada a un componente que su appliesTo: no admite, y cualquier otra infracción de la que informen esas comprobaciones detienen este comando, con el diagnóstico que imprime un build de los mismos documentos, y la detención nombra todos los hallazgos en una sola ejecución en lugar de solo el primero, de modo que una pasada te entrega la lista completa que corregir. Ocurre antes de la escritura, así que <release-stem>.lock y plugins-trust.yaml quedan exactamente como estaban y una Release que no se puede compilar nunca se registra como una que se resolvió correctamente. Lo que eso no cubre son las vinculaciones que devuelven un veredicto: aquí no se ejecuta ninguna vinculación ir-verdict ni render-verdict, así que un veredicto de rechazo detiene el build, el lint con ámbito de release o la validación con ámbito de release que lo invoca, y no este comando.

Una vinculación en un rol que da forma al grafo se ejecuta durante esa pasada, así que un plugin que no se resuelve detiene el pull. Una vinculación label-transform decide las etiquetas de los nodos antes de que nada se compare con ellas, y una vinculación annotation-transform inyecta anotaciones que se expanden en vinculaciones de Feature; ambas cambian lo que contiene el grafo, así que trazar el grafo implica invocarlas, e invocarlas implica disponer de los bytes propios de cada plugin. Un plugin cuyos bytes esta pasada no puede obtener detiene la ejecución, nombrando el plugin y lo que no se pudo encontrar para él: el mismo rechazo que hace un build del mismo workspace cuando no puede obtenerlos. Lo que invoca es la lista de vinculaciones que esta pasada acaba de resolver, con los ajustes y archivos de definición que el lockfile registra para que un build posterior los reconstruya, de modo que ambas pasadas ejecutan la misma vinculación sobre la misma entrada.

Un Plugin que nombra un paso de pipeline y que nada contiene también detiene el pull. Cada Plugin que nombra la pipeline de una Recipe o FeatureRecipe se resuelve con las demás dependencias de la Release —desde un directorio de catálogo, la copia dentro del binario del compilador, la caché de contenido o el registry—, y uno que ninguno de ellos contiene es uno que tampoco podría cargar un build. Así que el pull se detiene antes de escribir nada, nombrando el Plugin y la Recipe o FeatureRecipe cuyo pipeline lo nombra, con la condición que plantea un build cuando llega a ese paso (A plugin reference is not a Plugin entity (Una referencia a un plugin no es una entidad Plugin)). Eso vale para cada Recipe y FeatureRecipe que vincula el Manifest, incluida una que nada en esta Release vincula, porque cada una se resuelve y se fija tanto si se renderiza como si no. Publica el Plugin, o colócalo en un directorio de catálogo con su .wasm compilado al lado, y vuelve a hacer pull.

Esa detención y una ejecución degradada son resultados distintos, deliberadamente. Un renderizado que no puede terminar —el que describen tanto Cómo encuentra la resolución las entradas externas como Sin conexión— deja correctos todos los pines de dependencias, así que los pines se escriben y se informa de la carencia. Una composición que las comprobaciones rechazan no es una carencia en lo que se resolvió: es una Release que no se puede compilar, así que no se fija nada para ella y la ejecución se detiene.

La caché

El contenido descargado se almacena bajo .aggrega/cache, dividido en un subárbol entities/ para las entidades de catálogo, un subárbol source-artifacts/ para los artefactos de origen y un subárbol inputs/ para las entradas externas que consume un renderizado. La ranura de una entidad de catálogo se nombra por su tipo, su coordenada y su versión —de modo que un Component y una Recipe que comparten coordenada y versión conservan dos ranuras—, la de un artefacto de origen por el lugar del que se descargó, su versión y un prefijo del digest de su contenido, y la de una entrada externa por el digest de su contenido; lo que un build lee de cualquiera de ellas se comprueba con lo que registra el lockfile. Por tanto, pines de versión idénticos comparten una ranura entre varias Releases. Cada ranura de artefacto de origen contiene el archivo comprimido de referencia, una extracción regenerada y un pequeño archivo de metadatos; la extracción se regenera en cada lectura, así que la salida del build depende del archivo comprimido y del lockfile, no del estado de los archivos extraídos.

Todo nombre que la caché deriva de un valor es uno que aceptan Windows, Linux y macOS. Una coordenada, una versión, un host de registry o un digest contiene caracteres que un nombre de archivo no puede contener: la / entre las partes de una coordenada, el : antes de una versión, dentro de sha256: y antes del puerto de un registry. Así que cada valor —un tipo, una coordenada, una versión, un host de registry o un digest— se transcribe antes de convertirse en un nombre de directorio o de archivo: una letra minúscula, un dígito, ., _ y - se escriben tal cual, y cualquier otro carácter se escribe como un escape que empieza por +. El Component core/devtool/adminer:1.0.0 en la versión 1.0.0 es la ranura entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, y una ranura nombrada por un digest de contenido es sha256+zx00003a<hex>. También se escapa una letra mayúscula, de modo que dos coordenadas que solo difieren en mayúsculas y minúsculas conservan dos ranuras en un sistema de archivos que no distingue mayúsculas; un nombre que Windows reserva para un dispositivo, como con, tiene su primera letra escapada; y ningún nombre termina en punto. Dos valores distintos nunca comparten un nombre, y un valor tiene el mismo nombre en todas las máquinas. aggrega cache status enumera cada entrada por los valores a partir de los que se transcribieron sus nombres —una entidad de catálogo por su coordenada, su versión y su tipo— en lugar de por los nombres transcritos.

Una entrada de un archivo comprimido conserva el nombre que le dio su editor, así que en Windows se rechaza una que Windows no puede contener. Los archivos que contiene el archivo comprimido de un artefacto de origen o de una entidad de catálogo se disponen con los nombres que les da el archivo comprimido, no transcritos por la caché. Cuando la extracción se ejecuta en Windows, una entrada que contiene una parte que Windows no puede contener tal como está escrita —un nombre que reserva para un dispositivo, como NUL o aux, con cualquier combinación de mayúsculas y minúsculas y con o sin extensión, o una parte que termina en punto o en espacio— se rechaza con E0340, nombrando la entrada, y no se dispone nada de ese archivo comprimido. En Linux y macOS, una entrada así se dispone con el nombre que tiene. Una entrada que sale del directorio de la extracción se rechaza en todas las máquinas.

La ranura de una entidad de catálogo solo es una entrada con su manifest. La ranura contiene el contenido que sirvió un registry y, a su lado, el manifest que describe ese contenido. Una ranura que solo contiene el contenido —una descarga que se interrumpió entre las dos escrituras, o un archivo colocado allí a mano— no es una entrada: un pull, y un pull de verificación, lo vuelven a pedir al registry de la entidad donde se puede llegar a uno, mientras que un build, que nunca descarga, trata la entidad como ausente, igual que hace un pull cuando no se puede llegar a ningún registry.

Lo que llega a la caché se somete a dos cosas: la forma que describe el propio esquema de la entidad y el lugar que la caché le asigna. Un cuerpo descargado de un registry pasa por el esquema de su tipo —la misma comprobación que lo vuelve a leer— antes de almacenarse en caché, así que una entidad o biblioteca publicada que sirve el registry y que su propio esquema rechaza detiene el pull, nombrando lo que se descargó, en lugar de almacenarse en caché y encontrarse más tarde como un fallo. Y un valor a partir del cual se construye una ubicación de caché que colocaría un archivo en caché en un lugar distinto del que nombra el valor —una versión que es una ruta en lugar de una versión, una ruta url de origen o un module_subdir que sube por encima de su lugar— se rechaza donde se construye la ubicación, nombrando el valor problemático. Un valor escrito en una Recipe o una FeatureRecipe de la que eres autor se somete a lo mismo en el momento en que se construye a partir de él la ubicación de caché, y el module_subdir de un origen git antes aún, antes de descargar el repositorio, como se describe más abajo.

Un repositorio git se archiva desde su propio checkout. Para un origen git-repository, el pull hace checkout del repositorio en el commit que fija y archiva el directorio que nombra module_subdir, o el repositorio entero. Un module_subdir que sube por encima del repositorio tal como está escrito —../shared o ..\shared— se rechaza antes de descargar el repositorio, con E0307 citando el valor, así que no se lee nada junto al checkout. Un enlace simbólico que el repositorio confirma se archiva como el archivo o directorio al que apunta cuando este se encuentra dentro del repositorio; el propio module_subdir puede ser un enlace así. Uno que lleva fuera del repositorio detiene el pull con E0321, nombrando el enlace y adónde lleva, y no se almacena nada en caché, de modo que un repositorio del que haces pull no puede hacer que el pull copie un archivo de tu máquina en el artefacto. El checkout se elimina en cuanto el pull se detiene, así que el mensaje nombra el enlace por su lugar en el repositorio, y el repositorio y la revisión que nombra el origen, en lugar de un directorio que ya no existe. Cambiar el enlace corresponde al repositorio. El límite del workspace enuncia la regla que se aplica aquí.

La caché está anclada al workspace y no al directorio desde el que ejecutaste el comando, así que un workspace tiene una sola caché y un pull ejecutado desde un subdirectorio llena el mismo almacén que lee un build ejecutado desde la raíz.

Un pull en el que no se encontró ningún workspace y no se nombró ninguno se rechaza antes de descargar nada. Cuando nada nombra una raíz y la detección no ancla nada —desde la carpeta en la que lo ejecutas o, para una Release nombrada por una ruta absoluta, desde la propia carpeta de esa Release—, la carpeta sería la raíz, y una caché escrita debajo de ella la convertiría en un workspace. Así que el pull se detiene, no escribe ningún lockfile ni ninguna caché, y nombra la carpeta y las dos maneras de salir de ahí: nombra tu workspace con --workspace-root o AGGREGA_WORKSPACE_ROOT, o da a esa carpeta un .aggrega-config.yaml con un bloque workspace:. La herramienta de pull de aggrega mcp, llamada sin workspace_root en un servidor iniciado sin raíz, se rechaza de la misma manera; Configuración enumera los demás comandos para los que esto vale.

Compilar donde no se puede acceder a la red

Como este comando es el único paso que accede al exterior, una sola ejecución conectada basta para que todos los builds posteriores sean locales. Esa ejecución escribe el lockfile y llena la caché del workspace con los bytes que nombran esos pines, y después un build no necesita nada más.

Tres cosas viajan a la máquina desconectada:

  • La Release y su lockfile. Confirma <release-stem>.lock junto a la Release; es lo que indica al build en qué versión y digest se resolvió cada dependencia.
  • plugins-trust.yaml, cuando el workspace vincula un plugin que devuelve un veredicto. Un build compara las vinculaciones de veredicto que nombra su configuración con ese registro antes de que se ejecute cualquiera de ellas, así que llevar el registro es lo que somete el build desconectado a las identidades que se revisaron y a las firmas que el pull verificó para ellas. Confírmalo junto al lockfile, como describe El registro de confianza de plugins.
  • El directorio de la caché. Las entidades, los artefactos de origen y las entradas fijadas residen todos bajo él, y todo lo que no proporciona un directorio catalog_dirs local se lee de allí.

Compila en la máquina desconectada como de costumbre. Activar allí el modo sin conexión merece la pena aunque un build sobre un lockfile completo lea su clausura desde la caché: convierte un posible acceso a la red en un rechazo inmediato que nombra el modo, en lugar de un intento de conexión que primero tiene que agotar su tiempo de espera. Todo lo que la caché no contiene, y toda entrada externa que el lockfile no fija, detiene el build nombrando lo que falta y la resolución que lo fijaría: no se descarga nada en silencio para cubrir la carencia.

Una máquina aislada de la red y un workspace sin conexión son afirmaciones distintas, y merece la pena mantener la diferencia. Una máquina tras un aislamiento de red puede contener una copia local de un registry, o un catálogo catalog_dirs con todo lo que necesita, en cuyo caso un pull ordinario en esa máquina se puede satisfacer sin acceder al exterior en absoluto. El modo sin conexión describe a qué puede acceder un comando, no lo que contiene la máquina; Sin conexión expone lo que rechaza y lo que deja como está.

Sin conexión

En modo sin conexión —la clave de nivel superior offline en un archivo de configuración, AGGREGA_OFFLINE en el entorno, o --offline en la línea de comandos—, aggrega pull rechaza el acceso a la red. El rechazo se produce antes de intentar cualquier conexión y no como un tiempo de espera agotado a mitad de una descarga, así que un pull sin conexión no llega a ningún registry ni a ningún origen remoto. Cuando un archivo confirmado o una variable exportada activó el modo y quieres saltártelo para un comando, --offline=false permite la red solo para esa ejecución.

--upgrade se rechaza sin más en este modo, y es la única opción aquí a la que le ocurre. Una actualización completa hace flotar cada dependencia hasta la versión más alta que ofrece actualmente un registry, así que necesita preguntar a un registry qué sirve actualmente. Un pull ordinario no: respeta los pines que ya registra, resuelve solo lo que no tiene ninguno, y por tanto se puede satisfacer con lo que contiene la máquina. El rechazo indica cuál de los tres lugares activó el modo y cómo permitir la red para una ejecución.

La resolución recurre entonces solo a lo que la máquina ya contiene: la pila de búsqueda catalog_dirs y la caché bajo .aggrega/cache. Con un catálogo y una caché que satisfacen todas las referencias, un pull sin conexión termina con normalidad y escribe un lockfile ordinario. El lockfile registra el URI, la versión resuelta y el digest de cada dependencia, y nunca cuál de esos lugares sirvió los bytes, así que un pull sin conexión y un pull con conexión que resuelven las mismas versiones escriben el mismo lockfile.

Una dependencia que un pull sin conexión no puede satisfacer localmente lo detiene. La entrada nunca se omite:

  • Una entidad de catálogo que no se resuelve en ninguna parte detiene el pull, nombrando la referencia y desde dónde se referenció, de modo que se nombran tanto la dependencia que falta como lo que la pidió.
  • Un source: remoto detiene el pull, nombrando el origen e indicándote que permitas el acceso a la red o que llenes la caché desde un entorno conectado.
  • Una dependencia que contiene la caché y cuya firma exigida no registra el lockfile, o cuya firma registrada no acepta un build, detiene el pull con el rechazo sin conexión, nombrando la dependencia: registrar la firma implica preguntar a su registry, como describe Respetar o actualizar. Permitir la red para esa única ejecución la registra. Una firma registrada que acepta un build no se vuelve a consultar, así que no detiene un pull sin conexión.

Una entrada externa es lo único que no detiene, y en su lugar lo indica. El renderizado que las encuentra no puede descargar lo que no está ya almacenado, así que un pull sin conexión sobre una Release con una entrada externa sin fijar termina, escribe todos los pines de dependencias que resolvió e informa de tres cosas: que el renderizado no terminó, qué fijó, y que un build de esta Release se detendrá nombrando la URL. Los pines de dependencias que escribió son correctos —nada en ellos dependía del renderizado—, así que se conservan en lugar de descartarse para que un lector los reproduzca.

Esto es deliberado y no una carencia, y no hay ningún interruptor para ello. Un pull que descartara trabajo correcto te costaría la parte que tuvo éxito; un pull que se quedara callado te entregaría un lockfile que parece completo y no lo es. Indicarlo es el único resultado que te deja en condiciones de actuar: vuelve a ejecutar el pull desde un entorno conectado, o desde uno cuya caché ya contenga el contenido, y el mismo comando lo fija.

Así, un pull sin conexión es una negativa a tocar la red y no un resultado reducido para todo lo que nombra un documento, y para las entradas externas es una resolución completada que te dice lo que no pudo alcanzar. Un lockfile que existe es uno cuya resolución de dependencias se completó; si sus entradas externas están completas es lo que te dice la propia salida del pull, y lo que después le exige un build.

--verify en modo sin conexión cubre menos, e informa de ello. Preguntar adónde apunta hoy una ref de origen registrada implica llegar a su remoto, algo que el modo sin conexión rechaza. Así que un --verify sin conexión comprueba las dependencias fijadas y omite ese eje, e imprime una línea que lo indica en lugar de informar de una coincidencia que nunca estableció. Una firma registrada que solo su registry puede confirmar —en una entrada del lockfile cuyo paquete de firma en caché se eliminó o alteró— se omite de la misma manera, en una línea que nombra cada una de esas entradas:

verify: offline, so the signature the lockfile records for "<reference>" was not checked at its registry, which alone can say whether a pull would record it again; this verify does not cover it

Una firma registrada que un pull reescribiría respondiera lo que respondiera el registry se sigue notificando sin conexión, porque no hace falta ninguna respuesta para saberlo, como describe Compara las firmas registradas, en ambos archivos.

Un plugin vinculado a un rol de veredicto que sirve un registry es donde se separan una verificación sin conexión y un pull sin conexión. Un plugin así nunca se fija en el lockfile, así que cada pull resuelve su .wasm desde su registry, y un pull sin conexión sobre un workspace que vincula uno se detiene ahí, nombrando el plugin como uno cuyo .wasm no pudo resolver, incluso cuando la caché de contenido lo contiene, y tanto si ese registry está marcado como advisory u omite la verificación de firmas como si no. Una verificación sin conexión, en cambio, no pregunta nada al registry sobre el plugin: lee el plugin desde la caché de contenido, como lo lee un build, y se detiene donde la caché no contiene su .wasm o contiene uno que ya no coincide con el digest que nombra su manifest publicado. Sigue contrastando la identidad del plugin con el registro de confianza de plugins y vuelve a comprobar sus funciones de host frente a ese .wasm, y se detiene donde cualquiera de los dos discrepa, exactamente como hace una verificación conectada. Informa del plugin donde un pull reescribe su entrada responda lo que responda el registry, que es donde un build rechaza el plugin por su entrada: por no registrar ninguna firma, porque su entrada no registra ninguna o el registro no contiene ninguna entrada para él, o porque la firma que registra su entrada se creó para otro artefacto, que el pull sustituye por la del propio plugin. Cualquier otra entrada —una cuya firma acepta un build, y una cuyo paquete de firma en caché se eliminó o alteró— la nombra en una línea que indica que su firma no se comprobó, y no informa de nada sobre esa firma:

verify: offline, so the signature of "<plugin>" was not checked at its registry, which alone can say whether a pull would record the same signature on its entry in the plugin trust record; this verify does not cover it

Así, una verificación sin conexión pasa por alto una entrada cuya firma un pull conectado sustituiría o borraría —una cuyo firmante se editó a mano, por ejemplo, o una a la que su registry ya no adjunta firma—, y esa línea es lo único que lo indica. Una verificación en una máquina aislada de la red sigue disponible; lo que no te dice es si una ref se ha movido desde entonces, o si una firma omitida se volvería a registrar. Una comprobación que solo lee el código de salida cubre esos casos únicamente cuando la verificación se ejecuta conectada.

Integración con aggrega build

  • Verificación. aggrega build verifica cada dependencia resuelta con respecto al lockfile y se detiene ante una deriva: una entidad, una biblioteca o un plugin cuyo contenido ya no coincide con su pin, una referencia que la Release alcanza ahora y que el lockfile no fija o una que fija y que la Release ya no alcanza, y un archivo de Release editado desde el pull. Ejecuta aggrega pull --release <release>, el comando que imprime la detención, para resolverlo: el pull resuelve la Release tal como está ahora, reescribe los pins que se movieron y mantiene todos los demás, de modo que nada flota si tú no lo cambiaste. Cuando lo que se movió es un archivo bajo la fuente local de una Recipe, el pull indica primero aggrega pin para esa entidad, como describe El lock de la entidad. Un lockfile que este comando acaba de escribir supera esa comprobación, porque el comando ejecuta la misma comprobación antes de escribirlo; un build que se detiene por deriva justo después de un pull recibió entradas distintas de las del pull —un directorio --catalog pasado a uno y no al otro, o una configuración del workspace editada entre ambos—, así que ejecuta los dos sobre las mismas entradas. aggrega validate --release y cada selección de aggrega inspect que resuelve una Release someten el lockfile a la misma comprobación y rechazan con la misma detención, de modo que ninguno de los dos deja pasar un lockfile que un build rechaza.
  • Pull automático. Si falta el lockfile y auto_pull es true, aggrega build ejecuta primero el pull automáticamente. Si auto_pull es false, que es su valor predeterminado, el build se detiene y te pide que hagas el pull. El pull que ejecuta un build sigue pin_sources_at_pull, de modo que sobre una entidad sin pin se detiene exactamente como un pull. El paso de pull que ejecuta un build es el mismo que describe esta página, de modo que un build que completa un lockfile existente se detiene ante un ref de fuente movido exactamente como lo hace aggrega pull —consulta Determinismo e integridad.
  • Sin conexión. En el modo sin conexión, aggrega build usa solo lo que la máquina ya contiene y rechaza el acceso a la red antes de intentar cualquier conexión. Una referencia cuyo contenido no está en la caché detiene el build en lugar de fallar a mitad de una descarga, y un build sin lockfile al que no se le pide completar uno se detiene indicando el pull que lo completaría, exactamente como lo hace con conexión. --auto-pull no se rechaza: el completado que solicita es el pull que describe esta página, de modo que, sobre entidades de catálogo ya almacenadas en caché o presentes en un catálogo local, escribe el lockfile sin contactar ningún registro —una Recipe cuyo chart se obtiene de una fuente remota se resuelve de nuevo, así que sin conexión se detiene incluso donde la caché contiene ese chart—, y una referencia que ninguno de los dos contiene —o una en caché cuya firma requerida el lockfile no registra, o cuya firma registrada un build no acepta— lo detiene con el propio rechazo del pull, que indica esa referencia. --upgrade se rechaza, por el motivo que da Sin conexión.
  • Búsqueda en el catálogo. El pull respeta catalog_dirs de .aggrega-config.yaml incluso cuando no se indica ningún --catalog —y los directorios propios de una Release cuando la configuración le asigna algunos en workspace.releases— y resuelve la misma pila de búsqueda en la que gana la primera coincidencia que usa aggrega build, de modo que las dependencias que fija coinciden con lo que busca el build. Un directorio de la lista que no es un directorio —no existe nada allí, por ejemplo— lo rechazan ambos comandos antes de que se resuelva o se escriba nada, nombrando la entrada y el archivo de configuración y la línea que lo enumeran, como muestra De dónde se leen las entidades locales.

Cómo encuentra la resolución las entradas externas

Nada en esta sección cambia la regla anterior: sigue habiendo un único momento en el que se fija algo, y es este comando. Lo que describe es cómo el comando llega al tercero de los tres tipos, lo cual importa cuando integras la resolución en un pipeline, lees una ejecución que se degradó o razonas sobre por qué este comando renderiza.

Una entidad de catálogo y un artefacto de fuente se nombran cada uno en un documento; una entrada externa no. Resolver los dos primeros consiste en leer lo que escribiste. Una entrada externa la nombra un provider, a mitad de un renderizado, y qué URL nombra depende de los valores que se renderizan: una entrada de valores ausente deja sin compilar todo un subárbol del esquema de un chart y sin solicitar cada referencia remota de ese subárbol. Ninguna lectura de la Release puede enumerar el conjunto.

Así que el comando hace dos cosas en una sola pasada: resuelve y fija la clausura que nombran los documentos, y luego renderiza esa clausura para ver qué documentos remotos solicitan los providers. Los artefactos renderizados se descartan y los pins se conservan. Ambas cosas son internas al único comando, y ninguna es un segundo momento en el que algo pudiera fijarse: hay una sola escritura del lockfile, y contiene cada pin.

Conviene conocer dos consecuencias antes de integrar la resolución en un pipeline automatizado como un paso barato. Cuesta más que una resolución que solo lee documentos, porque renderiza. Y puede fallar por un motivo por el que una resolución basada solo en documentos no podría: un provider que no puede renderizar esta Release. Cuando eso ocurre, los pins de las dependencias se escriben igualmente, porque nada en ellos dependía del renderizado, y el diagnóstico indica la etapa que se detuvo, lo que se fijó y que un build se detendrá indicando la URL sin pin. La ejecución no se pierde, y Sin conexión muestra el mismo resultado alcanzado por otro camino.

El renderizado también somete el lockfile a la comparación que aplica un build, antes de que se escriba nada. Ejecuta la propia secuencia del build, de modo que compara el lockfile que este comando está a punto de escribir con aquello a lo que se resuelve un build de la misma Release, exactamente como un build compara un lockfile que encuentra en disco. Un lockfile que esa comparación rechaza no se escribe —ni nada de lo que el comando habría escrito después—, y el comando se detiene indicando que la resolución y el build no coinciden en aquello de lo que depende la Release, seguido de cada entrada que la comparación nombró. Nada en tus archivos puede causarlo, y resolver de nuevo llevaría al mismo desacuerdo, así que infórmalo junto con la Release en lugar de reintentar. Es el único fallo de renderizado que impide la escritura, y es la razón por la que un build de la misma Release, sobre las mismas entradas, no informa de deriva sobre un lockfile que escribió este comando.

No hay ninguna opción para omitir el renderizado. Una opción así conservaría, como alternativa, justo la sorpresa que elimina un único momento: una Release que se resuelve sin problemas mientras una entrada que necesita su renderizado queda sin pin, y que solo se descubre en el momento del build.

--auto-pull incorpora esta misma resolución a un build, y el build renderiza una sola vez. El renderizado del completado es el que encuentra y fija las entradas externas, y el build presenta ese renderizado en lugar de realizar un segundo, de modo que un build de un solo comando cuesta el mismo renderizado que un build normal sobre un lockfile ya completado. aggrega build expone qué flags de renderizado de un build llegan a él.

El conjunto depende de los parámetros de la Release, que es como ya se comportan los pins de los componentes. Editar los parámetros de una Release entre la resolución y el build es una edición de la Release, de modo que el build se detiene en la comparación de deriva indicando el archivo, antes de que ningún renderizado pueda solicitar una URL sin pin; el remedio es este comando. Los parámetros importados de un archivo separado no se registran por contenido, así que editar en su lugar ese archivo llega al renderizado, que se detiene indicando la URL sin pin, con un remedio que también indica este comando.

Determinismo e integridad

El source: de una Recipe puede definir su versión mediante una plantilla a partir de los values y la infra resueltos de la Release (y sobre los locals definidos en ellos); estos se resuelven en el momento del pull y el resultado se fija. El pull evalúa solo las entradas locals: que leen los campos source:, y las entradas que estas leen a su vez, únicamente con los helpers de plantilla propios de Aggrega: una entrada que lee la fuente y que llama a una función de Sprig detiene el pull indicando la entrada, el campo y la función, mientras que una entrada que ningún campo source: lee se deja al build, que la evalúa y la comprueba cuando renderiza la Recipe —consulta Resolving a source: coordinate registers a narrower function set (Resolver una coordenada source: registra un conjunto de funciones más reducido). Una etiqueta o rama de Git mutable se fija al commit concreto al que apunta, y el ref que escribiste se registra junto a él. En el momento del build, el digest del archivo comprimido en caché se vuelve a verificar con respecto al lockfile, de modo que se detecta una caché manipulada.

Un ref registrado se mantiene en el commit que fijó. El ref se registra porque las ejecuciones posteriores lo vuelven a consultar, no por legibilidad: un build pregunta qué artefacto nombra, y un pull pregunta si sigue apuntando adonde apuntaba. Un pull que no es una actualización vuelve a preguntar a cada ref registrado adónde apunta, y un ref que se ha movido en su remoto detiene la ejecución —indicando el artefacto, el ref, el commit que fija el lockfile y el commit al que se resuelve ahora— en lugar de adoptar el movimiento. Ejecuta aggrega pull --upgrade --release <release> para adoptarlo. Una actualización dirigida, que nombra URI de entidades, no lo hace: una referencia de fuente no es una entidad que puedas nombrar, así que una ejecución dirigida la mantiene exactamente como lo hace un pull simple.

Esa comprobación es lo único que la nueva verificación del digest en el momento del build no puede hacer por ti. Un pull que adoptara un ref movido reescribiría los bytes obtenidos y el digest registrado en el mismo acto, de modo que los dos valores que compara un build se habrían movido juntos y coincidirían, y estarías compilando un contenido de fuente distinto de aquel con respecto al cual se revisó el lockfile, sin que nada lo informara.

Solo un ref que registra el lockfile se mantiene de este modo, y un ref se registra siempre que escribes uno. Una Recipe que nombra su fuente solo mediante version: no tiene ref, así que no hay nada que una ejecución posterior deba volver a consultar, y esa es la respuesta correcta, porque una versión que escribiste tú mismo no puede moverse sin que lo sepas. La referencia del lockfile indica qué se registra.

Escribe el ref, no el commit. Un build encuentra un artefacto con fuente git mediante el ref que escribiste, cotejado con el ref que registró el lockfile, de modo que ref: v1.2.3 compila sobre el commit al que se fijó esa etiqueta y el commit nunca tiene que aparecer en tu Recipe. Indicar en su lugar una etiqueta mutable en version: no funciona ni está pensado para funcionar: version: se coteja tal como está escrito, y para una fuente git el lockfile fija un commit.

El lockfile fija el contenido obtenido de los registros y las fuentes remotas, y registra el digest de cada entidad que resuelve desde tus directorios de catálogo —sobre el archivo de la entidad y cada archivo que nombra junto a él, como describe El lockfile— y de cada archivo de Release que leyó la resolución. Los archivos de una fuente que empieza por ./ o ../, y un archivo de artefacto que importa una entidad, también se fijan uno a uno en el lock junto a esa entidad, como describe El lock de la entidad, que es lo que nombra el que se movió; la integridad del resto de tu workspace entre builds es responsabilidad del sistema de control de versiones. Consulta salida idéntica byte a byte para conocer el alcance de la garantía de determinismo.

Autenticación

Las credenciales de registry se leen únicamente de la configuración de credenciales de Docker: config.json en el directorio que indica DOCKER_CONFIG, o ~/.docker/config.json cuando esa variable no está definida, junto con cualquier credential helper o llavero del sistema operativo en el que el archivo delegue mediante credsStore o credHelpers. aggrega login <registry> escribe allí una credencial, y también lo hace docker login <registry>; ejecuta cualquiera de los dos antes de aggrega pull para un catálogo OCI o un registry de charts privado. Los archivos que escriben podman login y helm registry login no se leen.

Una configuración de credenciales que no se puede leer se notifica sin lo que contiene. Cuando config.json no es JSON válido, el valor auth de una entrada no es un usuario y una contraseña unidos por dos puntos y codificados en base64, o un credential helper que el archivo nombra no puede responder, el acceso al registro falla con un mensaje que nombra el registro y el archivo de credenciales, nunca lo que contiene el archivo o la entrada. aggrega login y aggrega logout notifican de la misma forma un config.json que no es JSON válido, y no cambian nada en él. Corrige el archivo; una entrada que no se puede leer también puede sustituirse con aggrega login <registry>.

Un repositorio de charts de Helm clásico o un archivo de chart (helm-https-chart), un fragmento de compose (compose-https-fragment) y un repositorio Git al que se llega por HTTP o HTTPS (git-repository) se autentican con el archivo netrc, el archivo de credenciales por usuario que también leen curl y Git. Es el único almacén de credenciales que leen estos tres tipos: ~/.config/helm/repositories.yaml y los credential helpers de Git no se leen. Un repositorio Git al que se llega por SSH se autentica a través del agente SSH y no lee ningún archivo netrc.

machine charts.example.com
login deploy-bot
password <token>

Qué archivo se lee. El archivo que indica la variable de entorno NETRC, cuando está definida. Si no, .netrc en tu directorio personal; en Windows, _netrc en %USERPROFILE% cuando ese archivo existe, y .netrc allí cuando no existe. Un archivo que falta no contiene credenciales y no es un error. Un archivo que existe y no se puede leer, o que no sigue el formato netrc, detiene el comando con E0360, nombrando el archivo —y, para un fallo de formato, la línea—, pero nunca lo que contiene el archivo: The netrc file cannot be read (El archivo netrc no se puede leer). En Linux y macOS, un archivo netrc que pueden leer otros usuarios de la máquina provoca una advertencia que lo nombra; haz que solo tú puedas leerlo (chmod 600).

Qué entrada responde a una solicitud. Cada solicitud se busca por su host —el nombre de host sin el puerto, sin distinguir mayúsculas de minúsculas— y la responde la primera entrada machine que nombra ese host, o la entrada default cuando ninguna lo nombra. El login y el password de la entrada se envían como credenciales HTTP basic, tanto por http como por https; una entrada a la que le falta cualquiera de los dos no envía nada. Un repositorio cuyo índice coloca sus charts en otro host se responde solicitud por solicitud: la solicitud del índice toma la entrada del host del repositorio, y la solicitud del chart la del host del chart. Una solicitud que se hace sin credencial debe poder leerse de forma anónima, y un servidor que responde 401 o 403 detiene el pull como una descarga no autorizada, cuyo remedio nombra la entrada que añadir y el archivo en el que se buscó.

La credencial no se escribe en ningún sitio. Se lee cuando se ejecuta una descarga y se envía con la solicitud: el lockfile, el entity.lock junto a la Recipe, la caché de fuentes y cada mensaje llevan la URL de la fuente tal como la escribiste.

Una URL de fuente no lleva credenciales. Una Recipe o FeatureRecipe cuya url de fuente escribe un usuario antes de su host —https://user:token@charts.example.com/…, o un token escrito solo como https://token@charts.example.com/…— se rechaza con E0361 al leerse el documento, antes de descargar nada: validar la Recipe la rechaza, y también cada pull, pin y build que la alcanza. El mensaje nombra el host y nunca la credencial: A source URL carries a credential (Una URL de fuente lleva una credencial). Pon la credencial en una entrada machine del archivo netrc en su lugar. Por SSH, un usuario escrito solo —ssh://git@github.com/…— nombra una cuenta y no un secreto y se acepta, mientras que una contraseña escrita ahí también se rechaza.

La comprobación solo lee la parte de la URL anterior al host. Un token que va en una cadena de consulta o en una ruta —…/index.yaml?access_token=…— no se detecta, así que no escribas ninguno ahí: la URL se registra tal como está escrita en el lockfile, en el entity.lock y en la caché de fuentes, incluidos los nombres de los directorios de la caché.

Variables de entorno

La configuración del workspace que lee pull se puede sobrescribir mediante el entorno, por encima de la configuración confirmada en el repositorio y por debajo de cualquier flag: AGGREGA_OFFLINE (consulta Offline, y --offline para el flag que la supera), AGGREGA_CATALOG_DIRS (separada como una lista de rutas del sistema operativo; indica rutas absolutas), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY y AGGREGA_SKIP_SIGNATURE_VERIFICATION (ruidosa: dondequiera que un pull habría comprobado una firma, registra una advertencia de que la verificación está desactivada globalmente). Consulta environment-variables.md para ver la lista completa y el modelo de precedencia.

Véase también

  • ./aggrega-build.md — verifica el lockfile y hace el pull automáticamente cuando está configurado.
  • ./aggrega-serve.md — el daemon ofrece esta misma resolución en aggrega/resolveDependencies, y dentro de aggrega/build para una solicitud cuyo campo autoPull la pide, de modo que un editor puede ejecutarla sin salir de la sesión; en ambos casos se ejecuta solo cuando una solicitud la nombra, y escribe el mismo lockfile que este comando.
  • ./aggrega-push.md — publica entidades de catálogo en un registro.
  • ./aggrega-lint.md — el control de publicación que precede a aggrega push.
  • ../../architecture/13-catalog-and-registry.md — el modelo completo de catálogo, lockfile y caché.

Sinopsis

aggrega pull [<uri>...] [flags]

Descripción

Resolve the Release's catalog and source dependencies into the cache and write the per-Release lockfile.
By default, pull reconciles the lockfile against the current dependency resolution while honoring
the pins it already records. That pin discipline governs what a registry or the content cache
serves: such an entity is fetched at its pinned version and verified against its pinned digest,
and if the registry no longer serves the pinned bytes, pull halts rather than silently re-pinning.
An entity a local catalog directory supplies is resolved from that directory instead, at the
version its file declares, and its recorded pin is not consulted — so editing a pin by hand does
not hold a locally-supplied entity at that version, and the reconcile rewrites the entry to match
the file. A reference with no pin — newly added, or removed from the lockfile by hand — is
resolved fresh and added. Entities no longer among the resolved dependencies are pruned.
Re-running pull on an unchanged dependency set is a no-op.
Use --upgrade with no positional arguments to discard the existing lockfile and re-resolve
every entity from current registry state, floating each dependency to the highest available
version. That form drops every recorded pin, so it asks for confirmation first; --yes answers in
advance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody can
give. Pass one or more entity URIs after --upgrade to upgrade only those: each named pin
is dropped and re-resolved fresh while every other pin — and the recorded external inputs —
is held unchanged. A named target may also be a plugin that returns an accept-or-reject verdict;
such a plugin carries no lockfile pin, and its identity is recorded beside the lockfile instead.
Naming one the workspace still attaches adopts the identity it resolves to. Naming one the
workspace no longer attaches drops its recorded identity — the one way to clear an entry that
outlived the attachment it was recorded for. A bare --upgrade does both for every plugin at once.
A URI given without --upgrade is a usage error.
Each Recipe and FeatureRecipe this Release builds from one of your catalog directories carries
the pins for its own inputs in the entity.lock beside it: a remote source: written out in full,
a file an artifacts entry imports, and each file of a local source:. Recording them is the
entity author's step, aggrega pin.
By default pull records none of them, and halts on an entity whose lock is missing any, naming
the entity, each input and its class, and the command that records them. A local source's files
are held to their pins as one set: a file added, changed or removed since the pin halts the pull
the same way.
Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull run
that same step instead; --pin-sources=false restores the halt for one run.
Which files of a local source directory belong to its entity was decided when the entity was
pinned, by the ignore rules of the plugin that served its capability for the author, and its
entity.lock records that decision. Where the plugin this workspace binds for that capability
declares different rules, pull prints a warning naming both plugins and the difference, and
carries on: the entity's files are the ones its recorded rules kept.

Flags

FlagPredeterminadoDescripción
--catalog[]Directorio de catálogo; repetible. Cada —catalog <dir> se antepone a la pila de búsqueda del catálogo (gana la primera coincidencia): los catalog_dirs del workspace o, para una Release a la que la configuración del workspace asigna directorios propios en workspace.releases, los de esa Release; la pila termina con el directorio llamado catalog en la raíz del workspace cuando existe. Una lista catalog_dirs escrita vacía no lee ningún catálogo local.
--detailfalseImprime, para cada entidad resuelta, lo que hizo este pull: obtenida de nuevo de un registro, reutilizada desde una ranura de la caché, encontrada en un catálogo local, servida desde dentro del binario del compilador, o externa (el Aggregate o el Manifest propio de la Release, leído del archivo o la entrada que indica la Release). Solo stdout; no se escribe en el lockfile
--dry-runfalseResuelve las dependencias e imprime lo que este pull escribiría en lugar de escribirlo: la ruta de cada archivo y el contenido que tendría van a stdout, y el lockfile, el entity.lock junto a cada Recipe y FeatureRecipe cuyos pins registrados se moverían con —pin-sources, y el registro de confianza de plugins quedan todos intactos. Solo se nombran los archivos que realmente cambiarían. La resolución en sí se ejecuta exactamente igual que en otro caso, de modo que la caché de contenido se llena igualmente, un pull que se detendría ante una entidad sin pin también se detiene aquí, y un —upgrade sin argumentos no pregunta nada porque no descarta ningún pin: lo que muestra una ejecución de prueba es lo que escribiría un pull. No se acepta con —verify, que ya no escribe ninguno de ellos
--include-prereleasefalseAún no implementado: se acepta y se ignora, de modo que un script que lo pasa sigue funcionando cuando empiece a tener efecto
--pin-sourcesfalseEjecuta el paso de pin del autor de la entidad sobre las Recipes y FeatureRecipes que construye esta Release, registrando en el entity.lock junto a cada una el pin de cada entrada que lee —un source: remoto escrito por completo, un archivo que importa una entrada artifacts y cada archivo de una fuente local— en lugar de detenerse ante una entidad cuyo lock no los registra. Es el mismo paso que aggrega pin, y escribe los mismos bytes. Escribe junto a la entidad, por lo que solo se ejecuta donde la entidad tiene una ubicación con permiso de escritura: un documento en uno de tus directorios de catálogo. Una entidad resuelta desde la caché no tiene ninguna y nunca se fija. Anula el pin_sources_at_pull del workspace en ambas direcciones: —pin-sources fija para esta ejecución y —pin-sources=false se detiene para esta ejecución, diga lo que diga la configuración
--progressfalseFuerza la visualización del progreso del pull incluso cuando stderr no es una terminal, imprimiendo una línea simple por paso a medida que se completa, con su tiempo. El valor predeterminado es auto: la lista interactiva de fases solo se muestra cuando stderr es una terminal que interpreta secuencias de escape, una terminal que no las interpreta recibe las mismas líneas simples, y la salida redirigida o canalizada no recibe ninguna
--quietfalseSilencia la visualización del progreso del pull en stderr. No afecta a stdout. Tiene prioridad sobre —progress
--release—Ruta al archivo YAML de la Release (obligatoria). Una ruta relativa se resuelve respecto al directorio en el que ejecutas el comando, no respecto a la raíz del workspace. Cuando ese directorio no pertenece a ningún workspace y no se indica ninguna raíz, una ruta absoluta encuentra el workspace a partir de la carpeta propia de la Release
--upgradefalseVuelve a resolver las dependencias a partir del estado actual de los registros, llevando cada una a la versión más alta disponible. Sin argumentos (sin URI posicionales) descarta el lockfile y vuelve a resolver todas las entidades, y pide confirmación primero porque descarta todos los pins registrados; con uno o más URI de entidades, vuelve a resolver solo esas, manteniendo sin cambios todos los demás pins y las entradas externas registradas, y no pregunta nada (mutuamente excluyente con —verify)
--verifyfalseVerifica el lockfile existente con respecto a la resolución de dependencias que haría ahora un pull, sin escribir el lockfile, el registro de confianza de plugins ni ningún entity.lock; termina con un código distinto de cero ante una deriva o un lockfile ausente. La resolución respeta los pins que registra el lockfile exactamente como un pull: una referencia cuyo registro ha publicado una versión más reciente desde el pull no es una deriva, porque un pull mantendría su pin, y un registro que ahora sirve bytes distintos bajo una versión fijada detiene la verificación igual que detiene un pull. La caché de contenido se lee y se llena igual que la lee y la llena un pull: una entrada que la caché contiene bajo su pin se lee desde ahí sin consultar a ningún registro, una que no contiene se obtiene, y una que ya no coincide con su pin se trata exactamente como la trata un pull. También contrasta el entity.lock junto a cada Recipe y FeatureRecipe de tus directorios de catálogo que alcanza la Release con aquello con lo que lo compara un build, y termina con un código distinto de cero ante un pin que un build rechazaría: un archivo importado que ya no coincide con su digest registrado, una fuente local cuyos archivos ya no coinciden con sus digests registrados, o un pin de fuente que discrepa del lockfile. También compara la firma que registra el lockfile para cada artefacto, y el registro de confianza de plugins para cada plugin, con la que registraría ahora un pull, y termina con un código distinto de cero donde un pull registraría, reemplazaría o eliminaría una: una firma que exige un requisito y que no está registrada, y una hecha para otro artefacto, se informan sin consultar a ningún registro, porque un pull las reescribe responda lo que responda; una firma que un pull vuelve a buscar y podría registrar sin cambios —el artefacto se obtuvo, o su paquete de firma en caché se eliminó o se alteró— se consulta en su registro, o en el modo sin conexión se deja sin comprobar con una línea que lo indica; y cada plugin que cubre el registro de confianza de plugins se verifica en su registro, como lo verifica cada pull, salvo en el modo sin conexión, donde se lee desde la caché de contenido como lo lee un build, su identidad y sus funciones de host se comprueban igualmente, y su firma se deja sin comprobar con una línea que lo indica, a menos que un build lo rechace por no registrar ninguna o por registrar una hecha para otro artefacto, lo cual se informa. Los marcadores de obsolescencia no se comparan. También informa de las versiones del compilador y de los plugins principales que registra el lockfile, que se informan con fines de auditoría y nunca se comparan con este binario, de modo que una diferencia de toolchain nunca es una deriva. No se acepta con —pin-sources, sea cual sea el valor que se le dé: una verificación ni registra un pin que falte en un entity.lock ni se detiene por él, de modo que el flag no cambiaría nada (mutuamente excluyente con —upgrade)
--yesfalseResponde de antemano a la confirmación del —upgrade sin argumentos, para uso no interactivo. Solo afecta a esa confirmación y a nada más: cualquier otra forma de pull no pregunta nada, así que pasarlo no cambia ningún comportamiento en esos casos