aggrega build
aggrega build compila un par Aggregate + Release en artefactos nativos de los providers (manifiestos de Helm, charts de Helm redistribuibles, YAML de docker-compose) en dist/ en la raíz del workspace, como expone Salida. La Release es el único punto de entrada: nombra el Aggregate y el Manifest, declara los límites y enruta los componentes hacia los providers.
Flags comunes
Dos flags tienen un comportamiento que la referencia de flags de más abajo no puede transmitir por sí sola:
--catalog <dir>— un directorio que contiene entidades de catálogo —los tipos de escritura Component, Feature, Recipe y FeatureRecipe junto con los tipos de biblioteca, los Aggregates y los Plugins—, que se carga de forma recursiva. Cada directorio--catalogse busca antes que los configurados, en el orden indicado. Para buscar un catálogo local del proyecto junto a uno compartido, pasa ambos (--catalog ./catalog --catalog ../shared-catalog) o enuméralos encatalog_dirs. Con--detail, cualquier entidad que un directorio de mayor precedencia oculte se informa en stderr, junto con las demás advertencias del build. Un directorio--catalogque no existe detiene el build y lo nombra. Lo mismo hace un directorio enumerado encatalog_dirsque no es un directorio, antes de que se lea o escriba nada, nombrando la entrada y el archivo de configuración y la línea que la enumeran: consulta De dónde se leen las entidades locales. Un build que se detiene porque una referencia no se resolvió en nada nombra, en la nota bajo la detención, cada archivo de esos directorios que declara una apiVersion de Aggrega —una línea que empieza, sin sangría, porapiVersion:con un valor que comienza poraggrega.ai/— y que no se pudo cargar, por ejemplo uno que no se analiza como YAML, con el motivo que da el propio analizador, entre los archivos de catálogo omitidos al cargar; un archivo YAML que declara otra apiVersion, o ninguna, no es un documento de Aggrega y nunca se nombra allí.--detail— informa de lo que hizo el paso de pull, el mismo diagnóstico transitorio de eventos de pull que emiteaggrega pull --detail. Lo que decide si hay algo que informar es si se solicitó un paso de pull —con--auto-pull, o habilitandoauto_pull— y no si ya hay un lockfile: un paso de pull solicitado se ejecuta en cualquier caso, llenando un lockfile que falta y respetando los pins de uno existente. Cuando no se ejecuta ningún paso de pull, el flag imprime una nota de una línea en stdout y continúa: nunca inventa un nivel de resolución que el lockfile confirmado no contiene. Para el estado de resolución posterior al pull de las dependencias de una Release, usaaggrega inspect.
--dry-run se trata en Previsualizar un build sin escribirlo, y --trace y --trace-unredacted en Salida de trace y Mostrar los valores retenidos más abajo.
Llenar el lockfile como parte del build
De forma predeterminada, el build es de solo lectura respecto a las dependencias: necesita un lockfile y no escribe ninguno. --auto-pull y la configuración de workspace auto_pull añaden el paso de pull al build, de modo que un solo comando resuelve las dependencias de la Release y compila con lo que resolvió.
Una edición de la Release es algo que el lockfile detecta. El lockfile registra la Release —y cada Release que esta extiende— por el digest de su contenido, de modo que un build de solo lectura sobre una Release editada desde el pull se detiene antes de renderizar nada, nombrando el archivo e indicándote que ejecutes aggrega pull --release <release>, que registra la edición respetando todos los demás pins. Un comentario o un cambio de espacios en blanco cuenta, porque el digest cubre los bytes tal como son. Un build con auto-pull ejecuta él mismo ese paso de pull, así que registra la edición y hace el build.
La Release se renderiza una sola vez. Qué entradas externas consume una Release se deriva de renderizarla y no de nada que declaren sus documentos, así que el paso de pull renderiza la Release para averiguarlo, y ese renderizado es el del build. Por tanto, un build con auto-pull cuesta un renderizado, lo mismo que un build simple sobre un lockfile que ya está en su sitio.
Los flags que dan forma a un renderizado se aplican a él. --trace, --verify-determinism, --disable-plugin-cache y --no-unsupported-field-warnings alcanzan el renderizado que realiza un build con auto-pull en las mismas condiciones en que alcanzan el de un build simple, así que si pides un trace o una comprobación de determinismo en un build de un solo comando, lo obtienes. --dry-run es la excepción, y es un rechazo y no un silencio: un dry run no escribe nada mientras que el paso de pull escribe, así que la combinación se detiene antes de cualquier trabajo (consulta Previsualizar un build sin escribirlo).
Cómo lee un build lo que fija el lockfile
Un pin del lockfile nombra un contenido —un digest— en lugar de un lugar. Para una entidad es el digest de lo que contiene una publicación de ella, su documento y los archivos que nombra, de modo que una copia de una entidad en un directorio de catálogo y una entrada de caché que contiene su publicación llevan el mismo pin, como describe El lockfile. Un build lee cada dependencia fijada desde las fuentes que ya están en la máquina: primero los directorios de catálogo, como en todas partes, y luego la caché de contenido en .aggrega/cache. Leerlas no consulta ningún registro; solo el paso de pull, donde un build ejecuta uno, descarga.
Una entrada de caché que ya no contiene su pin se omite. Una entidad editada en su sitio —un cuerpo nuevo bajo la misma version— deja en la caché de contenido el cuerpo anterior con ese nombre y esa versión. Donde un directorio de catálogo contiene una copia cuyo contenido tiene como digest el pin, el build lee esa copia y nunca la entrada, y lo indica en el error estándar, nombrando la entrada y ambos digests:
reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytesDonde ningún directorio de catálogo contiene la entidad, una entrada de caché completa que contiene exactamente los bytes fijados se lee como la dependencia, de modo que una entidad eliminada de su directorio de catálogo después de descargar su copia publicada sigue compilándose a partir de esa copia.
Donde ninguna fuente contiene los bytes fijados, el build se detiene antes de renderizar nada, con E0135, o con E0133 cuando el manifiesto de la entrada de caché no es el que fija el lockfile. La detención nombra el pin, la entrada de caché y el digest que contiene, y cada copia de la entidad en un directorio de catálogo con su digest, o bien que ningún directorio de catálogo la contiene. El remedio es un pull con un registro accesible, que descarga de nuevo la versión fijada y contrasta lo que descarga con el pin; consulta Respetar frente a actualizar para saber qué hace el pull cuando el registro ya no sirve esos bytes.
El renderizado que ejecuta aggrega pull para descubrir las entradas externas, y un build o una vista previa mediante aggrega serve o aggrega mcp, leen sus pins de la misma manera.
Entradas externas en tiempo de build
Un renderizado puede solicitar contenido de una URL remota —el esquema de valores de un chart con una referencia remota, por ejemplo— y un build nunca descarga una para añadirla a lo que el renderizado puede leer. Una solicitud de una URL que el lockfile ya fija se sirve desde el almacén de entradas del workspace y se verifica contra el digest registrado antes de que ningún byte llegue al renderizado. Una solicitud de una URL no fijada se detiene, nombrando la URL y el paso que la fija; no hay ninguna configuración que convierta esa detención en una descarga, porque ampliar silenciosamente el conjunto de entradas que lee un build es lo único que un build reproducible no debe hacer.
Donde la copia de una entrada fijada en el almacén ha desaparecido, solo esa entrada se descarga de nuevo por el digest que el lockfile ya registra y se comprueba contra él antes de escribir o devolver nada. Eso no puede cambiar lo que ve el renderizado —el digest quedó comprometido cuando se fijó la entrada—, así que repara el almacén en lugar de ampliar el cierre, y el lockfile queda sin cambios byte a byte. En el modo sin conexión no hay transporte ni siquiera para eso, y la copia que falta provoca en su lugar una detención que nombra el modo.
La fijación ocurre cuando se resuelven las dependencias de la Release, de modo que lo que un build puede leer queda establecido antes de que el build comience. aggrega pull es ese paso, y es el único.
El registro de confianza de plugins
Varios comportamientos de un build dependen de plugins-trust.yaml, el archivo confirmado junto al lockfile de la Release que registra a qué plugin se resolvió cada vinculación que devuelve un veredicto: una vinculación plugins.governance con un rol ir-verdict o render-verdict, y cada vinculación plugins.linter. aggrega pull lo escribe y el esquema del registro de confianza de plugins describe sus campos; lo que sigue trata solo de lo que el propio build hace con él.
Un build se contrasta con el registro antes de que se ejecute ninguno de esos plugins. Un plugin servido desde la caché cuyo digest de artefacto no es el registrado se rechaza en lugar de ejecutarse —esa es la resolución que normalmente toma una vinculación de ese tipo, y aggrega pull expone qué otras formas de resolverla no rige el digest registrado—. Y una entrada registrada de la que ya no da cuenta ninguna vinculación en .aggrega-config.yaml detiene el build: quitar un control no cambia ningún byte renderizado, así que una salida producida sin un control revisado tiene exactamente el mismo aspecto que una salida que ese control aprobó. La detención nombra el plugin y ofrece los dos remedios que difieren según lo que pretendías —volver a vincularlo si la eliminación fue un error, o solicitar la eliminación explícitamente si no lo fue— e imprime el comando listo para ejecutar. Una vinculación que el registro aún no contiene es un primer avistamiento, y ninguna de las dos comparaciones se detiene en ella.
Un build contrasta cada uno de esos plugins con la firma que registra su entrada, exactamente igual que contrasta una entrada del lockfile con la que registra esa entrada. Donde una entrada registra una signature verificada, el build vuelve a calcular el hash del bundle de firma que ese dato nombra en la caché antes de renderizar nada, y se detiene con E0144 cuando el bundle falta o difiere. Para un plugin que lee de la caché de contenido, también lee de ese bundle para qué artefacto se hizo la firma, y se detiene con E0332 cuando se hizo para un plugin distinto del que leyó el build —que es el aspecto de una signature copiada de otra entrada—, diga lo que diga el requisito de firma. Para un plugin servido por la caché de contenido, cualquiera de los dos rechazos nombra aggrega pull --release <release>: el siguiente pull verifica de nuevo la firma del plugin, registra la del propio plugin y almacena en caché el bundle que esta nombra, reescribiendo una copia en caché que ya no coincide con su digest. Donde la configuración de confianza del workspace exige una firma para un plugin que el build lee de la caché de contenido —con la misma configuración que haría que aggrega pull lo rechazara sin firmar, de modo que skip_signature_verification y un registro advisory dejan continuar el build igual que dejan continuar el pull—, una entrada que no registra ninguna firma, o la ausencia de cualquier entrada para el plugin, detiene el build con E0331, nombrando el plugin, plugins-trust.yaml y la configuración que exige la firma. El remedio es aggrega pull --release <release>, que verifica la firma del plugin en su registro en cada ejecución y la registra. Un plugin servido desde uno de tus directorios de catálogo, o desde la copia incluida en el binario del compilador, nunca está sujeto a ese requisito. Como el resto del build, esto lee archivos que ya están en la máquina y no consulta nada a ningún registro.
Un build nombra cada retirada que contiene el registro, junto a cada una de las que contiene el lockfile. Un marcador que aggrega pull registró para uno de esos plugins se informa como una línea deprecation: que nombra el plugin, la severidad registrada y el mensaje del publicador, con cualquier severidad, y build.halt_on_deprecated_severity decide si además detiene el build, con la misma regla que aplica a una referencia fijada. Todas las demás superficies que informan sobre una Release nombran el mismo conjunto con las mismas palabras, y ninguna se detiene por ello: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, la validación y la respuesta de clausura del servidor de lenguaje, y las herramientas describe y validate del asistente. Un registro que existe y no se puede leer detiene el build en lugar de pasar por uno que no registra nada.
aggrega build --upgrade reescribe ese archivo. Implica --auto-pull y ejecuta una actualización completa sin argumentos, que vuelve a resolver cada dependencia y, por tanto, vuelve a resolver y reescribe cada identidad registrada, y descarta cada entrada de la que no da cuenta ninguna vinculación. Así que, si este archivo aparece modificado tras un build de actualización, ese es el motivo: el alcance del flag es cada dependencia, y las identidades registradas forman parte de lo que se vuelve a resolver aunque no sean pins del lockfile. A diferencia de aggrega pull --upgrade, el flag del build no admite un destino, así que no puede limitarse a un solo plugin: para adoptar o descartar una sola identidad, ejecuta en su lugar aggrega pull --upgrade --release <release> <plugin>, que deja intactos todos los demás pins y todas las demás identidades registradas.
Como su alcance es todo, pregunta antes de empezar. aggrega build --upgrade confirma la actualización en las mismas condiciones que el aggrega pull --upgrade sin argumentos: ambos son el mismo acto, así que hacen la misma pregunta. Pasa --yes para responder por adelantado en un uso no interactivo; si la entrada estándar no es una terminal y no hay --yes, el build se niega en lugar de esperar una respuesta que nadie puede dar. Un build que no actualiza no pregunta nada.
Resolución del workspace y determinismo
La referencia manifest: de la Release, obligatoria según el esquema, se resuelve en relación con el archivo de la Release. Una entrada catalog_dirs relativa (y una ruta relativa de plugin en el sistema de archivos) se resuelve respecto al directorio del .aggrega-config.yaml que la declaró: «relativo» siempre significa relativo al archivo en el que lo escribiste, de modo que una ruta significa lo mismo desde dondequiera que invoques aggrega. Un flag --catalog, que no tiene un archivo declarante, se resuelve respecto al directorio de trabajo actual. Las referencias de registro (oci://…, una referencia de hub) se dejan tal cual.
La raíz del workspace es el directorio del .aggrega-config.yaml antecesor más cercano que contiene un bloque workspace:, o el directorio que nombra --workspace-root. Cuando la raíz se fija de esta manera, un build es independiente del lugar de invocación: ejecutar aggrega build desde la raíz del proyecto y desde un subdirectorio produce IR y artefactos renderizados idénticos byte a byte, porque el catálogo en el que se busca y las rutas de origen registradas en la salida no cambian con el directorio de trabajo. (Sin el marcador workspace: y sin --workspace-root, el directorio de trabajo es la raíz, así que la salida se ancla allí en su lugar, salvo que el directorio de trabajo no ancle nada y --release nombre la Release mediante una ruta absoluta: la raíz se descubre entonces de nuevo a partir de la propia carpeta de la Release, de modo que el catálogo en el que se busca y las rutas registradas en la salida son las del proyecto al que pertenece la Release, desde dondequiera que ejecutes el comando. Consulta configuration.md.) Donde tampoco así se encuentra un workspace y nada nombra uno, el build advierte en el error estándar que la carpeta que usó como raíz no está dentro de ningún workspace, y nombra el comando que la convierte en uno; un build al que se le pide resolver primero sus dependencias se rechaza antes de descargar nada, porque la caché que esa resolución llena se escribiría en esa carpeta y la convertiría en un workspace. Un build que no resuelve nada antes sigue renderizando, pero por la misma razón una entrada externa que el lockfile fija y que la caché ya no contiene no se descarga de nuevo: al plugin que la solicita se le comunica en su lugar la frase del rechazo, igual que se le comunica la del modo sin conexión, y el build informa de lo que ese plugin hace con ello. Un --workspace-root o AGGREGA_WORKSPACE_ROOT que nombra una carpeta inexistente se rechaza antes de que el build haga nada más, indicando cuál de los dos la proporcionó.
Variables de entorno
La configuración del workspace que lee el build puede sobrescribirse mediante el entorno, por encima de la configuración confirmada y por debajo de cualquier flag: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (separadas según la lista de rutas del sistema operativo; proporciona rutas absolutas), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY y AGGREGA_WORKSPACE_ROOT. Consulta environment-variables.md para ver la lista completa y el modelo de precedencia.
Salida
Los artefactos renderizados se colocan en dist/ bajo la raíz del workspace, sea cual sea la carpeta desde la que se ejecuta el comando —la propia raíz, una carpeta por debajo de ella o una carpeta en otro lugar con la raíz nombrada por --workspace-root o AGGREGA_WORKSPACE_ROOT—, y la línea final nombra ese directorio completo:
Build completed: 4 files written to <workspace>/dist<workspace> representa aquí la raíz del workspace, que la línea escribe como ruta completa. Donde no se encuentra ningún workspace y nada nombra uno, la carpeta desde la que se ejecutó el comando es la raíz, así que dist/ se escribe allí. Un dist que es un enlace que conduce fuera del workspace se rechaza antes de eliminar o escribir nada en él. Una Release que no declara límites escribe por provider: dist/<provider>/<files>. Un límite declarado sin directory: escribe por límite y por provider: dist/boundaries/<boundary-path>/<provider>/<files>. Las anulaciones directory: y subDirectory: escritas por el operador en los límites de la Release cambian la ruta de destino; el colapso por (path, provider) fusiona los contribuyentes que se resuelven en la misma ruta evaluada.
Archivos que el build no escribió
Un build escribe sus propios archivos y no elimina nada que no haya escrito, con una excepción: dist/boundaries/, que un build regenera por completo, se vacía antes de la escritura, de modo que un archivo que dejó allí un build de otra variante no sobrevive en un árbol que ya no lo produce. Todo lo demás en dist/ se deja tal como está —un archivo que escribió un build anterior y que este ya no produce, un archivo que el directory: de un boundary colocó allí en una ejecución anterior y un archivo que pusiste allí tú mismo por igual—, porque el build no puede distinguir un resto de un archivo que guardas allí a propósito.
Lo que hace en su lugar es decírtelo. Una vez escritos sus archivos, el build mira en el propio dist/ y en cada directorio por debajo en el que escribió un archivo o por el que pasó para escribir uno más profundo, y nombra cada archivo de allí que no escribió en esta ejecución, en una sola advertencia en la salida de error estándar. Los archivos se nombran por sus rutas relativas a dist/, ordenadas, de modo que el mismo árbol se informa de la misma manera en cada ejecución:
warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"La línea de cierre los cuenta a continuación:
Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not writeEn un directorio en el que el build no escribió nada, ni directamente ni más abajo, no se mira, de modo que una carpeta propia que guardes bajo dist/ no se enumera archivo por archivo. Un build que no encuentra ningún archivo así no imprime ninguna advertencia, y su línea de cierre es la que se muestra en Salida. En cualquier caso, los archivos que escribe el build son los mismos bytes. Para comparar dos builds, o para empezar desde cero, elimina dist/ antes de compilar.
La solicitud aggrega/build de aggrega serve y la herramienta build del asistente (aggrega mcp) escriben a través del mismo paso, así que nombran los mismos archivos con la misma frase: el daemon como uno de los notices de su respuesta, y la herramienta como el último de sus advisories. Una ejecución de prueba no escribe nada, así que no informa nada de esto.
Sangría YAML
Cada artefacto YAML renderizado —archivos docker-compose, plantillas y valores de charts de Helm, y manifiestos de Kubernetes— se emite con un ancho de sangría uniforme. El ancho lo establece build.yaml_indent en .aggrega-config.yaml y su valor predeterminado es 2 (el ancho convencional para esos formatos):
build: yaml_indent: 2 # default; accepts 2 through 9El ancho se aplica en un único punto de serialización compartido por todos los renderizadores, de modo que la salida se mantiene idéntica byte a byte entre ejecuciones con la misma entrada. Los valores fuera del rango [2, 9] los rechaza la validación del esquema de configuración.
Devolver el grafo compilado
--ir-graph escribe en la salida estándar, como JSON, el grafo que resolvió este build. Es aditivo: los artefactos se siguen escribiendo en dist/, el resumen se sigue imprimiendo y los bytes renderizados no cambian. El grafo sale antes que todo lo demás que el build imprime allí —un documento JSON y un salto de línea final—, de modo que un consumidor que decodifica el flujo lo lee y se detiene.
El grafo devuelto es el que consumió el renderizado, así que describe exactamente el build que produjo los artefactos que lo acompañan y no una segunda resolución de la misma Release. Se combina con --dry-run: el grafo se escribe y el informe de artefactos lo sigue, sin escribir nada en disco.
Los valores que un autor declaró sensibles se retienen en él —incluidos los values y infra de una conexión, cuando el socket del componente consumidor declara sensible una hoja—, en la forma estructurada descrita en aggrega inspect. --unredacted junto a --ir-graph los imprime en su lugar, en las condiciones que establece aggrega inspect --unredacted: alcanza el grafo y nada más —los archivos de trace tienen su propio --trace-unredacted, y los artefactos renderizados nunca se retienen— y todo lo que alcance la salida contendrá entonces esos valores en claro. Si se pasa sin --ir-graph, se rechaza, porque no habría nada que revelar.
El mismo flag, con el mismo significado, está en aggrega inspect y aggrega validate.
Previsualizar un build sin escribirlo
--dry-run ejecuta la misma compilación que ejecuta un build —los mismos controles de dependencias, el mismo renderizado, los mismos providers— e imprime lo que emitiría en lugar de escribirlo. Cada artefacto se informa con la ruta que ocuparía y el contenido que tendría:
aggrega build --release releases/production.yaml --dry-run==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==apiVersion: v1kind: ConfigMap...
Total build time: 2.5sDry run: 1 file would be written to <workspace>/dist; nothing was writtenLos artefactos se informan en el orden en que un build los escribe, de modo que la misma entrada informa los mismos bytes en la misma secuencia, y la ruta informada es la ruta en la que escribiría un build: bajo la raíz del workspace, escrita completa donde arriba figura <workspace>.
Lo que no se escribe. El directorio de salida se queda exactamente como está; tampoco se limpia, así que la salida de un build anterior sobrevive intacta a un dry run. El lockfile no se escribe. No se escribe nada en .trace/.
Las entradas externas se comportan exactamente como en un build ordinario, en las condiciones que expone Entradas externas en tiempo de build. Por tanto, un dry run lee el mismo cierre fijado que leería el build al que representa, y lo que muestra es lo que ese build escribiría.
Donde se rechazó una referencia, la ejecución nombra todas las que no pudo alcanzar y señala el comando que las fija:
note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit: - https://charts.example.com/values-schema.json Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run againEjecuta aggrega pull una vez y el dry run tendrá todo lo que necesita; nada más cambia en él.
Un dry run necesita un lockfile y nunca llena ninguno. El build es de solo lectura de forma predeterminada, y un dry run se atiene a ello sea cual sea la forma en que se solicitó un llenado. --auto-pull y --upgrade se rechazan directamente (más abajo); la configuración de workspace auto_pull se anula para esa única invocación, de modo que un workspace que llena de forma predeterminada se puede previsualizar igualmente. Sin lockfile, un dry run se detiene con el mismo remedio que da un build ordinario de solo lectura: ejecuta primero aggrega pull.
Los flags que rechaza. Tres flags escriben, así que combinarlos con un dry run no tiene un resultado honesto: ignorar la escritura haría desaparecer un llenado solicitado, y respetarla rompería la única promesa que hace el dry run. Cada combinación se detiene antes de cualquier trabajo, nombrando el flag que pasaste y el paso que debes ejecutar en su lugar:
| Combinado con | Por qué se rechaza |
|---|---|
--auto-pull | llena el lockfile; ejecuta aggrega pull como paso independiente |
--upgrade | vuelve a resolver cada dependencia y reescribe el lockfile; ejecuta aggrega pull --upgrade como paso independiente |
--trace | escribe archivos por nodo en .trace/; ejecuta el build con trace sin --dry-run |
Todo lo demás se combina con normalidad. --verify-determinism renderiza cada nodo dos veces y compara los bytes sin escribir ninguno, y --catalog, --quiet, --progress, --debug y los filtros de advertencias se comportan exactamente igual que en un build que escribe.
Para qué sirve y para qué no. Un dry run responde a «qué emitiría esta Release», una pregunta que solo un renderizado puede responder, así que no sustituye a aggrega validate, que comprueba la corrección sin renderizar, ni a aggrega inspect, que consulta el grafo antes del renderizado. Recurre a un dry run cuando la respuesta que quieres son los propios artefactos: revisar lo que un cambio en la Release hace a la salida, o comprobar una edición de una Recipe antes de confirmar nada en dist/.
Salida de trace
El flag --trace activa un volcado de depuración por nodo que captura cada estado intermedio del compilador. La salida se encuentra en .trace/ bajo la raíz del workspace, junto a dist/ (nunca dentro; la disposición en paralelo sigue la convención de .git/, .terraform/, node_modules/ y mantiene dist/ puramente desplegable).
La estructura de directorios es por límite y por instancia:
.trace/└── boundaries/ └── <boundary-path>/ └── <instance-id>/ ├── 01-pillars-initial.yaml ├── 02-provides-evaluation.yaml ├── 03-inject-hydration.yaml ├── 04-inject-mapping.yaml ├── 05-source-resolution.yaml ├── 06-source-locals.yaml ├── 07-values-mapping.yaml ├── 08-workload-synthesis.yaml ├── 09-artifact-evaluation/ │ └── <per-artifact-file>.yaml ├── 09b-feature-rendering-boundary.yaml ├── 10-engine-synthesis/ │ └── <per-synthesized-file>.yaml ├── 11-engine-emission.log └── 12-labels-injected.logCada ranura captura un estado concreto del compilador:
01-pillars-initial.yaml— la instantánea por nodo del contexto que lee una plantilla, tomada tras la resolución y antes de cualquier mutación por etapa. Contiene.values,.infra,.context,.parameters,.metadata.02-provides-evaluation.yaml— las salidasprovides:resueltas tras la evaluación de provides.03-inject-hydration.yaml— la tubería.context.injectfusionada tras la hidratación de inject (vista desde el consumidor de losprovidesde origen).04-inject-mapping.yaml— la tubería.context.injecttras las reescriturasinjectMappingde la FeatureRecipe.05-source-resolution.yaml— el contenidosource:analizado que consumirá el provider. Solo está presente cuando la Recipe declarasource:.06-source-locals.yaml— el bloquelocals:resuelto. La resolución del origen publica.localsantes de evaluar la plantillasource:, por lo que esta ranura se escribe tanto si la Recipe declarasource:como si no.07-values-mapping.yaml— la salida renderizada devaluesMapping:(el diccionario que recibe el provider). Solo está presente cuando la Recipe declaravaluesMapping:.08-workload-synthesis.yaml— el contexto tal como estaba cuando se evaluó la plantillaworkload:y se analizó su salida. Solo está presente cuando la Recipe declaraworkload:(en línea o cargado con$import:). ElWorkloadanalizado no está en esta ranura: aparece a partir de09-artifact-evaluation/, una vez asentado y no en curso.09-artifact-evaluation/— un archivo por cada artefacto evaluado. Solo está presente cuando la Recipe declaraartifacts:(con entradas en línea o cargadas por entrada con$import:).09b-feature-rendering-boundary.yaml— el contexto tal como queda al terminar el renderizado del nodo, una vez que las FeatureRecipes adjuntas a él han generado sus recursos, con elworkloadanalizado al lado. Se escribe para cada nodo.10-engine-synthesis/— un archivo por cada manifiesto sintetizado que el provider produjo a partir del Workload (modo workload de helm/compose). Solo está presente cuando el provider siguió una ruta de síntesis.11-engine-emission.log— el resumen posterior a la emisión (número de archivos, rutas de salida) del nodo.12-labels-injected.log— las etiquetas y anotaciones de procedencia escritas en la salida renderizada del nodo.
A partir de 03-inject-hydration.yaml, una ranura que muestra el contexto del nodo contiene el bloque .context.inject siempre que la tubería que captura entregue al menos una clave, mediante cualquier mecanismo: env, file, arg, o un mecanismo de otro nombre en el que escribe un mapeo inject, el injectMapping de una FeatureRecipe o el propio bloque inject: del componente. Un nodo cuya única entrega es uno de esos mecanismos personalizados también muestra el bloque, con ese mecanismo bajo su propio nombre y sus claves en all, y un valor declarado sensible se lee como <redacted> en ambos lugares. Una ranura tomada mientras la tubería no entrega nada no tiene bloque .context.inject.
El escritor del trace no es bloqueante: el trace se escribe en disco en paralelo con la compilación en lugar de en su camino. La latencia de compilación no se ve afectada por la E/S del trace: la misma compilación termina en el mismo tiempo real tanto si --trace está activado como si no.
Valores declarados sensibles en el trace
Un dato que un autor declaró sensible —una hoja de esquema que lleva sensitive: true, o una clave de entrega cuyo material procede de una clave provides que lo lleva— se escribe en el trace como el texto fijo <redacted>. La clave se mantiene y solo se sustituye el valor, de modo que una ranura sigue mostrando qué hojas y qué claves de entrega tiene un nodo. Un elemento hermano no declarado en el mismo bloque imprime su valor literalmente; la sustitución sigue a la declaración y a nada más.
Un valor que una FeatureRecipe entrega mediante su propio injectMapping también se retiene. Esa es la vía a la que una ranura que declara una lista inject vacía confía la entrega, y la vía que sigue una realización de credenciales solo por inject. La clave de entrega que escribe un mapeo así es en sí misma una plantilla, así que ninguna declaración la nombra; lo que se lee en su lugar es el propio texto del mapeo. Cuando ese texto hace referencia a una hoja values o infra que la Feature vinculada declara sensitive: true, cada clave de entrega que produjo el mapeo se lee como <redacted>, incluida una clave que no contiene nada sensible, ya que la lectura es por vinculación y no por clave. Un mapeo que no hace referencia a nada declarado imprime sus claves literalmente.
Un valor que una plantilla calculó a partir de un dato declarado sensible también se retiene, aunque su propia clave no lleve ninguna declaración. Lo que lo identifica es la referencia que escribió el autor: una entrada locals: cuya plantilla lee una hoja declarada sensible se retiene, y también un campo source: que lo hace. La lectura es conservadora —una plantilla que alcanza un objeto entero alcanza cada hoja declarada bajo él, así que {{ range $k, $v := .values.creds }} retiene su salida cuando algo bajo creds está declarado— y una entrada locals: que lee un hermano ya retenido se retiene a su vez. Una entrada hermana de la misma forma que no lee nada declarado se imprime literalmente.
Un valor que viaja a través de una arista uses se retiene según las declaraciones del destino, no del nodo consumidor, y se retiene en las dos superficies a las que la arista lo lleva. .context.uses.<alias>.provides reproduce lo que publicó el componente de destino, así que lo que rige esos valores es el esquema del destino: una clave provides que el destino declaró sensible se lee como <redacted> en la ranura del consumidor incluso cuando el consumidor no declara nada en absoluto. Cuando el propio bloque inject de la arista enruta esa clave hacia una clave de entrega del componente consumidor, .context.inject retiene también esa clave de entrega: la misma regla que ya sigue el mapeo inject de una vinculación, leyendo la misma declaración. La retención es por arista, así que dos aristas que publican el mismo nombre de clave provides se resuelven de forma independiente: aquella cuyo destino la declaró se retiene y la otra se imprime literalmente. El resto de la arista —su destino, su socket, sus etiquetas y los nombres de clave propios del mapeo inject— no es lo que rige una declaración provides del destino, y se imprime literalmente.
Los values e infra por conexión escritos en la propia arista se rigen, en cambio, por el socket del componente consumidor: el valueSchema y el infraSchema que declara ese socket, que son los contratos con los que se valida esa configuración. Una hoja que cualquiera de los dos contratos declara sensitive: true se lee como <redacted> en .context.uses.<alias>.values o .context.uses.<alias>.infra, conservando la clave, y lo mismo ocurre con una hoja que está en un valor predeterminado que declara el contrato; un elemento hermano no declarado se imprime literalmente. Las declaraciones del destino no intervienen aquí, y la retención es por conexión, así que una hoja del mismo nombre en una conexión cuyo socket la declara legible se imprime literalmente.
Las vinculaciones escritas en una conexión se muestran bajo la arista de esa conexión, en .context.uses.<alias>.features.<slot>, y cada una se retiene según las declaraciones de su propia Feature, las mismas que rigen esa Feature cuando un componente la tiene directamente. Una hoja values o infra que la Feature declara sensitive: true se lee como <redacted>, y lo mismo ocurre con una clave de los provides resueltos de la vinculación que la Feature declara sensible; cada clave se mantiene. El tipo, la versión y las etiquetas de la vinculación, y cada hoja y clave provides que su Feature deja sin declarar, se imprimen literalmente, de modo que un localizador publicado sigue siendo legible junto al material que localiza. La retención es por conexión y ranura, así que la misma Feature escrita en dos conexiones se resuelve en cada una. Una ranura que declara sensitive: true —en el componente o en su socket— indica que la vinculación maneja material secreto y no retiene ninguna hoja por sí misma: qué hojas se retienen lo declara la Feature. Las vinculaciones propias de un componente no están entre los bloques que muestra una ranura, ya que el trace no lleva ningún bloque .features; lo que una plantilla workload: lee de una de ellas lo cubre el nuevo renderizado que se describe más abajo.
El Workload analizado es un nuevo renderizado, no una captura del documento que emitió el build, y las ranuras que lo contienen —09-artifact-evaluation/, 10-engine-synthesis/ y 09b-feature-rendering-boundary.yaml— lo indican en una entrada workload_note junto a él. Un documento renderizado no registra nada sobre de qué declaración procede un carácter dado, así que no hay ninguna clave en la que sustituir dentro de él. Lo que muestra el trace en su lugar es la misma plantilla workload: evaluada una segunda vez, sobre un contexto cuyos datos declarados sensibles ya se leen como <redacted>. Como la plantilla ve una cadena donde había una cadena, el resultado conserva la forma del documento emitido: los mismos campos, en los mismos lugares, con <redacted> en la posición misma del dato retenido y el texto literal que lo rodea sin cambios.
Dos formas en que ese nuevo renderizado difiere de lo que se emitió, ambas indicadas en la nota:
- Una plantilla que se bifurca según el contenido de un valor se renderiza de forma distinta. Un
eqcontra un valor concreto, una prueba de longitud, un hash o una codificación del valor: cada uno ve<redacted>y produce un resultado distinto —otra rama, otra longitud, otro digest—. Por eso el trace nunca afirma mostrar el documento emitido. - Los datos que ninguna declaración nombra se transmiten sin cambios. La sustitución cubre lo que nombra el eje: una hoja
values/infradeclarada, una clave de entrega marcada, una claveprovidesque el propio Component del componente declara sensible, losprovidesdeclarados de un destino consumido, una hoja de losvaluesoinfrapropios de una conexión que su socket declara sensible, una hoja o claveprovidesdeclarada de una vinculación que el propio componente tiene (leída en.features.<name>) o de una escrita en una conexión, y un valorlocals:osource:calculado a partir de uno de ellos. Son los mismos datos por los que se retiene un rechazo generado por la plantilla. Un dato que llega a la plantilla por cualquier otra vía, como una claveprovidesque ninguna declaración nombra y cuyo valor calculó una Recipe a partir de una hoja declarada, aparece en el nuevo renderizado exactamente igual que en el documento emitido.
Cuando el nuevo renderizado no se puede producir en absoluto, la ranura mantiene la clave workload: y sustituye el documento por una línea que lo indica y nombra --trace-unredacted. La indicación es deliberada: una proyección que simplemente desapareciera sería indistinguible de una Recipe que no declara ningún workload:.
Conviene leer un límite antes de tratar .trace/ como seguro: dist/ no se oculta. Los artefactos renderizados se emiten exactamente como los produjo el renderizado, porque son lo que se despliega, y el nuevo renderizado del trace nunca los alcanza: la misma entrada se renderiza de forma idéntica byte a byte tanto si --trace está activado como si no.
Trata .trace/ como portador de material sensible y manéjalo como se maneja dist/.
Mostrar los valores ocultos
--trace-unredacted, junto con --trace, escribe en los archivos de traza los valores declarados sensibles en lugar del texto que los sustituye. Existe porque a veces el valor oculto es justo el que se está depurando — una credencial que llega desde el anexo equivocado parece idéntica a la correcta cuando ambas aparecen como ocultas.
También es la forma de capturar el documento que la compilación emitió realmente: si no se oculta nada, no hay nada que sustituir, de modo que los slots workload: contienen el documento emitido en lugar de una nueva renderización de él, y la entrada workload_note no aparece.
Tres propiedades lo delimitan:
- Cada archivo que escribe indica lo que es. Cada archivo de traza que produce la ejecución comienza con un comentario que nombra el flag e indica que más abajo aparecen en claro los valores declarados sensibles, de modo que un archivo adjuntado más tarde a un informe de errores o dejado en un directorio compartido lleva su propia advertencia. El comentario es válido en el formato propio del archivo, así que el archivo sigue pudiéndose analizar.
- Alcanza
.trace/y nada más. Los artefactos renderizados son idénticos byte a byte con y sin él — cambia lo que muestra un archivo de depuración, nunca lo que produce una compilación — y los formatos deaggrega inspecty el texto de diagnóstico que imprime una compilación fallida son idénticos en ambos estados. - Solo existe en la invocación. No hay ninguna opción de configuración para él, por lo que no se puede activar una vez y dejar activado para todos los que compilen el workspace después. Solicitarlo sin
--tracedetiene la compilación con un mensaje que nombra ambos flags, en lugar de aceptar una solicitud que no puede cumplir.
Aparte de la traza, una compilación imprime un aviso por cada clave de entrega que transporta material declarado sensible como valor literal, nombrando el componente, el destino, el anexo y la clave de entrega. Nunca detiene la compilación y --no-unsupported-field-warnings no lo silencia — ese flag cubre lo que un destino no puede cumplir de lo que tú escribiste, una clase distinta.
La palabra clave, sus dos lugares de escritura, la redacción exacta del aviso y el límite completo de lo que consigue declararla están en vocabulary/compact-form-authoring.md, «Declarar una hoja como sensible».
Cuándo usar --trace
- Diagnosticar por qué un manifiesto renderizado no contiene un valor esperado: recorre los volcados por pasada para encontrar el primer slot en el que falta el valor.
- Verificar el determinismo tras una actualización del compilador: dos compilaciones de la misma entrada con
--traceproducen volcados de traza idénticos byte a byte; cualquier diferencia por slot localiza la regresión. - Iteración al escribir un catálogo: comparar las instantáneas
04-inject-mapping.yamly06-source-locals.yamlmuestra lo que ven las plantillas de la Recipe en el momento de la evaluación.
Ejemplos
Compilar una Release contra el catálogo local:
aggrega build --release releases/production.yamlCompilar con un directorio de catálogo independiente:
aggrega build --release releases/production.yaml --catalog ../platform-catalog/Ver lo que emitiría una Release sin escribir nada de ello:
aggrega build --release releases/production.yaml --dry-runCompilar con volcados de traza para depurar:
aggrega build --release releases/production.yaml --traceTras la compilación, inspecciona .trace/boundaries/<boundary>/<instance>/ para ver el estado de cada pasada. El directorio .trace/ se sobrescribe en cada ejecución con --trace; el estado de traza anterior no se conserva entre compilaciones.
Referencias cruzadas
aggrega-pull— obtiene entidades del catálogo desde un registro OCI al catálogo local.aggrega-validate— comprueba la corrección del catálogo, del cierre de la Release o de una sola entidad sin emitir artefactos; la validación de dependencias que ejecuta una compilación, sin la renderización.aggrega-lint— comprueba las convenciones de publicación del catálogo en los mismos tres ámbitos.aggrega-inspect— consulta el grafo IR tras la finalización del grafo sin continuar con la renderización.- Errores — el formato categorizado de presentación de errores que aparece en la CLI.
Sinopsis
aggrega build [flags]Descripción
Compile an Aggregate and Release pair into provider-native artifacts under eachboundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,declares the boundaries, and routes each component to a provider. What aprovider emits is the provider's own shape — Helm manifests, a redistributableHelm chart, docker-compose YAML — so the output directory holds whatever theproviders this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder thecommand is run from, and the closing line names it in full. A run that finds noworkspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first tocreate one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makesthe rendered tree reviewable as a diff.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--auto-pull | false | Ejecuta el paso de pull antes de compilar: resuelve las dependencias de la Release en el lockfile y la caché dentro del proceso y luego compila contra ellas. Es el mismo llenado dentro del proceso que realiza la opción auto_pull del workspace, activado para una sola compilación sin editar la configuración del workspace. Por sí solo es un llenado incremental — se respetan los pines existentes, y las referencias sin pin se resuelven y se añaden |
--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. |
--debug | false | Emite en stderr diagnósticos detallados legibles por personas — tiempo real por fase y recuentos de entidades/dependencias. Prevalece sobre —quiet: la salida detallada siempre se emite. Distinto de —trace, que escribe archivos intermedios por nodo legibles por máquinas en .trace/ |
--detail | false | La compilación es de solo lectura de forma predeterminada y no imprime detalles de resolución. Cuando se ejecuta el paso de pull — porque se pasó —auto-pull o el workspace habilita auto_pull —, la compilación llena el lockfile dentro del proceso, exista ya uno o no, y este flag imprime para cada entidad resuelta lo que hizo ese llenado: obtenida de nuevo desde un registro, reutilizado un slot 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 de la entrada que nombra la Release). Cuando no se ejecuta ningún paso de pull, imprime una línea que lo indica en lugar de las filas por entidad. Solo stdout; no se conserva |
--disable-plugin-cache | false | Omite la caché persistente en disco de compilación de plugins para esta compilación y compila los guests de plugins desde cero en una caché en memoria que se descarta al terminar la compilación. Desactivado de forma predeterminada, lo que reutiliza la caché compartida en disco entre compilaciones. No cambia la salida renderizada |
--dry-run | false | Renderiza la Release e imprime lo que emitiría en lugar de escribirlo: la ruta prevista de cada artefacto y su contenido van a stdout, y el directorio de salida y el lockfile quedan intactos. Las entradas externas se comportan exactamente como en una compilación normal — las entradas con pin se sirven desde el almacén direccionado por contenido (y se rellenan por digest cuando falta el blob), y una renderización que solicita una URL externa sin pin se detiene nombrándola —, de modo que lo que muestra una ejecución de prueba es lo que escribiría una compilación. Se niega a combinarse con —auto-pull, —upgrade o —trace, cada uno de los cuales escribe — ejecuta el llenado de dependencias, o una compilación con traza, como un paso propio. Se combina con —policy-input, cuyos archivos son entonces lo único que escribe |
--ir-graph | false | Escribe además en stdout, como JSON, el grafo IR que calculó esta ejecución, además de todo lo que este comando ya produce. Los valores que un autor declaró sensibles se ocultan en él; pasa —unredacted para imprimirlos en su lugar. Los artefactos se siguen escribiendo y el resumen se sigue imprimiendo; el grafo se escribe antes que ambos |
--no-unsupported-field-warnings | false | Silencia la clase de advertencias de campos no admitidos: los avisos que un destino emite por algo que escribiste y que no puede cumplir — un campo del Workload que no puede expresar (como le ocurre a un destino de menor fidelidad como compose), o una anotación aggrega.ai/ sobre la que no actúa para el tipo de entrada del nodo. Las demás advertencias de renderización siguen apareciendo. Solo de visualización; no cambia la salida renderizada |
--policy-input | — | Escribe, en este directorio, el payload que cada rol de gobernanza entrega a un plugin conectado allí, como una línea de JSON: exactamente lo que la build entrega al plugin, con cada valor que la build le oculta también oculto aquí. Para annotation-transform, label-transform e ir-verdict, el archivo es el documento input que lee una política en ese rol. Para render-verdict, el motor de políticas remodela el payload antes de que una política lo lea — los documents de cada artefacto se analizan a partir de él —, así que una política render-verdict en un motor integrado se prueba en una build, conectada de forma que informe en warn o info; para un plugin cuyo .wasm compilaste tú, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json lo ejecuta sobre ese archivo. También se escribe un rol al que no hay nada conectado, como el payload que recibiría una conexión sin fuentes ni ajustes, de modo que una política puede escribirse antes de conectarse. Cada rol se escribe en <role>.json (annotation-transform, label-transform, ir-verdict, render-verdict); donde las conexiones de un mismo rol reciben payloads distintos — una lleva sus propias fuentes o ajustes, o una transformación cambia lo que lee la siguiente —, cada una se escribe en su lugar en <role>.<position>.<plugin>.json, donde position cuenta las conexiones de ese rol desde 1 en el orden en que las enumera la configuración del workspace y plugin es el último segmento de la referencia del plugin sin su versión, con el escape de todo carácter que un nombre de archivo no puede contener. Los archivos con esos nombres que ya estén en el directorio se reemplazan y no se toca nada más allí. Los archivos se escriben tanto si la build termina como si se detiene, y una build que se detiene antes de que se ejecute un rol nombra cada rol para el que no escribió ningún archivo. Pedirlos no cambia ningún artefacto ni ningún veredicto. Se combina con —dry-run, que entonces escribe estos archivos y nada más: el directorio de salida y el lockfile quedan intactos |
--progress | false | Fuerza la visualización del progreso de la compilación incluso cuando stderr no es un 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 un terminal que interpreta secuencias de escape, un terminal que no las interpreta recibe las mismas líneas simples, y la salida redirigida o canalizada no recibe ninguna. —quiet y —debug prevalecen ambos sobre —progress |
--quiet | false | Silencia la visualización del progreso de la compilación 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 |
--trace | false | escribe archivos intermedios por nodo en .trace/ bajo la raíz del workspace, junto a dist/, para la inspección post mortem |
--trace-unredacted | false | Escribe los valores declarados sensibles en los archivos .trace/ en lugar del texto |
--unredacted | false | Imprime los valores que un autor declaró sensibles en lugar de ocultarlos. Todo lo que alcanza la salida — un terminal, una tubería, un archivo, una grabación de pantalla — contiene entonces esos valores en claro. Alcanza el grafo que escribe —ir-graph y nada más, por lo que requiere —ir-graph; los archivos .trace/ usan —trace-unredacted en su lugar |
--upgrade | false | Convierte el paso de auto-pull en una actualización completa: descarta el lockfile existente y vuelve a resolver cada dependencia a partir del estado actual del registro, llevando cada una a la versión más alta disponible en lugar de respetar los pines existentes. Implica —auto-pull — por sí solo ejecuta un pull de actualización completa antes de la compilación. No admite un destino, por lo que no se puede restringir a una sola dependencia: para adoptar o eliminar un solo pin, ejecuta en su lugar aggrega pull —upgrade —release |
--verify-determinism | false | Renderiza cada nodo dos veces y compara los bytes emitidos, deteniendo la compilación si las dos renderizaciones de algún nodo difieren. Desactivado de forma predeterminada. Úsalo para confirmar que un provider renderiza de forma determinista — una entrada idéntica produce una salida idéntica byte a byte —, algo en lo que se basan las garantías de diff de GitOps y de salida idéntica byte a byte |
--yes | false | Responde de antemano a la confirmación de —upgrade, para uso no interactivo. Alcanza esa única solicitud y nada más: una compilación que no actualiza no pregunta nada, por lo que pasarlo ahí no cambia ningún comportamiento |