aggrega inspect
aggrega inspect genera una vista legible de cualquier entidad de Aggrega — un Component de catálogo, un archivo de entidad escrito, una entidad publicada en un registro o una Release completamente resuelta. Es la superficie de depuración canónica para entender lo que producirá el compilador: qué Components extienden qué bases, qué Recipe corresponde a cada tipo, qué Features se vinculan a cada nodo y de dónde provienen exactamente las contribuciones de cada Feature.
Cada tipo de entidad tiene una vista natural de «contrato». inspect muestra ese contrato — el esquema que publica un Component, las asignaciones que declara un Manifest, la topología que construye un Aggregate, las vinculaciones de Feature por nodo a las que se resuelve una Release. El material de tutorial y conceptual está en otro lugar; inspect responde a «¿a qué se resuelve realmente esta entidad?»
Un único argumento posicional se enruta según la forma de su contenido; no hace falta ningún subcomando. El comando despacha según la siguiente heurística:
| Forma del identificador | Despacho | Salida |
|---|---|---|
Empieza por ./, ../ o /, o termina en .yaml / .yml | Rama de archivo | Inspección por archivo según la cabecera kind: del archivo. |
Empieza por oci:// | Rama de registro | La entidad publicada en esa coordenada, leída de su registro y presentada con la vista que recibe un archivo de su tipo. Consulta Leer una entidad publicada. |
| Cualquier otra cosa | Rama de catálogo | Buscar el identificador en la pila de búsqueda del catálogo en todos los tipos de entidad; resolver las cadenas extends:; presentar la vista propia del tipo encontrado. |
Tres niveles de detalle
--list, el nivel predeterminado y --detail forman una disciplina uniforme de verbosidad en tres niveles que respeta cada tipo. --list y --detail son mutuamente excluyentes — pasar ambos se rechaza en lugar de resolverse en silencio.
--list— solo identificadores. Un Component enumera su nombre y los nombres de sus sockets uses; una MappingLibrary enumera los nombres de sus asignaciones; un Aggregate enumera los nombres de sus componentes con sus tipos.- predeterminado — una vista general estructurada pensada para el uso interactivo. Empieza con la identidad de la entidad y, para todos los tipos salvo un Manifest y una Release, con su descripción cuando la entidad escribe una; una entidad sin descripción no imprime ninguna en lugar de imprimir una línea vacía. El resto de la forma depende del tipo: un Component muestra su esquema y sus sockets; un Aggregate muestra los componentes, sus valores y aristas con las vinculaciones que lleva cada conexión, y el grafo de dependencias; una Release muestra el árbol de nodos por boundary con las vinculaciones de Feature, cada una de las escritas sobre una conexión listada bajo esa conexión.
--detail— cuerpos completos de los campos. Todo lo que contiene el tipo: un Component añade sus mecanismos de autoinyección, las Features requeridas y las etiquetas; una MappingLibrary expande el cuerpo completo de la plantilla de cada asignación; una Recipe añade el cuerpo de su workload, provides y las aserciones.
Algunos tipos usan los niveles para mostrar progresivamente más de un cuerpo escrito. Una MappingLibrary con --list muestra los nombres de las asignaciones; en el nivel predeterminado añade el ejemplo de uso sintetizado de cada asignación; con --detail expande el cuerpo completo de la plantilla.
Resolución: --raw y --resolved
Cada tipo tiene una profundidad de resolución predeterminada natural (consulta la tabla siguiente). --raw y --resolved son anulaciones siempre disponibles, y son mutuamente excluyentes — pasar ambas se rechaza en lugar de resolverse en silencio:
--rawdesactiva toda resolución — la entidad se emite tal como se escribió, directamente desde el archivo.--resolvedactiva la profundidad de resolución completa del tipo.
Para los tipos que por defecto se muestran tal como se escribieron, --raw no tiene efecto y --resolved activa la resolución que admite el tipo. Para los tipos que por defecto se resuelven, --raw es el desvío hacia la forma escrita.
--raw reproduce el archivo, así que un valor que un autor declaró sensible aparece en él exactamente como se escribió. Ese es el contrato, no una carencia — una vista tal como se escribió que ocultara en silencio parte de sí misma no sería tal como se escribió. Trata la salida de --raw como tratas el archivo de entidad del que procede. --output yaml reproduce el archivo de la misma manera, para cada tipo, incluida una Release.
Una Release responde a dos preguntas más, y cada una es un documento distinto con su propio flag. El grafo compilado al que se resuelve una Release es --ir-graph; su clausura de dependencias es --closure. Consulta Salida legible por máquina y La clausura de dependencias: --closure más abajo.
Valores predeterminados por tipo
inspect conoce los tipos inspeccionables de forma independiente de la tabla siguiente. Los tipos de catálogo se presentan por defecto tal como se escribieron — sus archivos son contratos autocontenidos. Los tipos de instancia usan por defecto una vista resuelta, porque su YAML escrito es solo el punto de partida de una cascada o de una pipeline.
| Tipo | Predeterminado | Qué significa «resuelto» |
|---|---|---|
| Component | tal como se escribió | El archivo es un contrato autocontenido; la resolución se hace frente a un enlace del Manifest, que se muestra mediante --show-implements. |
| Feature | tal como se escribió | Igual que Component. |
| Recipe | tal como se escribió | --show-implements resuelve la referencia al Component en spec.implements. |
| FeatureRecipe | tal como se escribió | --show-implements resuelve la referencia a la Feature en spec.implements. |
| MappingLibrary | tal como se escribió | Las entradas son cadenas opacas de plantilla de Go; la generación ocurre en el momento del consumo. |
| SchemaLibrary | tal como se escribió | Las entradas son definiciones reutilizables de esquemas y plantillas que se resuelven en el momento del consumo. |
| WorkloadLibrary | tal como se escribió | Las entradas son cuerpos de Workload reutilizables que importa una Recipe, evaluados en el momento del consumo. |
| ArtifactLibrary | tal como se escribió | Las entradas son paquetes de artefactos reutilizables que importa una Recipe, renderizados en el momento del consumo. |
| Plugin | tal como se escribió | El archivo es un contrato de plugin autocontenido: tipos de socket, capacidades por exportación, restricciones de ejecución y puntero a la firma. Direccionable por la ruta del archivo, o por su coordenada <pluginType>/<name> frente al catálogo. |
| Manifest | resuelto | Se aplica la cadena extends:; se presentan las asignaciones resueltas de componentes y features. |
| Aggregate | resuelto | Se construye la topología — se calculan el grafo uses y el orden. |
| Release | resuelto | Se ejecuta la pipeline completa: resolver, expandir anotaciones, ejecutar guardas, construir la topología, construir el IR. |
Un archivo cuyo kind: es Workload se rechaza: un Workload solo existe incrustado en una Recipe y no es una entidad inspeccionable de forma independiente. Inspecciona una Recipe para ver su Workload.
Profundidad de resolución por tipo
La mayoría de los tipos no tienen pipeline — inspect lee el archivo y lo presenta. Tres tipos de instancia se resuelven de forma significativa:
- Manifest aplica su cadena
extends:— siguiendo las importaciones de archivos — y presenta las asignaciones fusionadas de componentes y features.--rawmuestra el archivo tal como se escribió. - Aggregate construye su topología: se construye el grafo uses y se calcula el orden de dependencias. La vista predeterminada muestra los componentes con sus valores y aristas, seguidos del grafo de dependencias.
--rawmuestra el árbol de subsistemas tal como se escribió. - Release ejecuta toda la pipeline de compilación hasta el IR — resolver, expandir anotaciones, ejecutar guardas, construir la topología, construir el IR — y presenta el árbol de nodos por boundary con las vinculaciones de Feature de cada nodo y su procedencia. Las vinculaciones de gobernanza que dan forma al grafo se ejecutan en esa pipeline en lugar de omitirse para una vista, así que lo que lees refleja lo que decidieron: las etiquetas de una vinculación
label-transformya están en su sitio antes de que se compare nada con ellas, y las anotaciones inyectadas por una vinculaciónannotation-transformse expanden en vinculaciones de Feature exactamente igual que una anotación que escribiste tú. Una vinculación cuyo plugin este comando no puede resolver lo detiene, en lugar de dejarte un grafo dibujado sin las decisiones de ese plugin. Una Release que extiende otra se dibuja, en esta vista y en--ir-graph, como la Release en la que se compone su cadenaextends:— la que lee una build de ella —, de modo que una Release que solo nombra a su Release padre muestra el Aggregate, el Manifest y los boundaries de esa Release padre bajo su propio nombre. El Manifest que nombra una Release también se compone a través de su propia cadenaextends:, extienda o no algo la Release, de modo que una vinculación cuyo mapeo hereda ese Manifest muestra la realización que usa una build.--rawemite el archivo de la Release literalmente, sin pipeline.--closureplantea una pregunta distinta sobre la misma Release y no ejecuta ninguna pipeline; consulta La clausura de dependencias:--closure.
No hay un flag de profundidad independiente; el conmutador --raw / --resolved es el único control de la resolución, superpuesto al valor predeterminado natural de cada tipo.
Comportamiento ante errores
Un archivo hermano referenciado que no se puede cargar detiene el comando de inmediato — una Release que apunta a un Aggregate que falta, una entidad de catálogo defectuosa en la pila de búsqueda. Se detiene con un mensaje claro en lugar de presentar una salida parcial, y no hay un modo continue-on-error para un fallo de carga: en cuanto un documento que necesita la resolución es ilegible, no queda nada más que resolver. Cuando la resolución de un nombre se detiene en un documento de catálogo que la carga rechaza, el mensaje indica ese rechazo una sola vez: un encabezado con la categoría y, cuando el rechazo nombra una condición, su código corto, luego el documento y luego qué tiene de incorrecto — para un documento que el esquema de su tipo rechaza, la línea y la restricción que infringe. No incluye ninguna sugerencia de mover el archivo — el catálogo lo leyó, y por eso se rechazó.
Una Release cuya composición rechazan las comprobaciones del compilador se rechaza en lugar de presentarse. Resolver una Release construye el grafo, y las comprobaciones que un build realiza sobre el grafo terminado — una arista uses: cuyo destino no satisface el selector: de su socket, una Feature vinculada a un componente que su appliesTo: no admite, y las demás — se realizan también aquí, con el diagnóstico que imprime un build de los mismos documentos. El rechazo nombra cada hallazgo en una sola ejecución en lugar de detenerse en el primero, así que una sola pasada te muestra la lista completa que corregir en lugar de su primera entrada. Eso es lo que mantiene honesto a este comando respecto a un despliegue: una vista que presentara una composición que el build rechaza daría por correcto un workspace que no lo está. Las selecciones que no resuelven nada no se ven afectadas — --raw, --output yaml y --closure reproducen o resuelven lo que escribiste sin construir un grafo.
Una Release cuyo lockfile ya no coincide con aquello a lo que se resuelve se rechaza con la detención que imprime aggrega build. Donde hay un lockfile junto a la Release, cada selección que resuelve la Release — la vista predeterminada, --resolved, --ir-graph y --closure — lo contrasta con aquello a lo que se resuelve la Release, con la comparación de deriva que una compilación ejecuta antes de renderizar. Un lockfile que ya no coincide detiene el comando con el rechazo E0130 de la compilación: cada entrada que se desvió y, después, el aggrega pull --release <release> que la corrige. No se escribe nada en la salida estándar y el comando termina con un código distinto de cero, porque una imagen trazada a partir del catálogo en su estado actual mostraría lo que ninguna compilación de esa Release renderiza. --raw y --output yaml por sí solos no leen ni el lockfile ni el catálogo, y no están sujetos a él. Una Release sin lockfile junto a ella se resuelve sobre el catálogo en su estado actual.
Un archivo cuyo kind: no se reconoce informa del tipo desconocido y del archivo del que procede. Un archivo Workload informa de que el tipo solo existe incrustado y nombra la entidad en la que se incrusta. Un identificador oci:// que no se puede leer se rechaza con la condición que nombra el motivo; Leer una entidad publicada las enumera.
Resolución del catálogo
La pila de búsqueda del catálogo se ensambla con una precedencia por capas: primero van los flags --catalog (antepuestos, en orden), luego los catalog_dirs del workspace de .aggrega-config.yaml — para una Release a la que la configuración asigna directorios propios bajo workspace.releases, los de esa Release en su lugar —, y luego el directorio catalog en la raíz del workspace, que se lee tanto si algo lo nombra como si no. Un workspace cuyo catalog_dirs está escrito como una lista vacía no lee ningún catálogo local. La pila es first-win — el primer directorio que declara una identidad de entidad es su propietario; la copia de un directorio posterior queda oculta. La rama de catálogo resuelve el identificador frente a esta pila en todos los tipos de entidad, con una precedencia fija, y presenta la primera coincidencia mediante la vista propia de ese tipo; las ramas de archivo y de release cargan de ella las entidades de catálogo referenciadas cuando hay que resolver una asignación del Manifest o un padre extends:. Un padre extends: que la pila no contiene se lee donde lo lee una compilación: de la caché de artefactos, bajo el pin que el lockfile de una Release registra para él — el de la Release indicada, o el de cada Release que contiene el workspace cuando no se indica ninguna. Así, una base publicada en un registro se resuelve aquí una vez que aggrega pull la ha obtenido y fijado, y antes de eso el comando se rechaza indicando aggrega pull --release <release>. No se obtiene nada.
Buscar un nombre en los términos de una Release
Un nombre dado por sí solo se busca en la pila propia del workspace. Añade --release <release-path> junto a él y el nombre se busca en cambio en la pila de esa Release — los directorios que la configuración del workspace asigna a esa Release, con los --catalog que haya antepuestos —, que es lo que lee un build de esa Release. Un workspace que mantiene una variante de catálogo por Release, cada una declarando la misma entidad, responde por tanto a un nombre con la variante con la que se construye esa Release:
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlUn nombre que la pila de esa Release no resuelve se rechaza, y la explicación de dónde se leen las entidades locales nombra la entrada de esa Release bajo workspace.releases, ya que esa entrada es lo que leyó la búsqueda. --release elige la pila en la que se busca un nombre, así que solo se aplica a un nombre por sí solo: una ruta de archivo y una referencia de registro se leen tal como están y lo rechazan. Un --release que nombra un archivo que no existe, o que nombra un directorio, se rechaza antes de buscar nada.
Leer una entidad publicada
aggrega inspect oci://<host>/<repository>:<tag> lee la entidad publicada en esa coordenada; @<digest> en lugar de :<tag> nombra exactamente un manifiesto. Es la forma de examinar una entidad que solo existe en un registro — el repositorio es el segmento del tipo seguido de la identidad de la entidad, como expone el §6 de Catálogo y registro, y aggrega push imprime la referencia en la que publicó, que aquí se lee con oci:// delante.
Lo que ves es la entidad tal como se publicó. Una entidad publicada con los archivos que declara — una Recipe con su chart local o su lock, un Component con un esquema que importa — se distribuye como un archivo comprimido, y la entidad se extrae de él: el documento en la raíz del archivo comprimido que declara un tipo publicable, de modo que una plantilla de chart o un fragmento de compose distribuido junto a él no se confunde con ella. Una entidad que no declara ningún archivo se distribuye como su documento sin cambios, y la entidad de un Plugin se lee de su manifiesto en lugar del ejecutable publicado con él. Después, el documento se presenta con la misma vista que recibe un archivo de ese tipo, con los mismos niveles de detalle y los mismos --raw y --output yaml. No se aplica ninguna herencia: la vista es de lo que el publicador puso en esa coordenada. Los formatos legibles terminan con lo que se leyó: la coordenada, si contenía la entidad como archivo comprimido o como el propio documento, el tipo de medio que declara su manifiesto y el digest de ese manifiesto, que vuelve a leer los mismos bytes cuando se escribe como @<digest> en lugar de :<tag>; --output yaml imprime el documento y nada después.
Lo que comprueba y lo que no. Los bytes obtenidos se comprueban frente al digest que el propio manifiesto del artefacto registra para ellos, lo que establece que son los bytes que nombra ese manifiesto. Es una comprobación frente a lo que sirvió el registro y no frente a nada registrado de antemano: no se verifica ninguna firma adjunta al artefacto, y no se informa de ninguna retirada registrada contra él. No se escribe nada — ni entrada de caché ni lockfile —, así que leer una coordenada no cambia nada de lo que resuelve un build posterior.
Accede a la red. Se contacta con el registro con las credenciales que esta máquina guarda para él, del mismo almacén que leen aggrega push y aggrega pull, y con un registro en esta máquina se contacta mediante HTTP simple. Un workspace sin conexión rechaza la lectura antes de establecer ninguna conexión.
Una lectura que no puede responder sale con un código distinto de cero y no imprime nada en la salida estándar. Cada fallo siguiente nombra su condición junto con lo que hay que hacer al respecto; un registro al que no se puede llegar en absoluto se informa con el error de red que detuvo la lectura:
| Qué ocurrió | Condición |
|---|---|
| No hay nada publicado bajo la referencia | E0137 |
| El registro rechazó la credencial, o no hay ninguna almacenada para él | E0138 |
| El workspace está sin conexión | E0125 |
| El artefacto es un archivo comprimido que no se puede extraer | E0300 |
| El archivo comprimido no contiene ningún documento de entidad en su raíz | E0298 |
| El archivo comprimido contiene más de un documento de entidad en su raíz | E0299 |
| El documento no es una entidad de un tipo que publique un registro | E0301 |
Cada código figura en la referencia de errores. Una referencia que no nombra ningún repositorio, o ni una etiqueta ni un digest, se rechaza indicando la forma que debe escribirse en su lugar. --ir-graph y --closure se rechazan antes de obtener nada, porque ningún tipo que publique un registro es una Release.
Avisos de obsolescencia y de retirada
Un publicador puede registrar un marcador contra un artefacto después de publicarlo, indicando que la versión publicada está obsoleta o retirada. Cuando la rama de catálogo resuelve una entidad, inspect informa de cualquier marcador así bajo la vista propia de la entidad — para cada tipo que resuelve por nombre, no solo para un Component.
El aviso nombra la gravedad que registró el publicador — warning, error o retracted — junto con la versión sobre la que se registró el marcador, el motivo, el reemplazo cuando se nombra uno y la fecha de emisión. Se informan las tres gravedades. Es un conjunto más amplio que el que cambia aquello a lo que se resuelve un build: una versión marcada como retracted se excluye de la selección de versiones, mientras que warning y error son consultivas y se siguen seleccionando. inspect te muestra lo que dijo un publicador; no decide lo que obtienes.
El aviso se lee del índice local del registro desde el que se resuelve la entidad, que construye aggrega registry update — así que no necesita red y funciona en un workspace sin conexión. Como el índice es una instantánea, el aviso termina indicando cuándo se tomó esa instantánea y nombra el comando que la actualiza. Un workspace sin índice construido no informa de nada, y un aviso ausente significa por tanto «nada registrado en esta instantánea» y no «nada registrado».
Un marcador solo se informa cuando su propia firma se verifica frente a los firmantes que reconoce la política de confianza del registro. Un marcador sin firmar, o uno cuya firma no se verifica, no se informa: una afirmación que no se puede autenticar no se presenta como un hecho.
El aviso acompaña a las vistas legibles por personas. Ni --output yaml ni --ir-graph añaden ninguno, así que un consumidor que analiza cualquiera de los dos recibe un documento y nada más.
Ejemplos prácticos
Búsqueda de un Component en el catálogo
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"La vista predeterminada muestra la descripción del Component cuando define una, luego el esquema resuelto (tras cualquier fusión de extends:) y los uses-sockets declarados. El Component anterior no define ninguna descripción, por eso la transcripción empieza directamente en el esquema. --detail añade los mecanismos de self-inject, las Features requeridas y las etiquetas; --list muestra solo el identificador del Component y los nombres de sus sockets.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observabilityRecipe con --show-implements
La vista predeterminada de una Recipe muestra una sección por cada modo de entrada que declara, su capacidad y su mapeo de valores. --show-implements resuelve la referencia spec.implements contra el catálogo y renderiza el Component vinculado, junto con las vinculaciones que ese Component requiere:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metricsRecipe que declara varios modos de entrada
Los modos de entrada de una Recipe se componen por adición: un source: que renderizar, un workload: que sintetizar y un mapa artifacts: aportan cada uno salida, y una Recipe puede declarar cualquier combinación de ellos. inspect informa de cada modo que declara la Recipe en lugar de elegir uno, de modo que lo que ves es el conjunto que escribiste:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlLas secciones se ordenan source: → workload: → artifacts:, el mismo orden que aplica una build cuando resuelve una Recipe a un único nombre de modo y cuando informa de qué modo declarado no puede satisfacer el provider vinculado — así, esta vista y los diagnósticos de una build nombran los modos en el mismo orden. Una Recipe que no declara ni un source: ni un workload: se informa como solo de artifacts, que es el único caso en que la vista nombra un único modo.
Manifest (resuelto de forma predeterminada)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)La vista predeterminada aplica la cadena extends: del Manifest y presenta los mapeos resueltos de componentes y funcionalidades, además de las vinculaciones de anotaciones. --raw muestra el archivo tal como se escribió, antes de la resolución de extends.
Aggregate (resuelto de forma predeterminada)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontendLa vista predeterminada construye la topología y muestra cada componente con sus valores y sus aristas uses, seguidos del grafo de dependencias calculado. El árbol de subsistemas se renderiza con anidamiento; --flat renderiza una sección por nodo, cada una identificada por su ruta completa con puntos.
Una conexión escrita en la forma larga va seguida de las vinculaciones que transporta, cada una con el nombre que adopta en el componente consumidor — el alias de la conexión y el slot unidos por un punto —, con el tipo de Feature que nombra y una cláusula que indica el slot que ocupa y si maneja material declarado sensible:
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]El slot y la marca son los hechos que una build de una Release que despliega este Aggregate registra para la vinculación, leídos de la misma manera en que los lee la vista de la Release (consulta Conexión, slot y cláusula de sensibilidad de una vinculación); proceden de la declaración del slot del socket y de la propia Feature, por lo que no dependen de qué Release despliega el Aggregate. Un Aggregate no nombra ningún Manifest, así que la realización que el Manifest de una Release elige para la vinculación no se muestra aquí. Esta vista enumera las conexiones de un componente y lo que transportan; las vinculaciones del bloque propio de un componente aparecen en la vista de la Release.
Release (resuelta de forma predeterminada)
La vista de la Release es la inspección de mayor trascendencia. Ejecuta el pipeline completo y renderiza, por cada límite, cada nodo Component, sus aristas uses y cada Feature vinculada a ese nodo — la escrita en una conexión, bajo la arista de esa conexión —, cada una con el slot de vinculación que ocupa, si maneja material declarado sensible y la FeatureRecipe que la realiza, además de un corchete de procedencia que revela de dónde procede la vinculación:
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)Cada límite lleva su directorio de salida y sus anotaciones consumidas por el provider; cada componente bajo un límite lleva su tipo de componente del Aggregate, sus aristas uses (con las aristas entre límites marcadas), cada una seguida de las vinculaciones que transporta esa conexión, y sus propias vinculaciones de Feature, cada vinculación con su cláusula de hechos y su corchete de procedencia. --flat reduce el árbol de límites a una sección por límite identificada por su ruta completa. --raw emite el archivo de la Release literalmente, sin pipeline.
Salida YAML
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}Un Component nombrado desde el catálogo se imprime como la entidad que resolvió el catálogo, de modo que tras una fusión extends: ves la entidad fusionada en lugar del archivo escrito; un archivo de Component se imprime tal como se escribió.
Salida legible por máquina
Dos flags producen salida legible por máquina, y responden a preguntas distintas. --output elige un formato para el documento que este comando ya renderiza; --ir-graph pide un documento diferente — el grafo compilado al que se resuelve una Release — además de este. Son independientes: si pasas ambos, obtienes el grafo y el YAML tal como se escribió, cada uno una vez.
--output yaml emite la entidad tal como se escribió, apta para pipes y diffs. Esa salida es literal, y eso incluye los valores que un autor declaró sensibles — una salida que afirma reproducir la entrada no puede ocultar parte de ella y seguir reproduciéndola. Canalízala, guárdala y compártela como harías con el archivo de entidad del que procede.
El grafo compilado: --ir-graph
aggrega inspect <release> --ir-graph escribe en la salida estándar, como JSON, el grafo al que se resolvió la ejecución, antes de la vista que el comando renderiza de todos modos. Un solo documento JSON, un solo salto de línea final, de modo que un consumidor que decodifica el flujo lee el grafo y se detiene.
Se aplica a una Release, que es el único tipo que se resuelve a un grafo. Si se solicita para cualquier otro tipo, o para una entidad del catálogo por nombre, el comando se niega y lo indica, en lugar de renderizar la vista propia de esa entidad y descartar silenciosamente la solicitud.
Una composición que rechazan las comprobaciones del compilador no produce ningún grafo. El rechazo descrito en Comportamiento ante errores ocurre antes de que se escriba nada en este flujo, de modo que un pipeline que lo lee nunca recibe un grafo que una build de los mismos documentos rechazaría — recibe los mismos hallazgos que informaría una build, y un código de salida distinto de cero.
El mismo flag, con el mismo significado, está en aggrega build y aggrega validate: cada uno devuelve el grafo que calculó esa ejecución, además de cualquier otra cosa que produzca ese comando. Una integración de editor lee el mismo grafo a través del protocolo del daemon.
--output yaml no emite el grafo. Reproduce la Release escrita, exactamente como hace con cualquier otro tipo. Un pipeline que quiera el grafo lo lee en su lugar de --ir-graph, y recibe JSON en lugar de YAML.
El grafo oculta. No es un archivo que alguien haya escrito — es lo que la compilación calculó a partir del Aggregate, la Release y el catálogo —, así que no hay ningún compromiso de fidelidad a lo escrito que cumplir, y las mismas declaraciones que rigen las presentaciones legibles lo rigen también. Dondequiera que el grafo lleve una hoja que un autor declaró sensible, el valor se sustituye por un objeto de una sola clave que lo indica como oculto:
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}La clave se conserva, de modo que el grafo sigue respondiendo qué hojas llevan un nodo y sus vinculaciones; solo desaparece el valor. Un hermano no declarado en la misma carga útil se emite tal como se escribió — secretName arriba es un localizador público que su autor dejó sin declarar, y se imprime. El motivo que acompaña al marcador indica por qué falta el valor: declared para una hoja que cubre una declaración, y unreadable cuando la carga útil llegó en una forma que este comando no pudo leer, en cuyo caso se oculta toda la carga útil en lugar de adivinar cualquier parte de ella.
La configuración propia de una conexión se oculta de la misma manera. Los values por conexión que un Aggregate escribe en una entrada uses y la infra por conexión que una Release escribe en una de ellas se rigen por el socket del componente consumidor — el valueSchema y el infraSchema que declara, los contratos contra los que se valida esa configuración —, nunca por las declaraciones del destino. Una hoja que cualquiera de los dos contratos declara sensitive: true se sustituye por el marcador en los values y la infra de la arista, y en la entrada uses del nodo consumidor, que lleva los valores tal como los escribió el autor; cada arista enumera las hojas que oculta en sensitive_payload_leaves, el campo que usa un nodo para las suyas. Una hoja del mismo nombre en una conexión cuyo socket la declara legible se emite tal como está escrita.
Pasa --unredacted cuando un pipeline realmente necesite los valores, y trata lo que produce como tratas los propios archivos de entidad. aggrega build y aggrega validate aceptan el mismo flag junto a --ir-graph, en los mismos términos: el grafo que devuelven oculta los valores a menos que se pase.
El protocolo del daemon entrega el mismo grafo bajo la misma regla. aggrega/irGraph responde con estos valores ocultos, y los devuelve en claro solo a una solicitud que establece su campo unredacted — la forma de este flag en el protocolo. Así, lo que dibuja un panel del editor sigue las mismas declaraciones, y un cliente que muestra los valores lo hace porque los pidió.
El cierre de dependencias: --closure
aggrega inspect <release> --closure informa del cierre de dependencias de la Release: cada entidad del catálogo que alcanza, en la versión a la que se resolvió cada una, junto con las identidades del Aggregate y del Manifest a las que se resolvieron sus dos punteros y los documentos compartidos en los que se apoyan esas entidades. No se renderiza nada ni se produce ningún artefacto — el cierre se resuelve, no se construye, así que no se carga ningún provider para responderlo.
El cierre y la vista resuelta son documentos distintos, y ninguno puede recuperarse a partir del otro. La vista resuelta — lo que este comando renderiza de forma predeterminada para una Release — dice cómo es el despliegue: sus límites, sus nodos de componente, qué está conectado con qué y qué está vinculado a cada nodo. El cierre dice qué se incorporó para construirlo, y en qué versiones. Una entidad puede alcanzarse sin aparecer nunca como nodo — la Recipe a la que un Manifest mapea un tipo de componente la alcanza cada build y no es un nodo en ninguna de ellas —, y un nodo registra el tipo de componente con el que se declaró, no la versión a la que se resolvió ese tipo. Así que un lector que pregunta «¿por qué cambió esta versión?», «¿qué afectaría cambiar este documento compartido?» o «¿de qué depende realmente este despliegue?» está pidiendo el cierre, y un lector que tiene la vista resuelta no lo obtiene leyéndola con más atención.
La misma palabra pide el mismo documento en cada superficie. --closure aquí, aggrega/releaseClosure a través del protocolo del daemon (consulta aggrega serve, «Un cierre no es el grafo») y el modo release de la herramienta describe a través del protocolo de herramientas del asistente responden todos a esta pregunta sobre una Release; un nombre de Release en cualquiera de ellos llega a la misma resolución, de modo que los tres no pueden llegar a discrepar sobre aquello de lo que depende una Release. Sobre un lockfile que ya no coincide con aquello a lo que se resuelve la Release, este comando y la herramienta describe rechazan con la detención por deriva de la compilación; el daemon, que sirve a un editor mientras este edita, responde.
Es un solo documento, así que se pide por sí solo. --closure selecciona el cierre en lugar de la vista resuelta, y no puede combinarse con --raw, --resolved, --output ni --ir-graph — cada uno de ellos pide un documento distinto sobre la misma Release, y un comando que aceptara dos solicitudes tendría que responder silenciosamente solo a una. La combinación se rechaza, nombrando el par.
Se aplica a una Release y a nada más. Una entidad del catálogo, un archivo de Aggregate, un Manifest — ninguno de ellos resuelve un cierre, así que la solicitud se rechaza en lugar de responderse renderizando la vista propia de ese sujeto y descartándola. Una solicitud descartada se ve para quien la hace exactamente igual que un sujeto cuyo cierre está vacío.
Cada resultado se diferencia de los demás. A una Release que se resuelve se le responde con el listado. Una ruta de Release que no nombra ningún archivo se rechaza, indicando que el archivo no está. Una Release que está y cuyo cierre no puede resolverse se rechaza indicando qué no pudo resolverse y de dónde procedía la referencia, seguido de los archivos que rechazó la carga del catálogo — porque un archivo rechazado es la razón habitual por la que falta una entidad que alcanza la Release. Un registro de confianza de plugins junto a la Release que está y no puede leerse se rechaza indicando qué no pudo leerse, porque un listado que lo hubiera pasado por alto no informaría de ningún plugin retirado donde no pudo comprobarse ninguno. Una Release cuyo lockfile ya no coincide con aquello a lo que se resuelve se rechaza con la detención por deriva que imprime una compilación, como describe Comportamiento ante errores, porque las versiones listadas serían versiones que no usa ninguna compilación de esa Release. Un listado vacío nunca es la respuesta a ninguno de ellos: presentaría una ruta mal escrita, o un workspace roto, como una Release que no depende de nada.
Los tres niveles de detalle se aplican como en cualquier tipo. --list imprime solo las referencias, una por línea, para canalizarlas. El nivel predeterminado añade las identidades resueltas, la versión a la que se resolvió cada referencia, los documentos compartidos utilizados, cualquier mapeo del Manifest cuyo destino no implemente el tipo al que está mapeado y cualquier aviso de obsolescencia o retirada registrado sobre aquello de lo que depende la Release — en su lockfile, contra una referencia fijada, y en el registro de confianza de plugins junto a ella, contra un plugin vinculado en un rol que devuelve un veredicto de aceptación o rechazo — con las palabras que imprime aggrega build para el mismo marcador. --detail añade el tipo de cada referencia cuando el punto de la referencia registró uno — algunas posiciones de un documento dicen a qué tipo apuntan y otras no, así que se informa donde se conoce en lugar de deducirlo de la forma del nombre.
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)Cuando un workspace ha registrado a qué versiones se resuelve una Release, ese registro sirve de punto de partida para la resolución, de modo que las versiones informadas son aquellas con las que se construye este despliegue y no lo que el catálogo contenga hoy. Un workspace sin ese registro resuelve sobre el catálogo tal como está.
Conexión, slot y cláusula de sensibilidad de una vinculación
Cada vinculación de Feature en la vista de la Release lleva una cláusula que nombra los hechos que el compilador registra sobre la propia vinculación: qué slot de vinculación ocupa, si maneja material declarado sensible y la FeatureRecipe que la realiza — y, para una vinculación escrita en una de las conexiones del componente, la conexión en la que se escribió. La cláusula se sitúa entre el nombre de la vinculación y su corchete de procedencia, y se lee de forma idéntica en las dos formas de procedencia descritas a continuación.
Una vinculación escrita en una conexión se enumera bajo la línea de esa conexión en Uses:, no bajo Features:, de modo que Features: contiene solo las vinculaciones propias del componente. La línea superior nombra la conexión por su alias y el componente al que llega, y su propia cláusula dice el resto:
[socket: <socket>]— el socket a través del cual se conecta la conexión, que la línea de la conexión no nombra. Encabeza la cláusula porque cambia cómo se lee el resto: la mitad del slot que sigue nombra un slot que declara el socket de la conexión, no uno que el componente declara para sus propias vinculaciones.[connection: <alias> through socket <socket>]— el mismo hecho para una vinculación cuya conexión no tiene ninguna línea en el bloqueUses:, que entonces se enumera bajoFeatures:y nombra aquí su conexión. En ambos casos, una conexión se nombra una vez por vinculación, nunca dos.[slot: <name>]— la vinculación ocupa el slot llamado<name>. Un slot se ocupa vinculando una Feature con el nombre propio del slot, de modo que<name>es el nombre con el que se escribió la vinculación, comparado con los slots declarados: elfeaturesSchemadel Component anfitrión para una de sus propias vinculaciones, y elfeaturesSchemaque declara el socket de la conexión para una vinculación escrita en una conexión.[free]— la vinculación no ocupa ningún slot declarado: el Component resuelto no declara ningún slotfeaturesSchemacon ese nombre. Esto es un hallazgo, no un diagnóstico. Se acepta una vinculación de forma libre, y un operador que quiera prohibirla lo expresa como una política de gobernanza en lugar de confiar en que la herramienta la rechace.[sensitive]— la vinculación maneja material que un autor declaró sensible, porque la Feature vinculada declara una hoja sensible, porque el slot que ocupa declarasensitive: true, o por ambas razones.[realization: <name>:<version>]— la FeatureRecipe que el Manifest de la Release vincula para la vinculación: por el nombre propio de la vinculación cuando el Manifest mapea ese nombre — para una vinculación escrita en una conexión, el alias y el slot unidos por un punto —, y si no, por su tipo de Feature. Es la realización con la que una build de los mismos documentos renderiza la vinculación, y el mismo valor que el grafo compilado lleva en la vinculación comorealization(consulta--ir-graph), de modo que esta vista y el grafo no pueden nombrar realizaciones distintas. Va en último lugar en la cláusula.
Cuando se aplican varios hechos, comparten una cláusula. core/storage/s3-object-store declara un slot secret_access_key marcado con sensitive: true, de modo que una credencial vinculada con ese nombre informa de ambos hechos, mientras que una Feature vinculada con un nombre para el que el Component no declara ningún slot no informa ni de slot ni de sensibilidad. Con un Manifest que mapea cada tipo de Feature a una FeatureRecipe, cada línea nombra también su realización:
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]Un componente cuyo socket models declara un slot credential marcado con sensitive: true, y que conecta con el alias gpt una conexión que lo ocupa, enumera esa vinculación bajo la conexión — junto a una credencial propia, que permanece bajo Features::
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]Una vinculación escrita en una conexión nunca informa de [free]: un socket admite solo los slots que declara, y una conexión que lleva cualquier otro nombre se rechaza cuando se carga la build.
La cláusula se omite por completo cuando no se aplica ninguno de los hechos, y cada mitad se omite de forma independiente:
- Sin mitad de socket o de conexión significa que la vinculación se escribió en el bloque propio del componente, o llegó a él desde un ámbito más amplio o mediante expansión basada en anotaciones.
- Sin mitad de slot significa que no pudo resolverse el conjunto de slots declarados del Component anfitrión — por ejemplo, su tipo no coincide con ninguna entidad del catálogo. Esto es deliberadamente distinto de
[free]:[free]responde «no hay declarado ningún slot con ese nombre», mientras que una mitad ausente significa que la pregunta no pudo responderse en absoluto. - Sin
sensitiveregistra que ninguna declaración marcó la vinculación. Eso es más restringido que un veredicto de que la vinculación no transporta nada secreto; el eje informa de declaraciones, y no se infiere nada del nombre de un campo ni de su valor. - Sin mitad de realización significa que el Manifest no vincula la vinculación a ninguna FeatureRecipe que contenga el catálogo.
Un slot cuyo nombre declarado es literalmente free también se renderiza como [free], indistinguible de una vinculación de forma libre — nada reserva esa palabra frente al espacio de nombres de los slots.
Gramática del corchete de procedencia de la IR
Cada vinculación de Feature en la vista de la Release lleva un corchete de procedencia. El corchete puede adoptar una forma compacta (un corchete por Feature cuando la procedencia de la vinculación es uniforme en todas las hojas) o una forma por hoja (un corchete por hoja cuando las hojas de la vinculación proceden de fuentes heterogéneas). Existen tres cuerpos de corchete; se aplican de forma idéntica a ambas formas.
Los tres cuerpos de corchete
-
[explicit]— la vinculación de Feature está declarada por el autor. El Aggregate o la Release nombró explícitamente la Feature en el nodo afectado. Las vinculaciones explícitas son la fuente de mayor prioridad; siempre prevalecen sobre las contribuciones basadas en anotaciones en la misma hoja. -
[annotation: <key> from <source>]— la vinculación de Feature está basada en anotaciones. El compilador la sintetizó porque una anotación en<source>coincidió con una vinculación del Manifest que declara esta Feature.<key>es la clave de anotación que activó la vinculación (p. ej.,business.aggrega.ai/team);<source>es la entidad que llevaba la anotación (aggregate,release,componentomanifest). La vinculación sintetizada es estructuralmente idéntica a una explícita — el renderizado posterior trata ambas de la misma manera —, pero el corchete de procedencia las distingue para que la depuración siga siendo decidible. -
[explicit; overrides annotation: <key> from <source>]— una forma por hoja que se activa cuando una declaración explícita del autor en una hoja suprime una contribución de anotación que, de otro modo, habría establecido la misma hoja. La composición entre lados produce este caso: una anotación del Aggregate podría aportar el pilarvalues:de una Feature, una anotación de la Release aporta su pilarinfra:, y una declaración explícita de la Release en la misma Feature sobrescribe una hoja de infra. El corchete de la hoja registra tanto el autor explícito como la anotación suprimida; la anotación suprimida no contribuye a la salida renderizada, pero su presencia aparece en la vista de inspect para que el operador pueda ver qué anotación se sobrescribió y dónde.
Forma compacta frente a forma por hoja
El compilador elige entre el renderizado compacto y el renderizado por hoja recorriendo la procedencia por hoja de la vinculación y comprobando su uniformidad. La procedencia de una vinculación es uniforme cuando cada hoja poblada (en los pilares values: e infra: de la Feature) comparte el mismo origen (explícito o anotación), la misma clave de anotación cuando está basada en anotaciones, la misma entidad de origen, y ninguna hoja lleva un marcador «overrides annotation». Cuando la procedencia es uniforme, el compilador emite un corchete por vinculación:
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]Cuando la procedencia diverge — un caso típico es la composición entre lados, en la que una anotación del Aggregate aporta values: y una anotación de la Release aporta infra: en la misma Feature —, el compilador emite un corchete por cada hoja poblada:
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]El orden del recorrido es primero el pilar values (en el orden del autor) y después el pilar infra (con la misma disciplina). El prefijo del pilar (values. / infra.) y la ruta con puntos dentro del pilar indican exactamente qué hoja anota cada corchete.
Valores declarados sensibles
Una hoja cuyo esquema declara sensitive: true imprime el texto fijo <redacted> en lugar de su valor. La clave, el prefijo del pilar y el corchete de procedencia se conservan todos — solo se sustituye el valor —, de modo que la presentación sigue respondiendo qué hojas lleva una entidad y de dónde procede cada una. Se ven afectadas dos superficies legibles: el bloque Values: por nodo de un Aggregate y el bloque de vinculaciones por hoja de una Release resuelta — incluida una vinculación escrita en una conexión, impresa bajo la línea de esa conexión, que oculta exactamente las hojas que la misma Feature oculta cuando la tiene el propio componente. El grafo compilado de una Release con --ir-graph oculta las mismas hojas en la forma estructurada descrita en Salida legible por máquina.
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>Solo se oculta una hoja declarada, y la cláusula [sensitive] a nivel de vinculación no es una instrucción de ocultación: dice que la vinculación maneja material secreto, no cuáles de sus hojas lo llevan. Los localizadores publicados de una Feature de credencial — el nombre del recurso y la clave de datos — son públicos y se dejan deliberadamente sin declarar en el catálogo de la biblioteca estándar, de modo que se imprimen en claro junto al material que no lo es:
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]No se infiere nada del nombre de un campo: un campo llamado password que no lleva ninguna declaración imprime su valor, y un campo declarado llamado key no. La ocultación cubre lo que imprime la herramienta; nunca llega a un artefacto renderizado, y dist/ se emite exactamente como lo produjo el renderizado. La palabra clave y el límite completo de lo que consigue declararla están en vocabulary/compact-form-authoring.md, «Declarar una hoja sensible».
Mostrar los valores ocultos
--unredacted imprime los valores declarados sensibles en lugar de ocultarlos, en todas las superficies de inspect a la vez — tanto las presentaciones legibles anteriores como el grafo compilado de una Release. Existe porque el valor oculto es a veces justo el que se está investigando: una credencial que llega desde la vinculación equivocada parece idéntica a la correcta cuando ambas aparecen como ocultas.
Su alcance es el comando al que se pasa. aggrega build y aggrega validate también lo aceptan, donde llega al grafo que devuelve --ir-graph y a nada más, y lo rechazan cuando no se pidió ningún grafo. aggrega build --trace-unredacted es la misma idea aplicada a los archivos de traza de la build, y ninguno de los dos flags de la build llega a la salida del otro; un artefacto renderizado bajo dist/ no se ve afectado por ninguno de ellos, porque se emite exactamente como lo produjo el renderizado, se pase lo que se pase.
Todo lo que alcance la salida llevará entonces esos valores en claro — un terminal, un pipe, un archivo, una grabación de pantalla, un informe de error pegado. A diferencia de los archivos de traza, que se abren cada uno con una cabecera que indica que se capturaron sin ocultación, la salida en un terminal no lleva ninguna marca de ese tipo: solo la línea de comandos indica que se pasó.
Cuándo recurrir a inspect
- Depurar «¿por qué está aquí esta Feature?» — las vinculaciones basadas en anotaciones son invisibles en los archivos YAML del Aggregate y de la Release (las anotaciones están ahí, pero las vinculaciones de Feature que sintetizan existen solo en la IR). Inspect las muestra con su procedencia.
- Verificar la herencia de esquemas —
aggrega inspect <ComponentName>muestra el esquema fusionado después de que se resuelva la cadenaextends:; el archivo escrito, por sí solo, muestra únicamente el delta local. - Diagnosticar sorpresas de la composición entre lados — cuando una anotación del Aggregate y una anotación de la Release aportan ambas cargas útiles de pilar en la misma Feature, puede resultar confuso reconstruir mentalmente las hojas resueltas. La forma de corchete por hoja hace explícita la resolución.
- Comprobación de verificación previa al despliegue —
aggrega inspect ./prod-release.yamlenumera cada Feature en cada Component antes de queaggrega buildproduzca artefactos; el operador puede confirmar que la topología coincide con la intención antes de hacer commit de los manifiestos renderizados en GitOps.
Para la mecánica subyacente — cómo se propagan en cascada las anotaciones, cómo la partición entre lado y pilar encamina los valores de las anotaciones hacia los pilares de la Feature y cómo la disciplina de que prevalece la vinculación explícita interactúa con las contribuciones basadas en anotaciones —, consulta providers/well-known-annotations.md y entities/manifest.md, «Vinculaciones de Feature basadas en anotaciones».
Sinopsis
aggrega inspect [identifier] [flags]Descripción
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.Flags
| Flag | Predeterminado | Descripció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. |
--closure | false | Informa del cierre de dependencias de la Release — cada entidad del catálogo que alcanza, en la versión a la que se resolvió cada una — en lugar de la vista de nodos resueltos. Se aplica a una Release, que es el único tipo que resuelve un cierre; cualquier otro tipo rechaza la solicitud en lugar de descartarla silenciosamente. |
--color | auto | Colorear la salida: auto|always|never. |
--detail | false | Renderizar los cuerpos completos de los campos. |
--flat | false | Renderizar una entidad con forma de árbol (Aggregate, Release) como una lista plana, con cada nodo precedido de su ruta completa con puntos. Sin efecto en los tipos tabulares. |
--ir-graph | false | Escribir también 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. Se aplica a una Release, el único tipo que se resuelve a un grafo; cualquier otro tipo rechaza la solicitud en lugar de descartarla silenciosamente |
--list | false | Renderizar solo los identificadores. |
--no-color | false | Desactivar la salida coloreada (alias de —color=never). |
--output, -o | text | Formato de salida: text|yaml. |
--plugin | — | Ruta del sistema de archivos a un artefacto <file.wasm> sin procesar; deriva e imprime las funciones del host que importa, antes de que aggrega plugin sync las registre en una entidad Plugin. No acepta ningún argumento de identificador. |
--raw | false | Renderizar la entidad tal como se escribió, sin resolución. |
--release | — | Buscar un nombre del catálogo en los términos de este archivo de Release: a través de los directorios de catálogo que la configuración del workspace asigna a esa Release, con —catalog antepuesto. Se aplica a un nombre; un archivo o una referencia de registry se inspecciona tal como está y lo rechaza. 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 está en ningún workspace y no se indica ninguna raíz, una ruta absoluta encuentra el workspace a partir de la propia carpeta de la Release |
--resolved | false | Renderizar la entidad completamente resuelta. |
--show-implements | false | Para una Recipe o FeatureRecipe, resolver spec.implements contra el catálogo y renderizar el Component o la Feature vinculados. |
--unredacted | false | Imprimir los valores que un autor declaró sensibles en lugar de ocultarlos. Todo lo que alcance la salida — un terminal, un pipe, un archivo, una grabación de pantalla — llevará entonces esos valores en claro. |