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

Estado del lenguaje

Esta página es la referencia canónica sobre qué superficies de Aggrega se pueden usar hoy, cuáles están documentadas pero el compilador aún no actúa sobre ellas y cuáles están planificadas para una iteración futura. Complementa los capítulos por dominio al mostrar en un solo lugar el estado de madurez de todo el lenguaje.

Dos tipos de lectores consultan esta página. Los autores primerizos revisan la página antes de escribir sobre una superficie que no conocen, para confirmar que la superficie produce hoy una salida renderizada. Quienes buscan una referencia revisan la página cuando una superficie que usan se comporta de forma inesperada — por ejemplo, cuando el YAML pasa la validación pero no se produce ninguna salida, la página es el primer lugar donde consultar el estado de la superficie. Los lectores que vuelven también consultan la página para identificar las superficies que han cambiado de etiqueta de estado desde su última lectura. Los capítulos por dominio y las referencias de entidades describen cómo debe funcionar la superficie; esta página describe si ya funciona.

Taxonomía de estados

Cada superficie del lenguaje en esta página lleva una de cuatro etiquetas de estado:

  • disponible. El esquema acepta la superficie; el compilador la consume; el comportamiento coincide con el contrato documentado. Los autores que usan una superficie available reciben el contrato documentado.

  • aceptada pero inerte. El esquema acepta la superficie — escribir sobre ella pasa la validación —, pero el compilador aún no actúa sobre ella. Escribir una superficie accepted but inert produce un build sintácticamente válido sin ningún efecto renderizado para esa superficie; el compilador puede emitir una advertencia que nombra la superficie inerte (el patrón recomendado), o algunas superficies actuales se omiten en silencio sin advertencia. Las entradas por sección de más abajo indican el comportamiento concreto.

  • aceptada pero bloqueada. El esquema acepta la superficie — escribir sobre ella pasa la validación —, pero el compilador detiene el build en lugar de renderizarla. Escribir sobre una superficie accepted but blocked falla al renderizar con un error explícito que indica qué escribir en su lugar. Un bloqueo puede ser permanente, cuando lo que se escribió es una ambigüedad que el compilador no resolverá en tu nombre, porque elegir una interpretación por ti podría entregar algo que no pediste; o puede mantenerse solo hasta que se publique el comportamiento que hay detrás de la superficie. Lo que promete la etiqueta es lo mismo en ambos casos: el esquema la acepta, el build la rechaza y el error te dice cómo corregirlo.

  • planificada. La superficie está documentada tal como se diseñó, pero ni el esquema ni el compilador la aceptan todavía. Escribir sobre una superficie planned falla en la validación del esquema. La página muestra los elementos planificados para que los autores puedan planificar teniendo en cuenta su ausencia en lugar de descubrir la carencia en el momento del build.

Las etiquetas de estado se evalúan respecto al compilador actual. Las superficies en desarrollo activo pueden pasar de una etiqueta a otra; las entradas por sección describen el plan de transición cuando se conoce.

Tipos de entrada de la Recipe

Una Recipe compone su salida a partir de tres tipos de entrada — desde origen, sintetizado y artefactos — descritos en 16-recipe-input-composition.md. Estado por tipo de entrada:

  • source: + valuesMapping: (desde origen) — disponible. El compilador resuelve la URI source:, evalúa la plantilla valuesMapping (en línea, $import: de archivo o $import: de biblioteca) y entrega el resultado al provider de destino para su renderizado. Lo consumen los providers helm, helm-chart, compose, terraform y cloudformation.

  • workload: (sintetizado) — disponible. La Recipe declara workload: en línea (un escalar de bloque que contiene el YAML del Workload) o mediante $import: (ruta de archivo). El compilador analiza el Workload con plantillas, lo valida contra el esquema Workload integrado y lo despacha al sintetizador de workloads del provider de destino. Lo consumen los providers helm y compose. El provider helm-chart redirige explícitamente a los autores al provider helm para los manifests de K8s sintetizados. Una Recipe que declara workload: para un provider que no implementa la síntesis de workloads se detiene al renderizar con un CATALOG_ERROR.

  • artifacts: (artefactos) — disponible. El campo es un mapa de entradas con nombre; cada entrada se escribe en línea o se carga mediante un $import: por entrada. Las entradas se evalúan después de analizar el Workload y resolver el origen, de modo que el contexto de plantillas completo — incluidos .workload y .source — está a su disposición; reciben la procedencia fusionada en metadata.labels y metadata.annotations para los documentos que llevan metadatos (las claves no seguras para el juego de caracteres — recipe-uri, boundary-path, sync-wave — como anotaciones, la misma división que aplican los providers helm), y se emiten como archivos separados junto a la salida de la Recipe renderizada desde el origen o sintetizada desde el workload. Despacho por Provider — el provider helm plano emite archivos independientes en un directorio con el nombre del componente que los declaró, dentro del directorio de salida del boundary, porque la clave da nombre al archivo y no dice nada sobre qué componente lo escribió; el provider compose encamina sus emisiones a través del fusionador de fin de Release; el provider helm-chart evalúa cada entrada con los delimitadores de Aggrega [[ ]] para que la sintaxis {{ }} de Helm en el mismo archivo sobreviva hasta el renderizado posterior, y luego coloca cada entrada según su forma escrita — una entrada cargada con $import: en boundaries/<bp>/charts/<nodeID>/templates/<authored-key> (los archivos de un bundle anidados bajo esa clave), junto a las plantillas propias del chart desde origen, y una entrada de contenido en línea en boundaries/<bp>/charts/<nodeID>/<authored-key>, la raíz del chart, donde las plantillas propias del chart la leen mediante .Files.Get / .Files.Glob; el provider terraform escribe cada entrada tal cual en el directorio propio del componente bajo el árbol modules/ del boundary; el provider cloudformation fusiona cada entrada, un fragmento de stack, en el único stack ensamblado para ese directorio de salida. Las colisiones de nombres de archivo entre orígenes de distintos tipos de entrada (salida renderizada desde el origen, sintetizada desde el workload o emitida como artefacto) las detecta en tiempo de renderizado el detector de colisiones entre orígenes y producen un CATALOG_ERROR que nombra a cada contribuyente.

Consulta entities/recipe.md para la superficie de autoría de la Recipe y las reglas de composición de tipos de entrada; errors/fatal-halts.md para las reglas de forma de la Recipe; y la sección Providers más abajo para la matriz por provider.

Lenguajes de mapping

Las Recipes (y las FeatureRecipes) se vinculan a un único campo de mapping para traducir el contexto de Aggrega al diccionario de valores que consume el provider subyacente. El campo valuesMapping: admite tres modos de autoría, que se eligen según la forma del contenido:

  • valuesMapping: — Modos 1-3 disponibles. Modo 1: plantilla Go en línea (escalar de bloque). Modo 2: $import: de archivo (un mapa que contiene solo $import: con una ruta de archivo local). Modo 3: $import: de biblioteca (un mapa que contiene solo $import: con una referencia de identidad por nombre simple a una entrada de una MappingLibrary, <Library>#/mappings/<entry>, opcionalmente con un mínimo :<version>). El compilador elige según la forma del contenido — escalar de bloque para el Modo 1, $import: con una ruta de archivo para el Modo 2, $import: con una referencia de biblioteca por nombre simple para el Modo 3. Los tres evalúan la plantilla Go resuelta contra el contexto de plantillas de la Recipe durante el mapping de valores (la biblioteca de helpers Sprig está prerregistrada); el Modo 3 resuelve la entrada contra el catálogo local más cualquier biblioteca fijada en el lockfile, y una referencia que incluye un host se rechaza. Consulta entities/recipe.md «El campo valuesMapping — tres modos de autoría» para el mecanismo de despacho y ejemplos completos.

Consulta entities/recipe.md para la superficie de autoría de la Recipe y el diseño del lenguaje de mapping, y entities/mappinglibrary.md para la entidad de biblioteca en la que se basa el Modo 3.

Sintaxis de inject

El bloque inject: tiene una única sintaxis en cada ubicación — el inject propio de un componente, el de una conexión uses y el de un adjunto.

  • Una lista de entradas por mecanismo ([{in: ..., from: ...}], [{in: ..., value: ...}]) — disponible. Cada mecanismo de entrega es una lista; cada entrada nombra su identificador local (nombre de variable de entorno, ruta de archivo, flag de argumento) con in: y lleva exactamente uno de from: (referencia a una clave de provides) o value: (cadena literal). Un mecanismo escrito como mapa en lugar de como lista, o una entrada que lleva ambas palabras clave, detiene la build en el envoltorio del documento del Aggregate, nombrando la ruta.

  • value: solo en el inject propio de un componente. Un literal pertenece al inject propio del componente, que lo entrega. En una conexión uses, un value: detiene la build, como describe An inject: entry on a connection carries a literal (Una entrada en una conexión lleva un literal), y en el inject propio de un adjunto también detiene la build, como describe An inject: entry on an attached Feature carries a literal (Una entrada en una Feature adjunta lleva un literal): ambos entregan solo claves que publica otra entidad, nombradas con from:.

Consulta vocabulary/topology-triad.md para la especificación completa del Injection Contract, incluida la semántica del contexto de doble estado, las reglas de colisión de claves y ejemplos completos.

Motor de plantillas

El motor de plantillas Go de Aggrega evalúa las plantillas de Recipe y FeatureRecipe contra el contexto de plantillas en la fase por sitio que documenta la Matriz de expansión de plantillas. La biblioteca de helpers Sprig está prerregistrada junto a los helpers propios de Aggrega en cada superficie que evalúa el renderizador, con una excepción: resolver una coordenada source: estructurada registra solo los helpers de Aggrega — allí están disponibles optional y capitalizedWords, y las funciones de Sprig no, de modo que una llamada a Sprig en un campo source:, o en una entrada locals: de una entidad que lleva un source: estructurado, se detiene en el análisis. Consulta errors/fatal-halts.md, que dedica a esa superficie una sección propia. La evaluación, el análisis y la integración con Sprig están disponibles hoy.

Comportamiento ante claves ausentes — tolerado en las plantillas de valor; missingkey=error estricto en las plantillas de ruta, en las aserciones y en una coordenada source:. Las plantillas de valor se evalúan con la opción missingkey=zero de Go, de modo que una plantilla que hace referencia a una clave no vinculada (p. ej., .values.unset_field) no genera un error y la lectura no renderiza nada. Los modismos de catálogo como {{ .values.optional_field | default "fallback" }} siguen funcionando con esta política, porque un valor no definido cuenta como vacío para default. Las plantillas de ruta (directory: / subDirectory: en los boundaries de la Release) se evalúan con missingkey=error contra una lista de permitidos cerrada — los fallos silenciosos de ruta producen estructuras de sistema de archivos rotas que los operadores solo descubren después del build, y el rigor detecta el error antes. Otras dos superficies siguen la misma política estricta, por el mismo motivo: allí un renderizado vacío produciría un veredicto erróneo o un pin erróneo en lugar de un campo que el autor pueda releer. Se trata de una entrada assertions: en un Component, una Feature, una Recipe o una FeatureRecipe, y de los campos con plantillas de un bloque source: estructurado en una Recipe o una FeatureRecipe. errors/fatal-halts.md da cuenta de la política de cada superficie una por una y ofrece las formas sensibles a la presencia que funcionan con la estricta.

Valor de respaldo sensible a la presencia mediante optional. Cuando el autor de una Recipe necesita distinguir «clave ausente» de «clave presente con un valor cero / vacío / false» — la distinción que el default de Sprig no puede hacer —, el renderizador expone el helper optional: {{ optional .infra "replicas" 1 }} devuelve el infra.replicas escrito (incluido un 0 escrito) cuando está presente, y recurre a 1 solo cuando la clave está ausente. Consulta templates/sprig-functions.md para la semántica completa.

Plegado de nombres mediante capitalizedWords. Cuando un destino solo acepta letras y dígitos en los nombres con los que direcciona los recursos, {{ capitalizedWords .context.instance_id }} lee el id como palabras separadas por cualquier carácter fuera de ese alfabeto y pone en mayúscula la primera letra de cada palabra, de modo que payments-db da PaymentsDb. El plegado elimina todos los separadores, así que dos id que solo difieren en la puntuación llegan al mismo nombre; un build que emitiría dos recursos con un mismo nombre se detiene y nombra ambos id. Consulta templates/sprig-functions.md para la semántica completa.

Aplicación del contrato de parámetros en la capa de declaración. Los parámetros obligatorios que la Release no proporciona producen errores explícitos en la capa del contrato de parámetros, lo primero que comprueba la resolución, con una procedencia file:line que nombra el parámetro y el contrato. Las violaciones de tipo / restricción aparecen de la misma manera. Esta es la aplicación sustancial de las claves ausentes: el tipado se comprueba donde reside la intención del desarrollador (la declaración parameters: del Aggregate), no en el momento de evaluar las plantillas posteriores. Consulta entities/aggregate.md §«Contratos de parámetros tipados».

Una única gramática de declaración para los parameters: del Aggregate. Cada ranura de parámetro se escribe como un objeto de contrato tipado (key: { type: <type>, default: <value>, ... }). La forma abreviada de escalar simple (key: <value>) se rechaza en el envoltorio del documento del Aggregate, con un error que nombra el parámetro e indica que se esperaba un objeto. El vocabulario del contrato tipado hace explícita la semántica de type:, required: y las restricciones en la capa de declaración; el cumplimiento por parte de la Release sigue usando valores escalares según el tipo declarado en el contrato.

Consulta templates/expansion-matrix.md para la matriz de evaluación por sitio de plantilla y 05-templates.md para la descripción general de las plantillas.

Fases del pipeline de compilación

El pipeline de compilación de Aggrega está documentado en ../architecture/10-compilation-pipeline.md. Estado por fase:

  • Resolución, construcción de la topología, finalización del grafo, análisis estático y renderizado — disponibles.
  • Inject mapping (interceptación previa al renderizado injectMapping) y cada subetapa del renderizado base — publicación de locals, mapping de valores, síntesis del workload, evaluación de artefactos, renderizado del provider, renderizado de features y generación de recursos de la FeatureRecipe de credenciales — disponibles.
  • El pipeline de plugins (ejecución Wasm de pipeline:) — disponible. En una Recipe o una FeatureRecipe que declara pasos pipeline: no vacíos, cada paso se ejecuta en el orden declarado: el compilador despacha el plugin Wasm indicado por el paso sobre la salida renderizada, aplica las operaciones JSON Patch devueltas a los documentos a los que se dirigen y emite los efectos secundarios del paso. Un paso cuya condición when: se renderiza como falsa se omite como paso directo, dejando sin cambios el conjunto de documentos. Los autores que buscan mutaciones al estilo JSONPatch (inyección de sidecars de Envoy, VolumeMount de secretos, etc.) las consiguen mediante esta superficie.

Providers

La biblioteca estándar de Aggrega incluye cinco providers de renderizado — helm, helm-chart, compose, terraform y cloudformation. Estado por provider:

  • helm — disponible. Se incluyen tanto el modo desde origen (renderizado de charts de Helm mediante el SDK de Helm) como el modo sintetizado (Workload → un objeto controlador elegido según el form del Workload — Deployment, StatefulSet, DaemonSet, Job o CronJob — más Services y PVC).
  • helm-chart — disponible. Se incluye el modo desde origen (composición con umbrella chart). El tipo de entrada sintetizado no se aplica a este provider; los autores que necesitan síntesis de manifests de K8s usan el provider helm con workload:.
  • compose — disponible. Se incluyen tanto el modo desde origen (superposición de fragmentos compose) como el modo sintetizado (Workload → servicio compose + volúmenes + redes). La salida docker-compose.yaml por boundary se ensambla mediante el compositor a nivel de Release.
  • terraform — disponible. Se incluyen tanto el modo desde origen como los artefactos; cada boundary recibe una configuración raíz, aggrega.modules.tf, que declara cada componente como un bloque module cuyos archivos están en su propio directorio bajo modules/. El tipo de entrada sintetizado no se aplica a este provider.
  • cloudformation — disponible. Se incluyen tanto el modo desde origen como los artefactos (fragmentos de stack); todos los componentes que se renderizan en un mismo directorio de salida se ensamblan en una única plantilla de stack, emitida como JSON puro. El tipo de entrada sintetizado no se aplica a este provider.

El renderizado Provider lo proporciona un Plugin con pluginType: provider; consulta entities/plugin.md para la superficie de autoría del Plugin de renderizado de providers y 06-providers.md para las páginas de referencia por provider.

Expansión guiada por anotaciones

Los Manifests llevan una sección de vinculación features.annotations: que asigna claves de anotación a tipos de Feature, más una tabla de enrutamiento agrupada por pilar (maps.infra / maps.values) que indica qué propiedades del esquema de la Feature puede rellenar cada vinculación. Documentado en entities/manifest.md y providers/well-known-annotations.md; ubicación en el pipeline en ../architecture/10-compilation-pipeline.md; mecánica en la carga del catálogo y en tiempo de inspección en ../architecture/13-catalog-and-registry.md §«Expansión de Feature guiada por anotaciones».

  • Vinculaciones features.annotations del Manifest — disponibles. La subetapa de expansión de anotaciones de la resolución se incluye de principio a fin. Recorre los boundaries de la Release (de fuera hacia dentro) y los subsistemas del Aggregate (de fuera hacia dentro), calcula el conjunto efectivo de anotaciones por componente mediante cascada + sobrescritura con exclusión por null del valor completo y por subclave, analiza cada valor de anotación como un escalar, un mapa estructurado o un null explícito, encamina por subclave a través de la declaración maps de la vinculación aplicando la restricción de lado frente a pilar (el lado Aggregate activa maps.values; el lado Release activa maps.infra), valida los tipos de cada hoja contra el spec.schema de la Feature de destino e inyecta adjuntos de Feature sintéticos, que el grafo IR marca con origin: annotation. La composición entre ambos lados fusiona por pilar y por campo al construir la IR, y el valor explícito prevalece campo a campo; aggrega inspect muestra la procedencia entre corchetes para cada hoja. La validación de los destinos de vinculación en la carga del catálogo, el lint de solapamiento de pilares del esquema y el lint de solapamiento de mapas de vinculación protegen el recorrido. El prefijo simple aggrega.ai/ se rechaza al cargar el Manifest cuando se usa como clave de vinculación — ese prefijo está reservado a las anotaciones nativas de la plataforma; las vinculaciones usan feature.aggrega.ai/ o un dominio personalizado.

Coincidencia de versiones

Las Recipes y las FeatureRecipes declaran la interfaz de Component o de Feature que implementan mediante la palabra clave implements:. implements: nunca selecciona una Recipe: lo hace el mapeo del Manifest, y una instancia cuyo tipo no cubre ningún mapeo se detiene con un error que enumera como candidatas las Recipes cuyo implements: puede implementar ese tipo. Lo que implements: determina es la comprobación de que la Recipe de cada entrada de mapeo del Manifest implementa el tipo mapeado, o una base que ese tipo extiende con extends. El tipo mapeado es la clave de la entrada y, para una clave components.type, también el tipo de cada instancia de componente que la clave alcanza en una versión que la clave no nombra — cada instancia que alcanza, para una clave escrita sin versión — en la versión con la que la build compila esa instancia: la versión que nombra la instancia o, para una instancia que no nombra ninguna, la versión más alta de ese Component que contiene el catálogo. Estado por forma:

  • Exacta (core/api-server:1.0.0) — disponible. El tipo mapeado debe ser esa versión.
  • Rango compatible con la versión mayor (core/api-server:^1.0.0) — disponible. La forma con circunflejo es una restricción SemVer (>=1.0.0, <2.0.0 en el ejemplo); la versión del tipo mapeado debe satisfacerla.
  • Sin versión (core/api-server) — disponible. Cualquier versión del tipo la satisface.

Una entrada de mapeo cuyo implements: de la Recipe no coincide ni con el tipo mapeado ni con ninguna de sus bases detiene la build con un OPS_ERROR que nombra la entrada, la Recipe y su valor implements:. Una instancia de componente que una clave alcanza en otra versión, cuya versión no satisface el implements: de la Recipe, detiene la build con el mismo OPS_ERROR, nombrando la instancia, su tipo — y, para una instancia que no nombra ninguna versión, la versión con la que se compiló —, la clave, la Recipe y su valor implements:. La forma con circunflejo es la superficie de autoría canónica para la coincidencia compatible con la versión mayor.

Consulta vocabulary/inheritance-and-interface.md para la superficie de diseño de implements: y entities/manifest.md para la forma del nivel de mapping por Manifest.

Envoltorio de metadatos

Los envoltorios de las entidades de catálogo llevan metadata.labels, metadata.annotations y (en la Release) metadata.environment. Estado por superficie:

Disponibilidad de metadata.labels y metadata.annotations — en siete tipos. Los envoltorios de entidad que llevan estos campos son Component (etiquetas obligatorias, con la clave obligatoria component.aggrega.ai/type, anotaciones opcionales), Feature (ambos opcionales), los cuatro tipos de biblioteca SchemaLibrary, MappingLibrary, WorkloadLibrary y ArtifactLibrary (ambos opcionales) y Aggregate (solo etiquetas, opcionales). Las entidades restantes — Recipe, FeatureRecipe, Manifest, Release, Plugin — no aceptan metadata.labels ni metadata.annotations a nivel de envoltorio.

metadata.environment en la Release — obligatorio. El esquema de la Release enumera environment como campo metadata obligatorio; la build estampa su valor en la salida renderizada como la etiqueta aggrega.ai/environment. Consulta entities/release.md para los cinco casos de uso prácticos de la sección Environment Metadata (atribución de costes OTel/FinOps, filtrado de trazas/logs OTel, orientación de operadores de Kubernetes, diferenciación de producción multirregión, delimitación del ámbito de cumplimiento).

Consulta 02-naming-conventions.md para la disciplina de uso de mayúsculas en los campos que se aplica a las claves metadata, y las páginas de referencia de cada entidad para las formas de envoltorio que acepta hoy cada entidad.

Comandos de la CLI

La CLI de Aggrega registra el pipeline de build más la introspección. Estado por comando:

  • aggrega build — disponible. Lee un archivo de Release, resuelve el Aggregate + el Manifest, ejecuta el pipeline de compilación y escribe los artefactos renderizados en los directorios de salida de los boundaries. Cuando hay un lockfile, verifica las dependencias contra él; cuando no lo hay, se detiene pidiendo un pull, o lo rellena primero donde --auto-pull o auto_pull lo piden.
  • aggrega inspect — disponible. Inspecciona una entidad de catálogo, un archivo de entidad, una entidad publicada en un registry o una Release, e informa de su forma resuelta. Consulta cli/aggrega-inspect.md.
  • aggrega pull — disponible. Resuelve todas las dependencias de una Release y escribe un lockfile por Release que fija cada entidad de catálogo y cada artefacto de origen a una versión y un digest de contenido, y cada entrada externa que solicita el renderizado de la Release a un digest de contenido; almacena en caché el contenido obtenido en .aggrega/cache. --verify comprueba un lockfile existente contra el estado actual. Consulta cli/aggrega-pull.md.
  • aggrega push — disponible. Publica una entidad de catálogo en un registry OCI; aggrega push --list-kinds indica qué tipos acepta. Consulta cli/aggrega-push.md.
  • aggrega lint — disponible. Ejecuta las reglas de disciplina de publicación con la severidad warn sobre todo el catálogo, el cierre de dependencias de una Release o una sola entidad; sobre una sola entidad, --pre-publish añade una comprobación del incremento de versión respecto a la versión publicada actualmente de la entidad, y una discrepancia provoca una detención. Las reglas se distribuyen como un plugin Wasm opcional. Consulta cli/aggrega-lint.md.
  • aggrega serve — disponible. Un daemon de compilador como servicio de larga duración que habla JSON-RPC 2.0 por stdin/stdout, para la integración con editores e IDE. Consulta cli/aggrega-serve.md para los métodos que sirve.
  • aggrega version — disponible. Imprime la versión de la CLI; -o json emite un objeto de versión legible por máquinas.
  • aggrega validate — disponible. Comprueba la corrección en todo el catálogo, en una Release o en una sola entidad, e informa de los diagnósticos sin renderizar artefactos.
  • aggrega search — disponible. Busca entidades publicadas en el índice local de los registries configurados; el índice lo crea y actualiza aggrega registry update.
  • aggrega registry — disponible. Gestiona los registries y su política de confianza de firmas; registry add registra un registry y registry update crea el índice local que consulta aggrega search.
  • aggrega push-artifact — disponible. Publica un artefacto de datos independiente (como un paquete de documentación) en un registry OCI, junto a push, que publica entidades.
  • aggrega sign — disponible. Firma uno o más artefactos ya publicados y adjunta sus firmas.
  • aggrega deprecate — disponible. Adjunta un marcador de obsolescencia firmado a un artefacto ya publicado.
  • aggrega login y aggrega logout — disponibles. Se autentican en un registry OCI y almacenan la credencial, o eliminan una credencial almacenada.
  • aggrega auth — disponible. Gestiona la identidad de firma local que se usa para firmar artefactos.
  • aggrega config — disponible. Inspecciona y gestiona la configuración del workspace; los subcomandos muestran la configuración efectiva fusionada y de dónde procede cada ajuste, inicializan una configuración funcional con un registry y su política de confianza de firmas, y congelan en el workspace la configuración efectiva crítica para el build, de modo que se compile de forma idéntica sin depender de la configuración global de la máquina.
  • aggrega get-schema — disponible. Imprime el JSON Schema de un tipo de entidad o de contrato.
  • aggrega plugin — disponible. Inspecciona los plugins Wasm que la CLI puede resolver; los subcomandos los enumeran, añaden y eliminan plugins configurados, sincronizan los registros gestionados por la máquina de un plugin y generan una vista de catálogo de ellos.
  • aggrega cache — disponible. Inspecciona y mantiene las cachés en disco; los subcomandos informan del estado, depuran, desalojan entradas y vacían.
  • aggrega mcp — disponible. Ejecuta un servidor Model Context Protocol por stdio, o por HTTPS para un cliente en otra máquina, y expone la introspección del compilador a las integraciones con asistentes de IA.
  • aggrega completion — disponible. Genera el script de autocompletado del shell para la CLI.
  • Subcomandos de extensión de la CLI — disponibles. Un plugin Wasm publicado como invitado pluginType: cli se resuelve y se registra como subcomando de aggrega, de modo que una extensión instalada se ejecuta como aggrega <extension> junto a los comandos integrados.
  • aggrega import — disponible. Convierte un origen declarativo externo de definición de agentes (Langflow, Flowise, n8n) en borradores de archivos de autoría de Aggregate y Component, con una decisión determinista de reutilización del catálogo, puntuada por confianza, registrada para cada nodo. El mapping específico del formato lo proporciona un plugin importador que el workspace resuelve para el formato de origen — uno que contiene su catálogo, o uno de los importadores de Langflow, Flowise y n8n del compilador, que se compilan y publican con cada release del compilador. El binario lleva sus entidades Plugin pero no sus módulos, de modo que sirven sus formatos en todos los workspaces: el primer import que necesita uno que la máquina no tiene lo obtiene del registry predeterminado del workspace, lo verifica y lo conserva en la caché de contenido para cada import posterior. Un origen se analiza con el parser que el catálogo del workspace ofrece para su sintaxis o, cuando el catálogo no ofrece ninguno, con el que lleva el compilador, de modo que un workspace cuyo catálogo no contiene ningún parser importa mediante uno u otro.
  • aggrega scaffold — disponible. Redacta un documento inicial para cualquier tipo de entidad a partir del esquema de ese tipo — cada campo que exige, con un marcador de posición donde se necesita un valor — y lo escribe en la salida estándar; con --example, escribe en un directorio nuevo uno de los ejemplos ejecutables de la documentación, leído del paquete de documentación firmado.
  • aggrega explain — disponible. Explica la condición de detención que nombra un código corto (como E0007) o un código descriptivo.
  • aggrega edit-document — disponible. Aplica a un documento una única edición estructurada y acotada — añadir un componente, adjuntar una Feature, conectar una conexión o establecer un valor — conservando cada byte que no toca.
  • aggrega pin — disponible. Registra, en el entity.lock situado junto a una Recipe o una FeatureRecipe, el pin de contenido de cada entrada que la entidad lee desde fuera de su propio documento.
  • aggrega skills — disponible. Instala la skill de Aggrega en un asistente de IA.

Consulta 07-cli.md para la descripción general de la CLI y el índice de la referencia del lenguaje para todas las páginas de referencia por comando.

Editores y otros frontends

Cada frontend muestra lo que compiló el binario aggrega; ninguno incluye un compilador propio. Estado por superficie:

  • Contrato del grafo IR — disponible. El esquema del grafo IR, el contrato con el que todo frontend lee el grafo, se incluye en la distribución de esquemas de Aggrega; consulta la referencia del esquema IR.
  • Leer el grafo desde un comando — disponible. aggrega build acepta --ir-graph, y también aggrega inspect cuando recibe una Release y aggrega validate --release; el flag escribe en stdout como JSON el grafo que resolvió esa ejecución, además de lo que el comando ya produce. Una sesión del daemon lee el mismo grafo en aggrega/irGraph, y las herramientas cli-inspect, cli-build y cli-validate del servidor MCP lo aceptan como su argumento ir_graph.
  • Grafo de topología en Visual Studio Code — disponible. La extensión de Aggrega para Visual Studio Code dibuja el grafo IR de la Release seleccionada como un grafo interactivo y adjunta Features desde él, y pide ambas cosas al daemon aggrega serve.
  • Modo de streaming headless de la CLI — planificado. El modo headless emite el grafo IR como JSON delimitado por saltos de línea en stdout para que un frontend lo consuma a medida que cambia la topología. Lo que se incluye hoy es un documento por invocación, no un flujo: ningún comando emite una secuencia de grafos en un mismo stdout a medida que cambia una topología.

Consulta ../architecture/15-editors-assistants-and-frontends.md para ver cómo el editor, el asistente y el daemon llegan al compilador.

Direcciones de diseño

La taxonomía de estados anterior clasifica el estado por superficie en todo el lenguaje; esta sección registra el estado de direcciones de diseño más amplias documentadas en los capítulos de arquitectura.

El cumplimiento normativo en todo el parque no es una dirección planificada: establecer una regla de gobernanza una sola vez para que vincule cada build del workspace está disponible hoy mediante el socket de gobernanza. Un plugin conectado en la clave plugins.governance de la configuración del workspace evalúa cada build de ese workspace — un rol de veredicto que rechaza un grafo o un artefacto renderizado que infringe la regla, un rol de transformación que proporciona metadatos derivados que un desarrollador nunca escribe. Consulta ../architecture/11-governance-and-compliance.md.

  • Interface Parity & Auto-Implementation — disponible. Una Recipe escrita para un Component base sirve a cada Component que lo extiende, a cualquier profundidad de la cadena, sin que el Architect tenga que escribir una Recipe duplicada. El Component que extiende escribe schema: inherited, por lo que no añade a values / infra / provides ninguna clave raíz que la Recipe de la base no pudiera consumir; un Component que declara extends con un esquema propio se rechaza en el envoltorio de su documento. El Manifest sigue mapeando el tipo que extiende con una entrada propia, y la comprobación del mapeo la acepta cuando el implements de la Recipe mapeada nombra el tipo o cualquier base que este extiende. Documentado en ../architecture/02-ecosystem-philosophy.md.
  • Ghost Infrastructure Tracker — disponible. Una salvaguarda de la fase de renderizado emite una advertencia cuando una clave que un autor declaró llega a un nodo y ninguna plantilla que declara la Recipe vinculada la lee, de modo que un valor declarado por el autor y descartado en silencio por la plantilla se nombra en lugar de perderse. Es la mitad de la fase de renderizado del mismo diseño de coincidencia de formas. Consulta errors/warnings.md.

Los capítulos de arquitectura describen las superficies de diseño; esta página sigue el estado de implementación.