Referencia del lenguaje
El «qué» y el «cómo se usa» de Aggrega. Sintaxis, invocación de la CLI, catálogo de errores, ejemplos completos.
Lee los capítulos siguientes en orden para una primera comprensión. Los subdirectorios de referencia aparecen bajo su capítulo — ve directamente a ellos cuando busques una entidad, palabra clave, provider, comando de la CLI o error concretos.
Antes de leer la secuencia de capítulos, consulta Estado del lenguaje para conocer el estado actual de madurez — qué superficies del lenguaje están disponibles hoy, cuáles están aceptadas pero el compilador aún no actúa sobre ellas y cuáles están planificadas para iteraciones futuras. Compatibilidad indica lo que promete una release para los esquemas, la línea de comandos, las herramientas del asistente, los códigos de error y los kits de plugins.
Modelo de niveles de entidades
Los tipos de entidad de authoring de Aggrega se organizan en tres niveles que reflejan la progresión de la adopción (a continuación). Junto a ellos se encuentra el Workload, propiedad de la plataforma, que no es un tipo de authoring propio: es la forma que adopta la entrada sintetizada de una Recipe y expresa la forma de cómputo mediante el vocabulario form: (stateless, stateful, daemon, scheduled, task, reference). La división en niveles es un mecanismo de documentación y de incorporación, no una restricción de tiempo de ejecución: cada tipo de entidad es un ciudadano de primera clase del lenguaje; el compilador los trata de manera uniforme; el Aggrega de código abierto admite todos los niveles sin licencias ni restricciones de funcionalidades. Los marcadores de nivel señalan «avanzado; omítelo si no lo necesitas» para la navegación, no para las capacidades.
| Nivel | Tipos de entidad | Cuándo adoptarlos |
|---|---|---|
| Nivel 1 — la superficie mínima viable | Aggregate, Component, Recipe, Manifest, Release | Día 1 — fundadores en solitario y equipos pequeños entregan software funcional solo con el Nivel 1. El modelo mental: «Tengo una aplicación; quiero desplegarla; así se hace.» |
| Nivel 2 — separación de roles | Feature, FeatureRecipe, Plugin | Día 30 — equipos pequeños en los que los roles se separan (desarrollador + Ops + a veces Seguridad). El Nivel 2 entra a través de los Plugins de renderizado de providers (Ops elige entre Helm, helm-chart, Compose, Terraform y CloudFormation), las Features (Seguridad gestiona las credenciales por separado de la configuración de la aplicación) y las FeatureRecipes (personalización en el momento del enlace por provider). |
| Nivel 3 — reutilización entre Component | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | Día 365 — catálogos maduros en los que formas comunes se repiten en muchas entidades. El umbral es informal: cuando una forma (p. ej., PodResources) aparece en 5+ Components y coordinar sus actualizaciones supone fricción, una entrada de SchemaLibrary se justifica por sí sola. |
Cada progresión es opcional. Un fundador en solitario nunca está obligado a mirar el Nivel 3; un catálogo empresarial tiene pleno acceso al Nivel 3 cuando lo necesite. El Nivel 1 es completo para el caso de uso del fundador en solitario: un desarrollador puede entregar aplicaciones funcionales usando solo entidades de Nivel 1. Es una propiedad de diseño sólida: el Nivel 1 no es un «subconjunto que compila»; es un «subconjunto que entrega software».
La superficie de Nivel 1 de cinco entidades conlleva un coste de entrada: Aggregate + Component + Recipe + Manifest + Release es más ceremonia que «suelta un archivo YAML y obtén un servicio en ejecución». El coste es el precio de la separación del authoring en cuatro dominios (Intención del desarrollador / Catálogo de la plataforma / Operaciones de la plataforma / Enrutamiento) que diferencia a Aggrega de Helm o Terraform sin más. Los tutoriales de Nivel 1 recorren explícitamente la configuración de cinco entidades.
Dentro del Nivel 3, el mecanismo spec.templates / $instantiate: (helpers paramétricos en la SchemaLibrary) se documenta como una subfuncionalidad aún más avanzada. La mayoría de quienes adoptan el Nivel 3 no recurren a spec.templates al principio; el umbral es «cuando tu biblioteca tiene 6+ esquemas que comparten una estructura parametrizada».
Orden de lectura
- Cómo usar esta referencia
- Convenciones de nomenclatura
- Descripción general de la referencia de entidades
- Nivel 1: aggregate, component, recipe, manifest, release
- Nivel 2: feature, featurerecipe, plugin
- Nivel 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Transversal: workload (tipo del compilador propiedad de la plataforma, consumido dentro del
workload:de una Recipe)
- Descripción general del vocabulario
- Referencia del vocabulario: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Descripción general de las plantillas
- Referencia de las plantillas: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Descripción general de los Providers
- Referencia de los Providers: architecture, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- Descripción general de la CLI
- Referencia de la CLI: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import y el archivo de respuestas de la importación, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Descripción general de los errores
- Referencia de los errores: fatal-halts, warnings, sentinels, error-translation
- Descripción general de los ejemplos
- Referencia de los ejemplos: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; workspaces ejecutables: Ejemplos ejecutables
Referencia para el authoring de Plugin
La superficie de plugins Wasm se sitúa junto a la secuencia de capítulos en lugar de dentro de ella: un autor de plugins la lee independientemente del recorrido de authoring de entidades. La página de la entidad plugin cubre la superficie de authoring del catálogo; las páginas siguientes cubren los sockets, los payloads y el flujo de trabajo del autor.
- plugin-contract — los sockets a los que se conecta un plugin, su posición en el pipeline y las formas de entrada y salida de cada socket.
- plugin-developer-guide — el flujo de trabajo completo del autor:
describe(), declaraciones de capacidades, límites de ejecución, el ciclo de vida publish/pull/build, firma, versionado. - policy-socket — el socket de gobernanza en profundidad: sus cuatro roles, las severidades de los veredictos, el canal de entrada del operador y cómo escribir una policy para cualquiera de los dos motores incluidos en el compilador.
- governance-attachment-facts — los datos por vinculación que una policy de gobernanza lee del grafo de build, incluidas las tres unidades de la marca de sensibilidad y por qué la ausencia de marca no es un permiso.
- when-to-use-a-pipeline-step — cómo elegir entre un paso de pipeline y una FeatureRecipe basada en plantillas.
- embedded-plugins — los plugins incluidos en el binario del compilador.
- tagging-plugins — los dos plugins de gobernanza integrados que escriben etiquetas sin una política,
governance/label-injectorygovernance/selector-tagger: sus ajustes y lo que escribe cada uno. - core-importers — los diez importadores del compilador, desde Langflow, Flowise y n8n hasta Compose, MCP y los frameworks de agentes: qué lee y qué redacta como borrador cada uno, su configuración y su publicación con cada release del compilador.
- authoring-a-provider-walkthrough — un recorrido práctico de la escritura de un guest provider, desde un directorio vacío hasta una build que escribe los archivos que el provider renderizó.
- writing-a-governance-plugin — escribir tu propio plugin de gobernanza a partir del esqueleto de adaptador del kit de plugins: una regla, el export de cada rol ejecutado a mano, una entidad
Pluginen el catálogo del workspace y una build que rechaza. - compatibility — cómo se versionan los kits de plugins: qué pueden cambiar una release de parche y una release menor de un kit, y qué permite que un plugin ya compilado se siga cargando.