Catálogo y registro
Este capítulo define cómo la plataforma escala en toda la empresa mediante el Catálogo OCI (Open Container Initiative): cómo se organiza el catálogo, cómo se resuelve una referencia, cómo se publica y se fija una entidad, y las formas de nombre que siguen las entidades del catálogo.
El catálogo de Aggrega: taxonomía y resolución del registro
El compilador de Aggrega se basa en un registro estrictamente tipado e inspirado en OAM para resolver la intención abstracta del desarrollador (Dominio 1) en una realidad concreta de Ops (Dominio 3). Para dar soporte a un ecosistema abierto y distribuido manteniendo una experiencia de desarrollo fluida, todos los esquemas, enlaces de infraestructura, políticas programables y plugins adaptadores siguen una taxonomía de URI estandarizada de la Open Container Initiative (OCI). Como cada entidad del catálogo es direccionable por URI, aggrega pull trae a la caché las que necesita una Release y las fija en su lockfile, y una build las lee desde ahí. El workspace local del desarrollador contiene solo sus archivos Aggregate y Release, no una copia del catálogo.
1. Estructura de directorios principal (el catálogo)
La carpeta aggrega-catalog de la biblioteca estándar (y cualquier catálogo de terceros conforme) se organiza para imponer físicamente la separación de responsabilidades. La estructura separa explícitamente las interfaces abstractas de sus implementaciones de infraestructura concretas.
Para los Components y las Features, los segmentos del URI se corresponden 1:1 con los segmentos de ruta del sistema de archivos. Los Components usan un URI de tres segmentos ({publisher}/{category}/{name}) en el que el segmento de categoría lleva una de un conjunto cerrado de categorías cognitivas — la misma palabra que la etiqueta component.aggrega.ai/category del componente (el espejo 1:1 del directorio, comprobado por la regla category-matches-directory del linter de publicación). Las Features siguen siendo planas ({publisher}/{name}) — un conjunto pequeño, que crece despacio. La clasificación ontológica operativa (stateful-server, server, etc.) reside en la etiqueta component.aggrega.ai/type, nunca en la estructura de directorios; las etiquetas de capacidad cognitiva (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) superponen subconjuntos de comportamiento. La interfaz web del hub usa etiquetas para filtrar y buscar; las categorías sirven tanto para la navegación por el sistema de archivos como para el eje de exploración del catálogo.
El árbol siguiente es ilustrativo en su contenido y exacto en su forma. Donde una entidad se dibuja completa, llega hasta su archivo hoja, de modo que se puede leer en el diagrama una ruta real completa: qué nivel de directorio lleva qué segmento del URI, dónde se sitúa el segmento de versión obligatorio y qué nombre de archivo usa cada tipo de entidad en la hoja. Muestra un puñado de entradas por nivel en lugar del contenido completo del catálogo — ... marca una elisión, y los nombres escritos a su lado son más entradas de ese mismo nivel.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformLas categorías de componentes son un conjunto cerrado, y es ese conjunto — no el sistema de archivos — la autoridad sobre las categorías. Un valor de categoría que aún no tiene ninguna entidad es vocabulario reservado: el eje de exploración se mantiene estable y un autor sabe dónde caerá un componente futuro, así que un estante vacío es correcto y no una vacante que deba un ocupante. Como el catálogo no contiene archivos de marcador de posición, el directorio de un valor así se crea cuando llega su primera entidad.
La lista autorizada — cada categoría, lo que contiene, los valores operativos de type que suelen llevar sus entidades y qué directorios existen — es la sección Categorías de Component de la guía de convenciones del catálogo, publicada junto al catálogo de la biblioteca estándar que rige.
El eje type lleva solo las primitivas operativas — el vocabulario cognitivo nunca aparece en él, y el esquema publicado de Component enumera los valores que admite la clave reservada, de modo que una palabra cognitiva escrita ahí se rechaza al cargar el documento. La división en tres ejes: type operativo (cómo trata la infraestructura al componente), category cognitiva (qué es, reflejada por el directorio) y etiquetas de capacidad por rol (subconjuntos de comportamiento — una entidad es category: datastore más el valor de datastore.aggrega.ai/engine que lleve su propia identidad de producto, de modo que core/datastore/qdrant lleva vector y core/datastore/redis lleva kv, y ambos ejes son consultables). Una capacidad cuya veracidad depende de lo que configure un autor no se lleva en absoluto en el catálogo: la inyecta en tiempo de compilación el rol label-transform del socket de gobernanza, que lee los values declarados por el desarrollador. Las categorías puramente de IA llevan el prefijo ai-; las categorías de doble uso aparecen sin prefijo, con el matiz de IA expresado mediante etiquetas de capacidad. Las categorías se eligen según cómo navegan y exploran los usuarios, no según cómo clasifica el compilador — el vocabulario de categorías y las etiquetas de capacidad son términos con los que el compilador compara selectores y a los que no atribuye ningún significado. El nombre de un componente no repite su categoría: el modelo de OpenAI de la biblioteca estándar es core/ai-model/openai, no core/ai-model/openai-model.
2. El esquema dividido y el pipeline de síntesis del bridge
Para eliminar el código repetitivo por cada Component en torno a las declaraciones de sockets de topología, Aggrega divide la validación en dos partes y controla cada una donde reside su objeto:
usesSchema(YAML declarativo). Declara los sockets de topología que ofrece una entidad del catálogo y asigna a cada uno un contrato. La CLI de Go lo lee de forma nativa para extraer las cadenasselector:para la coincidencia de etiquetas durante el análisis estático y para validar los mecanismosinjectpermitidos. Cada entrada de socket admite un campo opcionalrequired: true(por defectofalse) — cuando se establece, el compilador emite un error de validación si no se declara ninguna dependencia en ese socket. Es la contrapartida para los sockets de la semántica derequired: trueen las entradas defeaturesSchema: ambas detienen la build. Declarar un socket aquí es lo que hace el catálogo de la biblioteca estándar y sigue siendo el mejor camino — pero no es la única forma en que un desarrollador puede trazar una arista. El autor de un Aggregate puede nombrar en su propio componente un socket que esteusesSchemano declara, incluso en una entidad que no declara ningúnusesSchema; un socket ad hoc de este tipo no lleva selector, ni lista de permitidosinject, ni esquema por arista, precisamente porque aquí no hay ninguna entrada que los lleve. Losusesde un acoplamiento de Feature y losusespor arista de una Release no están abiertos de esa forma — ambos solo pueden nombrar un socket declarado. Consulta dependency-resolution §«Dominio 2: el esquema dividido» para conocer el contrato completo y aquello a lo que renuncia un socket ad hoc.- Desazucarado. Si los desarrolladores usan la forma abreviada de array YAML (
uses: databases: ["db1"]), la CLI la normaliza en un mapa ({"db1": {"target": "db1"}}). - Síntesis del bridge. El compilador proyecta la tabla de slots
featuresSchema:en un fragmento de JSON Schema 2020-12 — una propiedad por cada slot de acoplamiento, que describe la forma de un relleno que puede vincularlo, con una palabra clave de extensiónx-aggrega-inject:en un slot que declara una lista de permitidosinject. La validación de JSON Schema ignora las palabras clave de extensión durante la validación estructural, y nada vuelve a leer ninguna desde el fragmento: una comprobación que necesita la lista de permitidos de un slot lee el propio slot. La tabla de socketsusesSchema:no se proyecta en ningún fragmento. Elselector:y elinject:de un socket permanecen en el YAML tipado que escribió el arquitecto y se leen desde allí, y elvalueSchema:/infraSchema:por arista de un socket se encapsula y se compila por separado, sin ninguna restricción inventada a su alrededor. - Composición. El arquitecto de plataforma escribe una declaración
schema:estricta (forma compacta o JSON Schema 2020-12 completo) que definevalues,infrayprovides. Esa declaración es el contrato propio de la entidad y se compila por separado: ni el fragmento de slots ni la tabla de sockets se incorporan a ella. Cada superficie se comprueba donde reside su objeto, de modo que un fallo de socket se notifica sobre la entrada de socket que escribió el arquitecto y no en una ruta dentro del bloqueschema:— y el arquitecto sigue sin escribir código repetitivo deuses.
Ejemplo — una declaración de socket y lo que el compilador hace con ella: El YAML del arquitecto de plataforma
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}Lo que el compilador hace con ella La tabla de sockets se lee como el YAML tipado que es: la cadena selector: va al motor nativo de coincidencia de etiquetas, y la lista inject: restringe qué mecanismos de entrega puede nombrar una arista que pase por ese socket. El bloque schema: se compila por separado, como contrato values / infra / provides propio de la entidad. El analizador estático lee la cadena selector: de la entrada de socket que escribió el arquitecto — junto con appliesTo / appliesToAnyOf de las entidades Feature — y evalúa la coincidencia de etiquetas frente a los metadata.labels de cada destino para validar la seguridad de tipos entre nodos.
Selectores al estilo de Kubernetes en usesSchema
El motor nativo de coincidencia de etiquetas del compilador de Go evalúa las cadenas de selector con la semántica de selección estándar al estilo de Kubernetes (AND mediante coma, OR mediante in(), NOT mediante !=/notin()). Este mismo motor — y la misma gramática de cadenas de selector — evalúa también los selectores de acoplamiento de las Feature (appliesTo y cada elemento de appliesToAnyOf). La capa de selectores es estrictamente la compuerta de la topología — las declaraciones schema: por pilar validan el contenido de values, infra y provides de forma independiente. Después de que el compilador de Go trace las aristas topológicas durante la construcción de la topología, el analizador estático lee las cadenas selector de las entradas de socket que escribió el arquitecto y las evalúa frente a las labels de catálogo del nodo de destino para validar la seguridad de tipos entre nodos.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"Un selector que el motor no puede leer como una de sus seis formas de requisito — un requisito vacío, una clave que contiene espacios o uno de =, !, (, ) y la coma, un conjunto sin cerrar — detiene la compilación en cada arista que protege en lugar de leerse como otro selector. La gramática de selectores enumera las formas y cada rechazo.
3. Formatos y composición de esquemas
Para proporcionar tanto una validación estricta como los metadatos estándar del catálogo (autor, versión, descripción), las definiciones del Dominio 2 (Interfaces) y del Dominio 3 (Implementaciones) se escriben como envoltorios YAML. El Dominio 2 utiliza declaraciones schema: incrustadas, expresadas en forma compacta (la predeterminada; ~15 palabras clave, transformadas mecánicamente a JSON Schema 2020-12) o en YAML de JSON Schema completo.
Por qué cada YAML del catálogo repite el envoltorio. El envoltorio (bloque apiVersion, kind, metadata) aparece al principio de cada archivo del catálogo — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — sin importar lo breve que sea el cuerpo. La repetición es deliberada: cada archivo está diseñado para analizarse, validarse, pasar por el linter e inspeccionarse como un artefacto independiente. Un único archivo descargado del registro OCI, colocado en un sandbox de CI o abierto en un editor de terceros debe llevar suficiente autodescripción como para que las herramientas posteriores puedan identificar qué tipo de entidad representa y qué versión de esquema se aplica. La ubicación del directorio nunca sustituye al envoltorio: cada analizador, validador y linter lee el tipo de la entidad y la versión de esquema del envoltorio. El coste es código repetitivo mecánico por archivo; el beneficio es que la garantía de herramientas independientes se mantiene en la superficie de distribución OCI, en el sistema de archivos local y en las superficies IDE / CI / inspect. Los autores copian el envoltorio de archivos existentes cuando escriben nuevo contenido del catálogo, o parten de aggrega scaffold <kind>, que imprime un documento inicial para el tipo con su apiVersion y su kind ya rellenados.
Para mantener el principio DRY (Don’t Repeat Yourself, «no te repitas»), el catálogo emplea dos mecanismos de composición distintos:
- Entradas compartidas de SchemaLibrary (
$ref:entre documentos): Las definiciones reutilizables de JSON Schema se almacenan en entidades de catálogo SchemaLibrary (Tier 3). Se referencian por identidad mediante$ref:entre documentos (<library>#/schemas/<entry>, sin host — la versión procede del lockfile) desde cualquier esquema de Component o Feature consumidor. La cadena se recorre en tiempo de compilación. Consulta entities/schemalibrary para la forma de autoría de la entidad de biblioteca y vocabulary/cross-document-ref para la semántica de resolución. - Herencia simple (
extends): Para líneas base completas de componentes, las entidades pueden usar la propiedadextends: "URI". El compilador de Go lee recursivamente la cadena de padres y fusiona en profundidad los metadatos YAML (sobrescribiendo las etiquetas en caso de conflicto y añadiendo los arrays). A partir de ahí, los dos tipos de catálogo se separan en los pilares de datos. Elschema:de una Feature se compone con el de su base según la composición de JSON Schema 2020-12. Un Component que extiende no escribe ningún contenido de pilar: escribe el marcador literalschema: inheritedy recibe el bloqueschema:de su base exactamente como lo escribió la base, a cualquier profundidad de una cadena. Lo que un Component así compone en su lugar es estructura — sus slots de acoplamiento (featuresSchema), sus sockets de topología (usesSchema), su lista de permitidos de autoinyección (inject) y susassertionscon nombre se fusionan todos a lo largo de la cadena. Consulta entities/component para los ejemplos de extensión de componentes base e hijo + governance-and-compliance §«Herencia y disciplina de publicación» para lo que la herencia resuelve por construcción y lo que sigue siendo una regla de disciplina de publicación.
Consulta entities/component para los ejemplos de extensión de componentes base e hijo, y entities/recipe para la autoría de Recipe con punteros y mapeadores, con ejemplos completos.
4. La configuración del espacio de trabajo (.aggrega-config.yaml)
El archivo .aggrega-config.yaml en la raíz del espacio de trabajo es la configuración del espacio de trabajo del proyecto — la declaración propia del espacio de trabajo, apta para el control de versiones igual que go.mod o package.json. Por convención, el directorio .aggrega/ se mantiene fuera del control de versiones — inclúyelo en .gitignore, como harías con node_modules/ o .terraform/.
La sección workspace es el marcador de raíz: su presencia marca la raíz del espacio de trabajo, y solo contiene los directorios de catálogo que definen la raíz — catalog_dirs, y el mapa releases que da a una Release directorios de catálogo propios. Cualquier otro ajuste está en el nivel superior. Muchos son valores únicos; otros son secciones que agrupan bajo una sola clave los ajustes de un mismo aspecto. Cada campo es opcional, con valores predeterminados documentados. El conjunto completo y actual de claves de nivel superior, cada una con su tipo, valor predeterminado y significado, se genera a partir del esquema en schema/other/aggrega-config; el ejemplo siguiente muestra el marcador de raíz junto con algunos de los ajustes de valor único:
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootUn bloque signing: contiene los valores predeterminados de firma de artefactos que usan aggrega push --sign y aggrega sign, tanto en el nivel superior (global) como por registro:
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemLa precedencia por campo es flag de la CLI > signing por registro > signing global > valor predeterminado de interés público. Fulcio y Rekor usan por defecto las instancias de interés público de Sigstore, por lo que son opcionales; timestamp_url no tiene valor predeterminado — la marca de tiempo de confianza sin claves procede de la inclusión en el registro de transparencia de Rekor, y una autoridad de sellado de tiempo RFC3161 es opcional (establece timestamp_url, o --timestamp-url, con un endpoint completo para habilitar una). Seguridad: el bloque signing: no contiene material secreto — el token de identidad OIDC nunca es un campo de configuración (es un secreto de corta duración, que se proporciona en el momento de firmar: se obtiene mediante un flujo en el navegador en un terminal interactivo o del workflow en GitHub Actions, y en otro caso se pasa con --identity-token o se exporta como AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN), y la clave privada nunca va en línea; key_path es la ruta a un archivo de clave. Esta es la asimetría deliberada con el lado de la verificación, que fija una clave pública en línea, mientras que en el lado de la firma solo hay siempre una ruta de clave.
Marca una raíz sin catálogos incluidos escribiendo workspace: {}. La lista catalog_dirs admite configuraciones monorepo en las que un catálogo compartido se encuentra en un directorio hermano. El compilador comprueba cada directorio en orden. El flag offline: true impide cualquier acceso a la red — el compilador solo usa rutas locales y la caché, y se detiene si una entidad no se encuentra localmente. Los ajustes por secciones agrupan cada uno un aspecto. Entre ellos: los controles de rigor en tiempo de compilación y las sugerencias de autoría; los sockets de acoplamiento Wasm a nivel de espacio de trabajo (governance, linter, importer, providers, cli), cada uno de los cuales admite una lista de referencias a plugins; el rigor del lint por regla, incluidos los interruptores de política de disciplina de publicación; el ajuste de la caché de análisis del daemon y el tamaño de su pool de workers para el despacho de solicitudes; y el límite de tamaño del almacén de módulos compilados compartido por toda la máquina. Otros, a su vez, contienen los valores predeterminados de firma y de confianza en firmas y el comportamiento propio del daemon. Cada clave de nivel superior está documentada por completo en schema/other/aggrega-config.
Se pueden configurar tres cachés distintas, y vale la pena dedicar un momento a distinguirlas porque sus nombres son parecidos y sus ámbitos no. artifact_cache_dir designa la caché de contenido en disco por espacio de trabajo descrita más abajo. parse_cache limita la caché de análisis en memoria del daemon, que solo vive mientras vive el daemon. compiled_module_cache limita el almacén en disco del código máquina de los plugins compilados — una de las cachés que comparten todos los espacios de trabajo de la máquina, porque la forma compilada de un plugin depende del plugin y no del proyecto que lo usa:
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capDe las cachés que comparten todos los proyectos de la máquina, es la que puede llegar a dominar el uso de la caché en disco, ya que cada plugin que ejecuta la máquina se compila en ella una vez y se conserva, por lo que es la única con un límite de tamaño permanente. Cada invocación que abre el almacén aplica el límite antes de compilar nada, eliminando entradas completas, empezando por las compiladas hace más tiempo, hasta que el resto quepa. (Una compilación ejecutada con --disable-plugin-cache compila en memoria en su lugar, por lo que ni hace crecer el almacén ni lo recorta.) Eliminar una entrada cuesta una recompilación posterior y nada más, y eso es lo que hace seguro bajar el límite y aplicarlo mientras otras compilaciones se ejecutan en la misma máquina. Establécelo por encima de lo que compila una sola compilación: como el límite se aplica antes de compilar, un límite inferior al conjunto de trabajo de una sola compilación hace que cada compilación descarte y recompile los mismos módulos, y por la misma razón el almacén puede quedar por encima del límite entre compilaciones y se recorta de nuevo al inicio de la siguiente. aggrega cache status informa del tamaño del almacén, y aggrega cache evict --max-size lo recorta bajo demanda a un límite indicado en la línea de comandos.
La raíz artifact_cache_dir contiene tres subárboles paralelos que una sola invocación de aggrega pull llena de manera uniforme, uno por cada clase de dependencia fijada: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ para las entidades de catálogo (Components, Features, Recipes, FeatureRecipes, Aggregates, las bibliotecas y los Plugins con los ejecutables que publican), donde el tipo es aquel con el que se publica la entidad, de modo que dos entidades de tipos distintos que comparten una referencia y una versión — un Component y una Recipe con el mismo nombre — ocupan dos slots; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ para los artefactos de origen descargados de los campos spec.source de Recipe / FeatureRecipe (charts de Helm, fragmentos de compose); y <artifact_cache_dir>/inputs/sha256/<hex-digest> para las entradas externas — los documentos remotos que un provider pide al host mientras renderiza, como un $ref en el values.schema.json de un chart que apunta a una URL. Cada slot de caché de un artefacto de origen contiene el archivo .tgz de referencia, un directorio derivado extracted/ regenerado en cada lectura de una compilación y un archivo metadata.yaml que registra la identidad {kind, url, version, digest, mediatype, pulled_at} del artefacto. Cada slot de caché de una entidad contiene el artefacto publicado tal como se obtuvo y el manifiesto OCI frente al que se verifica. El slot de cada tipo cuyo documento puede nombrar un archivo a su lado — una Recipe, una FeatureRecipe, un Component, una Feature — contiene además un directorio derivado extracted/ con los archivos que lleva ese artefacto, en un directorio cuyo nombre es el digest de contenido del artefacto: el documento y los archivos que la entidad declaró, cuando se publicó como archivo comprimido, y solo el documento, cuando se publicó como su documento (§6). El directorio de la entidad se dispone allí a partir del artefacto verificado en cada lectura, igual que los archivos de un artefacto de origen: cada archivo se comprueba frente al artefacto, un archivo modificado o añadido a mano en ese directorio se descarta en lugar de leerse, no se lee nada más bajo extracted/, y un artefacto que no supera la verificación se rechaza antes de disponer nada. Una lectura reescribe solo lo que difiere del artefacto, de modo que las compilaciones que leen una misma caché al mismo tiempo — solicitudes que aggrega serve atiende en paralelo, o dos comandos sobre un mismo espacio de trabajo — encuentran cada una íntegros los archivos que se les entregaron. El segmento <digest-prefix> de 12 caracteres separa en slots distintos el mismo {kind, url, version} reetiquetado con digests upstream diferentes. Una entrada externa no necesita un slot así: se almacena como un único archivo cuyo nombre es el digest de contenido al que el lockfile la fija, de modo que lo que lee una compilación posterior se direcciona por la fijación y no por la URL de la que llegaron los bytes — y eso es lo que permite a esa compilación servir la entrada con la red denegada.
Junto a esos tres pueden aparecer otros tres directorios, y ninguno contiene contenido de dependencias fijadas: index/ contiene las instantáneas consultables por registro que escribe aggrega registry update (§8), signatures/ almacena en caché cada paquete de firma verificado bajo su propio digest, de modo que una lectura posterior vuelve a comprobar el blob en caché frente al digest con el que se registró en lugar de volver a obtener el paquete, y catalog-snapshots/ conserva cada instantánea publicada del catálogo que leyó una importación (§8) —el archivo comprimido y su manifiesto en una ranura con el nombre del digest del manifiesto, con el árbol del catálogo dispuesto a partir del archivo comprimido en cada lectura, y un archivo current que nombra la instantánea que lee el workspace cuando nada nombra otra.
El paquete de documentación no está entre ellos. Sus bytes dependen solo del registro en el que se publica y de la versión con la que se publica, por lo que se conserva una vez por máquina, junto al almacén de módulos compilados bajo la misma raíz de caché por usuario, en docs-bundles/<encoded-reference>/<encoded-version>/ bajo esa raíz: el paquete, el manifiesto frente al que se verifica y las firmas que verificaron sus descargas. artifact_cache_dir no llega a él. Antes de leer una página de él, esas firmas se verifican de nuevo bajo la propia comprobación de firmas del espacio de trabajo que lee para el registro del paquete, de modo que una copia que dejaron entrar los ajustes más permisivos de un espacio de trabajo no se sirve a un espacio de trabajo cuya comprobación la rechaza — consulta aggrega-explain y aggrega-cache.
artifact_cache_dir se escribe relativo a la raíz del espacio de trabajo y designa el mismo directorio sin importar desde qué directorio se invoque un comando ni qué directorios de catálogo se estén explorando. Un valor absoluto se rechaza al cargar la configuración, con un diagnóstico que nombra el campo: cada lector del ajuste lo resuelve frente a la raíz del espacio de trabajo, por lo que una ruta absoluta nombraría una ubicación a la que ninguno de ellos llega, y el fallo sería de otro modo silencioso — la caché que escribe un pull dejaría discretamente de ser la caché que lee una compilación. La caché puede estar dentro de un directorio de catálogo, y en la disposición predeterminada lo está, ya que un directorio de catálogo suele ser la propia raíz del espacio de trabajo. Lo que no debe hacer es ser un directorio de catálogo: una exploración del catálogo se salta la caché, por lo que un directorio de caché que también es un directorio de catálogo saca todo el contenido de ese directorio de cada exploración. artifact_cache_dir: . nombra la raíz del espacio de trabajo, que en la disposición predeterminada es exactamente ese caso, y se rechaza al cargar la configuración con un diagnóstico que nombra el campo — al igual que cualquier otra grafía que se reduzca a la raíz del espacio de trabajo. Esas dos formas, junto con la ruta absoluta anterior, son las que la comprobación de configuración puede reconocer por sí sola. Un valor que nombra algún otro directorio de catálogo — sub, en un espacio de trabajo cuyo catalog_dirs incluye sub — se carga sin objeciones, y el único síntoma es que las entidades que contiene dejan de encontrarse. Mantener la caché fuera de cada directorio incluido en workspace.catalog_dirs forma parte, por tanto, de escribir la configuración, y no es algo que esta compruebe por ti.
Saltarse la caché es lo que impide que un artefacto de resolución se lea como si un autor lo hubiera escrito. Un slot de caché contiene bytes que colocó allí una descarga del registro, almacenados bajo la coordenada desde la que se descargaron y avalados por un digest del lockfile; una exploración que recogiera uno como contenido de catálogo escrito por un autor estaría tomando bytes que nada ha verificado, en una ruta que el autor no puede editar. Conviene enunciar claramente una consecuencia: si la caché contiene una entidad que ningún lockfile fija — dejada por un pull interrumpido, copiada a mano o abandonada cuando una Release dejó de referenciarla —, esa entidad no es visible para una exploración del catálogo, y una compilación o validación que dependa de ella se detiene indicando que no se encontró la entidad. La solución es volver a hacer pull de la Release, para que la entidad se resuelva mediante el lockfile y se registre su digest; la detención nombra la entidad para que pueda identificarse la fijación que falta. La alternativa — resolverla de todos modos — es justamente la lectura no verificada que saltarse la caché existe para evitar.
El lockfile es por Release: resolver release.yaml escribe release.lock junto a él (el nombre base del archivo de la Release más .lock). aggrega pull resuelve las dependencias y escribe el lockfile; aggrega build lo lee y usa las versiones fijadas independientemente del estado del registro en el momento del build. Los workspaces confirman el lockfile en el control de versiones cuando importa la reproducibilidad del build entre máquinas; después de que una entidad, una biblioteca, un plugin o la propia Release cambian en el workspace, aggrega pull --release <release> lo actualiza, resolviendo de nuevo lo que cambió y manteniendo cada otra fijación, y aggrega pull --upgrade --release <release> es la forma de adoptar una versión más reciente que un registro ofrece ahora. El lockfile registra cada entidad resuelta con su tipo, su URI tal como se escribió, la versión resuelta, el digest del contenido y los sitios que la referencian. El tipo y el URI identifican juntos una entrada, de modo que una Release cuyo Aggregate y cuyo Manifest comparten un nombre registra una entrada para cada uno, y una edición de cualquiera de los dos detiene el siguiente build hasta que un pull la registra:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1Cada entrada fijada contiene el tipo + el URI + la versión resuelta + el digest direccionable por contenido. El digest se verifica en cada descarga; los bytes que no coinciden con el digest fijado detienen el build con un error de integridad. El digest de una entidad se calcula sobre lo que lleva una publicación de ella —su documento y cada archivo que declara junto a él, cada uno por su ruta y sus bytes— y no sobre los bytes con los que viaja, de modo que la misma entidad registra el mismo digest tanto si se lee desde un directorio de catálogo como si se descarga de un registro, comoquiera que se haya comprimido su archivo y cualesquiera que sean los bits de permisos, incluido el bit de ejecución, que un checkout haya dado a sus archivos. El digest que el propio registro calcula sobre los bytes publicados es aquello contra lo que se verifica primero una descarga, a través del manifest, cuyo digest registra una entrada resuelta por el registro junto al suyo propio.
5. El modelo de resolución de entidades de tres niveles
El compilador resuelve cada referencia a una entidad encontrada durante la compilación mediante una búsqueda en cascada estricta. Los tres niveles — ruta local, workspace y caché, y registro — corresponden a tres flujos de trabajo de autoría que coexisten en un proyecto Aggrega sano: una Release que nombra los archivos que tiene al lado, un equipo que consume un catálogo confirmado en el repositorio más la caché descargada previamente, y un pull que llega al registro en busca de un artefacto aún no descargado. El nivel de workspace y caché y el nivel de registro de la misma cascada evalúan los campos type en los Aggregates, los valores de URI en los mapeos del Manifest, las declaraciones implements en Recipes y FeatureRecipes, y las referencias plugin dentro de los pipelines de Recipe y FeatureRecipe; al nivel de ruta local solo llegan los archivos que nombran una Release y su Manifest.
Ruta local. Una referencia aggregate, manifest o extends de una Release, o el extends de un Manifest, que comienza con ./ o ../ (un prefijo de ruta relativa POSIX) se lee directamente del disco, de forma relativa a la Release. Sin búsqueda en el catálogo, sin llamada al registro. El prefijo explícito distingue en el nivel sintáctico la intención de ruta local de la búsqueda por nombre: una Release que escribe aggregate: ./aggregate.yaml nombra un archivo; aggregate: checkout nombra un Aggregate por su metadata.name. El resolvedor nunca examina el contenido de la cadena para decidir qué nivel se aplica — el prefijo es el discriminante. Cualquier otra referencia, incluido un type de Component en un Aggregate, se resuelve mediante el nivel de workspace y caché y el nivel de registro: una entidad escrita localmente se coloca bajo catalog/ en la raíz del workspace o en un directorio que enumera workspace.catalog_dirs, y un type escrito como ruta de archivo relativa detiene el build como una entidad que ningún catálogo contiene.
Workspace y caché. Una referencia sin un prefijo explícito de ruta local se busca primero en los directorios enumerados en workspace.catalog_dirs (árboles de catálogo locales al proyecto, escritos en el repositorio o copiados en él — consulta el §4 para la forma de la configuración) — o, para una Release a la que la configuración asigna directorios propios en workspace.releases, en los de esa Release — después en el directorio catalog/ de la raíz del workspace, y luego en artifact_cache_dir (la ubicación .aggrega/cache/, ignorada por git, que contiene los artefactos descargados en resoluciones anteriores desde el registro y cuyos subárboles describe el §4). El acierto en la caché a partir del segundo build es lo que mantiene el ciclo interno libre de red incluso cuando el proyecto depende de contenido de catálogo remoto.
Registro. Si el nivel de workspace y caché no devuelve ninguna coincidencia, aggrega pull — o un build ejecutado con --auto-pull o con el ajuste auto_pull del workspace — emite un pull OCI basado en ORAS contra default_registry (por defecto hub.aggrega.ai), desempaqueta el artefacto en la caché para los builds posteriores y continúa con la entidad resuelta. Un build sin ninguno de los dos lee solo lo que fija su lockfile, y se detiene nombrando aggrega pull cuando falta el lockfile. La forma de URI OCI que construye la llamada al registro sigue la taxonomía por tipo de entidad descrita en el §6 (Empaquetado de artefactos & taxonomía OCI). Los URI abreviados en los Aggregates y los Manifests se expanden a su forma OCI completa antes de la llamada al registro; las reglas de inferencia que guían esa expansión están en la referencia URI abreviados sensibles al contexto del Manifest y en el §8 más abajo.
Precedencia y ocultación. La precedencia de resolución es estrictamente ruta local > workspace y caché > registro. Una entidad de un directorio de catálogo local con la misma identidad que una entidad del registro oculta la entidad del registro — esto es intencionado y permite a los autores de catálogos experimentar con modificaciones antes de publicar. La misma ocultación se aplica entre catalog_dirs y la caché: una entidad presente en un directorio de catálogo del workspace tiene preferencia sobre una copia en caché, lo que garantiza que las ediciones locales de un catálogo copiado en el repositorio surtan efecto de inmediato.
Dentro del nivel de workspace y caché, catalog_dirs es una pila de precedencia ordenada en la que gana el primero. Cuando la misma identidad de entidad aparece en más de un directorio de catálogo enumerado, gana el directorio enumerado antes y la aparición posterior queda oculta — reemplazada, no cargada, y no es un error. Esto permite a un proyecto colocar su propio directorio de catálogo por delante de uno compartido o copiado en el repositorio y reemplazar entidades seleccionadas por su identidad, mientras el resto recae en el directorio compartido. El reemplazo es observable: el detalle de la resolución informa qué directorio ganó y cuál quedó oculto, de modo que una superposición nunca es silenciosa. La ocultación solo se aplica entre directorios; dos archivos de un mismo directorio que reclaman la misma identidad son un error de autoría y detienen la carga. Un directorio nombrado más de una vez — por un flag --catalog y en catalog_dirs, o dos veces en la lista — es una sola entrada de la pila, en la que se busca una sola vez en el lugar donde se nombró primero, de modo que una ocultación siempre afecta a dos archivos distintos y nunca a un directorio leído contra sí mismo. Como la precedencia sigue el orden de directorios que controla el autor, el conjunto resuelto es determinista.
El directorio catalog/ de la raíz del workspace se une a esa pila al final, no al principio, y solo cuando el directorio existe — así, cualquier cosa que un proyecto enumere gana sobre él en caso de colisión, y enumerar un directorio no relacionado nunca hace que deje de leerse en silencio. Se omite cuando una entrada enumerada ya lo alcanza, ya que el recorrido de un directorio enumerado es recursivo y una pila que nombra la raíz del workspace ya lo ha leído. Omitir catalog_dirs y escribirlo como una lista vacía son afirmaciones distintas: si se omite, el workspace sigue leyendo catalog/; si se escribe como [], no lee ningún catálogo local, y así es como un workspace declara que no tiene ninguno.
Builds aislados de la red. Establecer offline: true (§4) omite por completo el nivel de registro. Una referencia que no se resuelve en el nivel de ruta local ni en el de workspace y caché produce un error de entidad no encontrada en lugar de intentar en silencio una llamada de red, lo que da a los pipelines de CI que legalmente no pueden acceder a la red un contrato determinista de fallo rápido.
Dónde opera la cascada. La cascada carga la entidad en memoria; los demás mecanismos de resolución construidos encima — la búsqueda de dos niveles type frente a name del Manifest, la coincidencia de versión de implements en tres formas (exacta / rango compatible con la versión mayor / sin versión) descrita en vocabulary/inheritance-and-interface, y la selección de la Recipe por eje según el provider y la instancia del componente — operan sobre entidades que el resolvedor ya ha obtenido a través de esta cascada.
6. Empaquetado de artefactos & la taxonomía OCI (la capacidad como segmento inicial)
Aggrega trata la lógica de infraestructura de la misma forma en que Docker trata las imágenes de contenedor, utilizando los estándares de la Open Container Initiative (OCI) mediante ORAS (OCI Registry As Storage). Los usuarios pueden alojar su catálogo de Aggrega en cualquier registro estándar (GHCR, AWS ECR, Aggrega Hub).
Como las Recipes son estrictamente 1:1 con una capacidad de renderizado — una Recipe nombra una sola capacidad en spec.capability y no puede apuntar a dos —, la forma más limpia de organizarlas en un registro OCI es colocar la capacidad en el segmento inicial del repositorio.
La taxonomía OCI abarca todos los tipos de entidad. El nombre de un repositorio es el segmento del kind — el kind de la entidad, en minúsculas — seguido de la identidad de la entidad, todo en minúsculas:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, editorcore, categoríadatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, editorcore, categoríacomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, editorcore(plano, sin categorías)hub.aggrega.ai/aggregate/core/db-module:1.0.0— Módulo Aggregate reutilizablehub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, capacidadhelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, capacidadhelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, capacidadcomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, capacidadhelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, definiciones de esquema compartidas; elmetadata.nameen PascalCaseAIDatastorespasa a minúsculas en el nombre del repositoriohub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, fragmentos de mapeo Go-template compartidoshub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, tipo de socketprovider(el segmentometadata.pluginType)
Los kinds publicables abarcan los kinds de autoría del catálogo junto con el Aggregate, un módulo reutilizable (publicable tanto si después se referencia como el spec.aggregate de nivel superior de una Release como si se anida en el bloque aggregates: de otro Aggregate), y el Plugin, una referencia direccionada por contenido a un artefacto WebAssembly que el compilador enruta y el runtime ejecuta. El Plugin es un artefacto publicable estructural, no un kind de autoría del catálogo. Release y Manifest son entradas del lado del despliegue que residen en el control de versiones y nunca se suben con push — aggrega push las rechaza —, por lo que no tienen mediatype de publicación. aggrega push --list-kinds informa del conjunto que publica el binario instalado, un kind por línea. Cada kind publicable tiene su propio mediatype OCI en cada una de las dos formas que adopta una publicación:
| Kind de entidad | Publicada como su documento | Publicada con los archivos que declara |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — no declara ningún archivo |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — no declara ningún archivo |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — no declara ningún archivo |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — no declara ningún archivo |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — no declara ningún archivo |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — se publica a través de su propio manifest |
Lo que lleva una publicación, y por tanto su forma, se deriva de lo que la entidad declara — no de su kind, ni de lo que hay en su directorio. Una publicación lleva el documento de la entidad y los archivos que la propia entidad nombra junto a él: el source: local de una Recipe o de una FeatureRecipe — un directorio viaja con cada archivo que contiene y que conservan las reglas de exclusión registradas en su entity.lock —, cada archivo que sus entradas valuesMapping:, workload: y artifacts: importan con $import:, y el entity.lock que escribió su paso de fijación; y cada archivo de esquema que un Component o una Feature importa, incluido cada archivo de una cadena de importación. Nada más del directorio viaja: una nota, un README o la salida de un build junto a la entidad no forma parte de lo que publica, se llame como se llame, y no cambia la forma en que publica. Una entidad que no nombra nada se publica como su documento tal como se escribió, byte a byte, bajo el mediatype +yaml de su kind; una que nombra un archivo se publica como un tar comprimido con gzip del documento y esos archivos, bajo el mediatype +tar+gz de su kind. Un Aggregate, un Plugin y los kinds de biblioteca no declaran ningún archivo junto a su documento, por lo que siempre se publican como el documento — incluido un Aggregate en la raíz de un workspace, ya que cada ruta que declara nombra otra entidad y no un archivo que lleve; lo mismo ocurre con una Recipe cuyo contenido es todo en línea. Un source remoto es una referencia y no un archivo, así que no lleva nada, aunque el entity.lock que registra su fijación convierte a esa Recipe en un archivo comprimido. El segmento de versión de cada mediatype es común a todos los kinds publicables, y el segmento de codificación indica cuál de las dos formas tienen los bytes. Las herramientas posteriores despachan según la cadena completa del mediatype — kind, versión y codificación juntos.
Una forma escrita no nombra ningún directorio que una publicación pueda conocer: un source local escrito como plantilla. Su directorio solo se elige cuando una Release rellena la plantilla, por lo que la entidad lleva cada archivo de su propio directorio que conservan sus reglas de exclusión registradas, para que cualquier directorio que elija una Release haya viajado; aggrega push lo indica cuando ocurre. Llevar solo lo nombrado tiene un coste, y recae en el consumidor: un archivo que una entidad lee y no nombra en ninguna parte no viaja, y es el build de un consumidor — no el push del editor — el que se encuentra con su ausencia, nombrando la ruta que falta dentro de su espacio de caché.
Qué archivos de un directorio de origen pertenecen a la entidad se decide una sola vez, cuando se fija la entidad, y queda registrado. El plugin que sirve la capacidad de la entidad en el workspace del autor declara lo que su ecosistema nunca distribuye — los directorios de control de versiones de un plugin de charts y su respeto del .helmignore de un chart, el .terraform/ de un plugin de módulos — y el .aggregaignore del autor junto a la entidad tiene la última palabra. El paso de fijación registra ese plugin y las reglas compuestas en el entity.lock, y la publicación, cada comparación de las fijaciones del source, la fila de la entidad en el lockfile y el renderizado aplican todos las reglas registradas en lugar de volver a consultar a un plugin, de modo que lo que se publica es lo que renderiza el propio build del autor, y un binding cambiado o un binario más reciente no altera ningún digest hasta que la entidad se vuelve a fijar. El compilador no tiene ninguna opinión sobre ningún ecosistema: las reglas provienen del plugin y del autor, y el compilador solo las aplica. Un enlace simbólico entre los archivos de una entidad se rechaza en lugar de seguirse, ya que aquello a lo que apunta viajaría bajo su nombre. aggrega pin explica las reglas en su totalidad.
El nombre de una Recipe no lleva ni un prefijo de dominio ni la capacidad: el directorio del tipo de entidad y el segmento de la capacidad ya indican ambos.
Convención de nombres: los Components (dominio 2) usan {publisher}/{category}/{name}, y las Features (dominio 2) y los Aggregates reutilizables (dominio 1) usan {publisher}/{name}, donde el segmento publisher nombra al proveedor o autor (core = biblioteca estándar oficial, acme = empresa). Las entidades del dominio 3 (Recipe, FeatureRecipe) usan {capability}/{name}, donde la capacidad es el provider que la entidad declara en spec.capability; una referencia también puede nombrar la entidad sin prefijo, solo con la hoja. Los nombres de Recipe NO incluyen tampoco la capacidad, puesto que ya es el segmento inicial del URI canónico.
Las Recipes utilizan la palabra clave implements para vincularse a la interfaz que cumplen. El campo implements admite coincidencia exacta, por rango compatible con la versión mayor o sin versión (consulta vocabulary/inheritance-and-interface para la coincidencia de versión de implements). La Recipe de una entrada de mapeo del Manifest debe implementar el tipo para el que está mapeada, o una base que ese tipo extends: la clave de la entrada, y el tipo de cada instancia de componente que la clave alcanza en una versión que no nombra, en la versión con la que el build compila esa instancia — de modo que una clave no puede enviar una instancia a una Recipe escrita para otra versión de su tipo.
Cuando un ingeniero de Ops ejecuta aggrega push, la CLI publica la entidad en esa forma, de manera inmutable en su versión. Un consumidor la obtiene a través del modelo de resolución de tres niveles, la almacena localmente en caché en .aggrega/cache/ y dispone lo que lleva en el espacio de caché de la entidad (§4) — los archivos de un archivo comprimido, o solo el documento.
Una entidad descargada lee los archivos que lleva exactamente como los lee junto a ella en un directorio de catálogo. La entidad se lee desde su lugar en ese árbol desplegado, de modo que un source: o un $import: relativo que declara —escrito de forma explícita o producido por una plantilla— se resuelve dentro de lo que se publicó, y una ruta que sale del directorio propio de la entidad se rechaza allí igual que en un directorio de catálogo. Nada fuera del árbol se lee en su lugar: ni el directorio desde el que se ejecuta una build, ni un archivo colocado en la ranura de la caché. Un Component o una Feature cuyo esquema se importa desde un archivo lleva ese archivo, de modo que una copia descargada carga el contrato que se publicó y valida los valores escritos contra él exactamente como lo hace una copia leída desde un directorio de catálogo.
Volver a leer la entidad desde un paquete es el paso inverso, e identifica la entidad por lo que el documento es y no por cómo se llama: el documento en el nivel superior del paquete cuyo kind: es un tipo de entidad publicable. El nombre del archivo de la entidad es una convención del catálogo y no un contrato, de modo que recipe.yaml es lo que escribe el catálogo de la biblioteca estándar y no lo que exige el formato, y un archivo que se lleva junto a la entidad —una plantilla de chart, un fragmento de compose— no se confunde con ella. La regla no puede funcionar al revés, basándose en el tipo que busca el consumidor: un tipo se lee a partir de la entidad, que está dentro del paquete, de modo que en el momento en que hay que abrir el paquete no existe ningún tipo en el que basarse. El lado de lectura se detiene en lugar de elegir cuando el nivel superior de un paquete contiene dos documentos de entidad —el paquete que produce otro cliente al empaquetar un directorio entero que contiene dos entidades, y que quedaría entonces bajo cada una de sus coordenadas publicadas como un único artefacto—. La publicación de este producto no puede producirlo, porque cada entidad lleva solo lo que declara, y además el lado de publicación rechaza un directorio así: cada tipo tiene un directorio propio excepto Aggregate, Release y Manifest, y aggrega pin y aggrega push rechazan una entidad de cualquier otro tipo que tenga otra entidad al lado, mientras que una carga de catálogo, un lint y una build dejan el directorio como está. El nombre de un directorio no se juzga en ninguno de los dos lados: la disposición <name>/<version>/ es la convención del catálogo de la biblioteca estándar.
Una entidad publicada se lee mediante el mismo paso. Una coordenada lleva exactamente una copia de su entidad, en la forma que le dieron sus declaraciones, y una persona la examina con aggrega inspect oci://<registry>/<repository>:<tag> en lugar de mediante una copia legible publicada junto a ella, de modo que no existe una segunda copia que pueda llegar a discrepar de la que resuelve una build. El comando desempaqueta un archivo comprimido según la regla anterior, lee la entidad de un Plugin desde su manifiesto en lugar de desde el ejecutable publicado con él, y muestra el resultado como se muestra un archivo de ese tipo; consulta Leer una entidad publicada.
Anotaciones de manifiesto consultables. Cada publicación estampa un pequeño conjunto de anotaciones consultables en el manifiesto OCI del artefacto, para que un índice de registro o un explorador de catálogo pueda filtrar artefactos por sus metadatos de catálogo sin descargar ni analizar el cuerpo de cada entidad. Cada entidad lleva su descripción legible por personas (la anotación de descripción OCI estándar) más su categoría de catálogo y su tipo. Un Plugin lleva además su tipo de socket y las capabilities que sirve. Estas anotaciones son lo que aggrega registry update vuelve a leer en el índice consultable local (§8).
Cada archivo publicado tiene nombre. Cada archivo que lleva una publicación se nombra en el manifiesto con la anotación estándar org.opencontainers.image.title, que es el nombre con el que un cliente OCI genérico escribe ese archivo cuando descarga el artefacto en un directorio. El nombre dice qué es el archivo, y su extensión sigue el media type del archivo:
| Qué se publica | El archivo que escribe un cliente OCI genérico |
|---|---|
| una entidad publicada como su documento | entity.yaml |
| una entidad publicada con los archivos que declara | entity.tar.gz |
| un Plugin | entity.yaml, la entidad, junto a entity.wasm, su ejecutable |
| una firma adjunta a un artefacto | signature.json |
| un marcador de obsolescencia adjunto a un artefacto | deprecation.json |
un artefacto de datos publicado con aggrega push-artifact | el nombre indicado con --name |
Así, oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server deja la entidad publicada en ./server/entity.yaml, byte a byte tal como se publicó. oras omite un descriptor que no lleva nombre y aun así informa de éxito, por lo que cada descriptor que empaqueta una publicación lleva uno. El nombre se deriva solo del media type, nunca del nombre del archivo que se publicó, de modo que los mismos bytes publicados desde un archivo con otro nombre producen el mismo manifiesto. Una entidad publicada con sus archivos llega como su paquete: entity.tar.gz da nombre al paquete, y la entidad que contiene se encuentra según la regla anterior y no por ningún nombre de archivo. La propia resolución de Aggrega nunca lee estos nombres —selecciona cada archivo por su media type y confía en él por su digest—, así que están ahí para cualquier otro cliente.
7. La arquitectura de la Recipe: punteros y mappers
Consulta entities/recipe para conocer la superficie completa de autoría de la Recipe —source: (puntero), valuesMapping: (mapper, con tres modos de autoría: block scalar inline, $import: de archivo, $import: de biblioteca hacia una entrada de una MappingLibrary), esquemas de origen impulsados por Wasm, compatibilidad nativa con IaC y ejemplos desarrollados.
8. El registro predeterminado y las URI abreviadas sensibles al contexto
Para eliminar el exceso de YAML, el compilador resuelve las URI abreviadas de forma sensible al contexto según la posición del esquema en la que aparecen. El registro predeterminado se configura en .aggrega-config.yaml (con hub.aggrega.ai como valor predeterminado).
Un host de registro tiene una sola lectura. Cada registries[].host se escribe como el propio host —un nombre de host en minúsculas que contiene un punto, localhost, un único nombre seguido de un puerto, una dirección IPv4 o una dirección IPv6 entre corchetes, cada uno con un :port opcional, y sin esquema, ruta, credenciales ni mayúsculas—, porque esa grafía es la clave bajo la que se encuentra cada política de confianza por registro, y el requisito de firma integrado del hub oficial está asociado a hub.aggrega.ai. default_registry nombra un host de la misma manera y puede ir seguido de una ruta de repositorio, como ghcr.io/acme: todo lo que se publica a través del predeterminado acaba entonces bajo esa ruta, y cada referencia corta se resuelve bajo ella, mientras que la confianza sigue decidiéndola solo el host. default_registry puede escribirse en su lugar como el name: de una entrada de registries, y entonces representa el host de esa entrada. El nombre se lee una sola vez, mientras se resuelve la configuración, frente a las entradas vigentes tras cada archivo de configuración y el entorno, de modo que cada lector del predeterminado —la publicación, la vinculación de ubicación, la verificación de firmas y cada consulta de confianza— lee el host de esa única entrada, y ninguno de ellos llega a un host escrito como el nombre; un nombre seguido de una ruta se rechaza, ya que un nombre representa una entrada y no una ubicación. Un nombre se compara antes que una grafía de host, y un nombre que llevan dos entradas se rechaza por ambiguo. La misma lectura decide tres cosas que hace un pull con el host: la ubicación de registro a la que se vincula una identidad de catálogo sin host, si el artefacto descargado nombra siquiera un registro cuya firma se verifica, y contra qué política de confianza se ejecuta esa verificación. Una grafía que podría llegar a un registro sin dar con su política —mayúsculas, un puerto HTTPS predeterminado explícito, un esquema, credenciales, una ruta en el host de una entrada de registries— se rechaza donde se configura, indicando la grafía que se debe escribir, y lo mismo ocurre con un único nombre sin puerto que no nombra ninguna entrada, que es la forma del primer segmento de una identidad de catálogo y no la de un host. El rechazo se aplica en cada capa que puede fijar el valor: el archivo de configuración, donde el esquema establece la misma forma como patrón en cada registries[].host; la variable de entorno AGGREGA_DEFAULT_REGISTRY; y la línea de comandos. Así, cada host que puede nombrar una configuración es uno cuyos artefactos se verifican según la política escrita para él. El host se juzga solo por su grafía; si el nombre se resuelve, o si allí responde un registro, es estado de ejecución que el compilador nunca consulta. configuración detalla las formas aceptadas con ejemplos.
Las URI abreviadas se resuelven de forma sensible al contexto frente al Manifest; consulta ../language-reference/entities/manifest.md §URI abreviadas sensibles al contexto para ver las reglas de inferencia específicas.
Gestión de registros
aggrega registry gestiona los registros que conoce el espacio de trabajo y su política de confianza de firmas. La identidad de un registro es su host; los subcomandos comparten un único modelo de direccionamiento:
aggrega registry add <host>registra un registro y fija su política de confianza, obteniendo la política anunciada por el registro en el primer contacto, salvo que unos flags de confianza proporcionen una manualmente. Un--name <alias>opcional asocia un alias descriptivo a la misma entrada indexada por host: el host sigue siendo la identidad, y el alias se resuelve en él dondequiera que se nombre un registro. Un alias es único entre los registros.aggrega registry listmuestra cada registro configurado —host, alias, un breve resumen de la postura de confianza y un indicador en el predeterminado— en orden ascendente de host. Lee la configuración resuelta y no contacta con ninguna red.aggrega registry remove <name|host>elimina la entrada de política de confianza de un registro, indicada por su host o su alias. Solo elimina la política de confianza: el punterodefault_registryqueda intacto y la capacidad de hacer push a ese host no se ve afectada, de modo que el host vuelve a la confianza predeterminada en lugar de quedar inaccesible. Undefault_registryescrito como el nombre de la entrada eliminada deja de nombrar nada, y se rechaza hasta que se reescriba.aggrega registry updateactualiza el índice consultable local, descrito a continuación.
Dondequiera que se nombre un registro —un argumento de un subcomando registry o el flag --registry de aggrega push y aggrega push-artifact—, el mismo resolvedor interpreta el token: un alias configurado se resuelve en su host, y cualquier otro token se lee como el host que nombra, descartando el esquema, la ruta y las credenciales de una referencia. Donde ese host pasa a ser algo frente a lo que se toma una decisión de firma —el destino de aggrega push o aggrega push-artifact, o la clave bajo la que aggrega registry add escribe una entrada—, se le exige la única lectura descrita arriba y se rechaza, indicando la grafía que se debe escribir, cuando no está escrito así. Un host no registrado que está escrito así es un destino legítimo y se acepta.
El índice consultable local
aggrega registry update [<name|host>] construye un índice consultable local de los registros que conoce el espacio de trabajo. Recorre los repositorios de cada registro configurado, selecciona la versión publicada más alta de cada uno, lee las anotaciones de manifiesto consultables de esa versión (§6) y escribe un índice por registro en la caché de artefactos. Sin argumentos indexa cada registro configurado; con un único argumento de registro (un host o un alias) indexa solo ese.
El índice sigue el modelo de actualización explícita habitual en los gestores de paquetes: registry update es el comando que contacta con los registros, y un aggrega search posterior lee sin conexión el índice escrito. El archivo de registros de un registro es determinista: dos actualizaciones frente al mismo estado del registro producen bytes idénticos, y la marca de tiempo de actualización vive en un archivo contiguo para que nunca altere los registros. Un repositorio sin ninguna versión publicada, o que no se puede leer, se omite, de modo que un solo repositorio ilegible nunca hace abandonar el índice entero.
La instantánea publicada del catálogo
Cada publicación del catálogo de la biblioteca estándar publica también el catálogo completo: un único artefacto OCI, un tar comprimido con gzip de todos los archivos que contiene el árbol del catálogo en el commit que publicó esa publicación, en catalog/snapshot bajo el registro en el que se publica el catálogo —hub.aggrega.ai/catalog/snapshot para el hub oficial. Solo se envía después de que todas las entidades de esa publicación estén en el registro, de modo que no nombra ninguna entidad que el registro no contenga. Se etiqueta con el commit a partir del cual se construyó y con latest, y el publicador lo firma sin clave, como cada entidad de la publicación, de modo que la identidad del publicador lo verifica según la política de confianza del registro; latest pasa a una instantánea solo una vez que está firmada. El archivo comprimido se escribe con una única disposición fija —entradas en orden ascendente de sus nombres, cada una con el mismo modo, propietario y hora de modificación—, de modo que un mismo commit produce siempre el mismo tar.
Su único lector es una importación cuyo workspace no nombra ninguna carpeta de catálogo: ni workspace.catalog_dirs, ni AGGREGA_CATALOG_DIRS, ni un directorio catalog/ en la raíz del workspace. aggrega import, la importación de la sesión del editor y la herramienta de importación del asistente ejecutan la misma operación, de modo que cada uno obtiene la instantánea de la misma forma. La importación la descarga del registro predeterminado del workspace a través del mismo control de tráfico de salida y el mismo inicio de sesión que un pull, verifica su firma según la política de confianza de ese registro antes de conservar nada, la guarda en la caché de artefactos del workspace y la lee allí como una carpeta de catálogo, sujeta a su digest —así, al importador se le ofrecen los Components del catálogo, y --target genera como borrador un Manifest a partir de sus Recipes, exactamente por el camino que sigue una carpeta de catálogo. La constancia que la importación escribe junto a sus borradores identifica la instantánea por el digest de su manifiesto, de modo que una importación posterior de los mismos borradores lee el mismo catálogo sin ninguna solicitud, y aggrega import --upgrade descarga la instantánea más reciente e importa frente a ella a partir de ese momento. En modo sin conexión, una importación que tendría que descargar una instantánea se detiene, nombrando lo que hay que ejecutar. Un workspace que nombra una carpeta de catálogo importa frente a ella y no descarga ninguna instantánea. Ningún otro comando lee la instantánea: un pull, una build y una validación resuelven cada entidad a través de los niveles del §5 y la fijan en el lockfile, y los borradores de una importación hacen referencia a las entidades del catálogo por su nombre, de modo que compilarlos resuelve esas entidades de la misma forma.
9. Fijación mediante lockfile e inmutabilidad de los artefactos
La disciplina de fijación mediante lockfile ancla cada dependencia a un artefacto concreto direccionable por contenido. En la primera resolución del lockfile (aggrega pull), el resolvedor consulta el registro, elige una versión según la restricción de tres formas de la URI (exacta / rango / sin versión) y escribe la versión fijada + el digest en el <release-stem>.lock de la Release. Las invocaciones posteriores de aggrega build usan los valores fijados independientemente de la mutabilidad del registro; se pueden publicar nuevas versiones sin afectar al lockfile existente.
El modelo de fijación lleva consigo una regla fundamental: una vez que un name:version se publica en un registro y se resuelve en el digest D, esa correspondencia es permanente. Volver a publicar el mismo name:version con contenido distinto se rechaza en el momento del push. El propio aggrega push lo impone en cada publicación: resuelve el artefacto existente en name:version en el registro de destino; si está presente y el digest coincide con el contenido que se va a enviar, el push no sube nada y solo adjunta lo que aún le falta a esa publicación —su fecha de publicación, y su firma donde el push firma—; si está presente y el digest difiere, el push se detiene con un error de violación de inmutabilidad que cita ambos digests.
La inmutabilidad importa por dos consecuencias:
- Las fijaciones del lockfile son fiables. Cuando el lockfile registra
mariadb:1.0.0con el digestD, una build que descarga por digest recibe los bytes deD. Sin inmutabilidad, una modificación en el lado del registro podría sustituir los bytes deDpor debajo de la fijación del lockfile, socavando la estabilidad entre el momento del bloqueo y el de la build. Las builds reproducibles se basan en esta garantía. - Los cambios de metadatos posteriores a la publicación tienen una vía clara. Marcar una versión publicada como obsoleta, rotar claves de firma o modificar atestaciones no puede hacerse modificando el artefacto publicado (la regla lo prohíbe). Debe hacerse publicando una nueva versión de parche o un artefacto sidecar que registre por separado el cambio de metadatos. Ambas vías son auditables —una nueva versión o un sidecar aparece como una entrada distinta del registro— y ninguna altera los bytes del artefacto original.
La regla de inmutabilidad se aplica de manera uniforme a todo artefacto de Aggrega publicado en OCI (entidades, SchemaLibrary, MappingLibrary, plugins Wasm referenciados por el pipeline[].plugin: de una Recipe / el pipeline[].plugin: de una FeatureRecipe / el plugins.{governance,linter,importer}[]: de la configuración del espacio de trabajo). Todo lo que está fijado por name:version más un digest de contenido en el lockfile está sujeto a la inmutabilidad.
La inmutabilidad es incondicional, y ninguna configuración la relaja. No existe ningún flag ni ningún ajuste de la configuración del espacio de trabajo que permita una sobrescritura, porque el registro no expone ninguna vía de sobrescritura que un operador pueda activar. El contenido que ha cambiado se publica con una nueva versión, y aggrega lint --pre-publish verifica que el incremento de versión coincida con la clasificación del cambio.
Volver a resolver hacia una versión más reciente requiere una acción explícita del usuario: aggrega pull --upgrade --release <release> <uri> vuelve a resolver una sola dependencia manteniendo todas las demás fijaciones, y aggrega pull --upgrade --release <release> vuelve a resolver todas las dependencias frente al estado actual del registro. Las dependencias en forma de rango y sin versión se vuelven a resolver hacia la última versión que coincida; las fijaciones en forma exacta no se mueven a menos que el usuario actualice explícitamente a otra versión exacta. El lockfile es la fuente de verdad para las builds; la forma escrita por el usuario expresa la restricción de versión en el momento de la autoría.
10. Aplicación de la forma de los nombres de las entidades de catálogo
Los nombres de las entidades de catálogo siguen patrones por tipo de entidad, enumerados a continuación y detallados por tipo en la Visión general de la referencia de entidades. Son una superficie distinta de los nombres de instancia que un desarrollador escribe en un Aggregate o en una Release, que comparten un único patrón sea cual sea el tipo; ese patrón está en ../language-reference/02-naming-conventions.md «Nombres de instancia». El campo metadata.name que declara un YAML de catálogo no siempre es idéntico a la URI de referencia canónica de la entidad: Component y Feature incorporan los segmentos de publicador y de agrupación directamente en metadata.name; Recipe y FeatureRecipe declaran un metadata.name formado solo por la hoja, y su URI canónica de dos segmentos combina esa hoja con la spec.capability que declara la entidad; cada tipo de biblioteca declara un token PascalCase en metadata.name.
Formas por tipo de entidad:
- Component — tres segmentos kebab-case
{publisher}/{category}/{name}declarados enmetadata.name. Ejemplo:core/datastore/postgres. - Feature — dos segmentos kebab-case
{publisher}/{name}declarados enmetadata.name. Ejemplo:core/data-masking. - Recipe — una única hoja kebab-case en
metadata.name(p. ej.,postgres). La URI de referencia canónica{capability}/{name}(según el §6 anterior) combina laspec.capabilitydeclarada de la entidad con esa hoja; el segmento inicial se compara conspec.capability, no con la ubicación de la entidad en el disco, de modo que mover unrecipe.yamlno cambia cómo se referencia. El catálogo de la biblioteca estándar coloca la entidad en<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlpara que el árbol refleje la coordenada, pero ese reflejo es una convención del catálogo y no el origen de la URI. Una referencia también puede nombrar la receta sola —solo la hoja, sin segmento de capability—, que es la forma predominante en la práctica y se resuelve siempre que una sola receta del catálogo lleve ese nombre. En una URI de Recipe no aparece ningún segmento de publicador, y una referencia que lleva un tercer segmento no coincide con ninguna receta. - FeatureRecipe — una única hoja kebab-case en
metadata.name(p. ej.,k8s-secret-from-parameter), simétrica con la Recipe: URI canónica{capability}/{name}a partir de laspec.capabilitydeclarada más la hoja, la hoja sola aceptada de la misma manera, y el árbol<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlque refleja la coordenada por convención. - Los tipos de biblioteca — SchemaLibrary, MappingLibrary, WorkloadLibrary y ArtifactLibrary — un único token PascalCase en
metadata.nameque coincide con^[A-Z][A-Za-z0-9]*$(p. ej.,BaseComponents,AIDatastores,BaseWorkloads). La forma es la misma en todos los tipos de biblioteca, de modo que mover una entrada entre bibliotecas nunca implica renombrarla según una convención distinta. El envoltorio JSON Schema de cada tipo de biblioteca también declara el patrón, además de la comprobación descrita a continuación.
Para Component, Feature, Recipe y FeatureRecipe, el JSON Schema de metadata.name acepta cualquier cadena no vacía, de modo que nada de la forma es estructural para esos tipos. Cada forma documentada —incluidos los tipos de biblioteca, cuyos envoltorios también declaran su patrón— la comprueba el plugin de disciplina de publicación, que lleva los patrones como fuente de verdad en forma de regex compartida con la distribución del compilador. Aquí no se asigna a ningún tipo una forma que luego el plugin ignore.
La comprobación es opcional: un solo comando la realiza, y solo se ejecuta cuando un autor la solicita. Los dos comandos que con más frecuencia se supone que la realizan no lo hacen:
aggrega lintinforma de las infracciones de forma de los nombres. El plugin compara elmetadata.namede cada entidad con el patrón de su tipo. La comprobación se ejecuta cuando un autor invocaaggrega lint—sobre una sola entidad, sobre el cierre de dependencias de una Release con--release, o sobre cada entidad del catálogo cuando se invoca sin argumentos—, y el mismo conjunto de reglas es accesible desde la superficie de herramientas orientada al editor que expone la CLI. Los hallazgos son orientativos: se informan con gravedadwarny no detienen nada.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)El hallazgo empieza con su gravedad y el código corto con el que está registrada su regla, que aggrega explain E0278 desarrolla. La ruta del archivo afectado se imprime encima del hallazgo, y una ejecución sobre todo el catálogo termina con un recuento de las entidades comprobadas y de los hallazgos orientativos generados.
aggrega buildno comprueba la forma de los nombres. La salida renderizada no depende de los nombres de las entidades de Aggrega, de modo que una build sobre un catálogo con nombres no conformes no emite ninguna advertencia ni ningún diagnóstico, y tiene éxito exactamente como lo tendría de otro modo.aggrega pushtampoco comprueba la forma de los nombres. La publicación rechaza por otros motivos, sobre todo por la regla de inmutabilidad anterior, según la cual volver a publicar unname:versionexistente con contenido distinto se detiene. Cuando un rechazo nombraaggrega lint --pre-publish, le está indicando al autor qué comando ejecutar; el push no lo ejecuta.
Como ni la build ni la publicación comprueban la forma, un catálogo que quiere que se respete la convención ejecuta aggrega lint de forma deliberada, en un hook de pre-commit o como paso de un pipeline. Ten en cuenta que un hallazgo de forma de nombre es orientativo: aggrega lint lo informa y aun así termina con éxito, de modo que un pipeline que quiera condicionar su avance a la convención lee los hallazgos informados en lugar de basarse en el código de salida.
Una política por espacio de trabajo suprime la regla:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseCon la política establecida, la regla de forma de los nombres no informa de nada en absoluto. También puede establecerse para una sola invocación con aggrega lint --allow-nonstandard-names, o forzarse de nuevo a desactivada con --no-allow-nonstandard-names. Los usos legítimos son catálogos que nunca se publicarán, experimentos con varios publicadores y entidades de propósito especial.
11. Expansión de Feature guiada por anotaciones
El bloque mappings.features.annotations del Manifest declara vinculaciones entre claves de anotación y tipos de Feature, además de una tabla de enrutamiento agrupada por pilar (maps.infra, maps.values) que nombra las propiedades del esquema de la Feature que cada anotación puede rellenar. La subfase de expansión de anotaciones de la resolución recorre los límites de la Release de fuera hacia dentro y los subsistemas del Aggregate de fuera hacia dentro, calcula los conjuntos efectivos de anotaciones por componente mediante cascada y sobrescritura con exclusión null del valor completo y por subclave, e inyecta vinculaciones sintéticas de Feature que llevan origin: annotation en su procedencia IR. La explicación completa de la forma de las vinculaciones y de la autoría está en language-reference/entities/manifest.md y language-reference/providers/well-known-annotations.md; esta sección documenta los mecanismos en tiempo de carga del catálogo y en tiempo de inspección en los que se apoya la ruta de expansión.
Caché de compilación de esquemas. El spec.schema.{infra,values} de cada Feature se compila una vez por build y se reutiliza entre los recorridos en cascada. La validación de tipos repetida por subclave frente al mismo esquema de Feature (un ámbito de cascada por componente, para cientos de componentes) lee el esquema compilado en lugar de compilarlo de nuevo. No se conserva nada entre builds, por lo que el siguiente build vuelve a compilar desde cero un esquema de Feature modificado.
Validación de los destinos de vinculación (carga del catálogo). Al cargar el catálogo, el compilador recorre cada vinculación features.annotations del Manifest y verifica que cada ruta con puntos declarada bajo maps.infra y maps.values corresponda a una propiedad que el spec.schema.<pillar> de la Feature referenciada declare realmente. Una vinculación que enruta hacia una ruta que el esquema de la Feature no enumera detiene la carga del catálogo con un OPS_ERROR claro que nombra la clave de la vinculación, la ruta que falta, la URI de la Feature y la ubicación en el código fuente.
Lint de solapamiento de pilares del esquema (carga del catálogo). Se emite una advertencia orientativa cuando el spec.schema de una Feature declara el mismo nombre de propiedad en ambos pilares, infra y values. El solapamiento rara vez es intencionado: propiedades con el mismo nombre en distintos pilares confunden la intención de autoría (¿qué pilar se activa cuando una anotación apunta al nombre compartido?) y complican los mensajes de diagnóstico. La advertencia no es bloqueante y no admite exclusión: un autor que pretende el solapamiento lo mantiene junto con la advertencia, y uno que no lo pretende renombra la propiedad en un pilar.
Lint de solapamiento de mapas de vinculación (resolución). Se emite una advertencia orientativa cuando una ruta de subclave aparece tanto bajo maps.infra como bajo maps.values en las vinculaciones del Manifest. Una ruta que aparece en ambas listas de pilares es incoherente: una única subclave de anotación no puede enrutar a ambos pilares simultáneamente, y el desempate determinista que aplica el compilador (una ruta presente en ambas listas se enruta a infra; una anotación escrita en el Aggregate solo puede enrutarse a través de values, así que una escrita allí para esa ruta se rechaza) es una red de seguridad, no una forma de autoría prevista. La advertencia no es bloqueante; los autores que ejecutan ignorando la advertencia obtienen igualmente un build limpio, con el desempate visible en la procedencia IR.
Representación de la procedencia en aggrega inspect. El comando inspect muestra un corchete por cada vinculación de Feature que registra el origen de cada hoja rellenada:
[explicit]— la Feature se vinculó explícitamente mediante un bloquefeatures:de un Aggregate o de una Release.[annotation: <key> from <source>]— cada hoja rellenada proviene de la misma clave de anotación. El corchete nombra la clave y dónde se declaró la anotación: el archivo y la ruta de clave con puntos dentro de él.- Corchetes por hoja — composición entre lados en la que cada hoja rellenada se muestra con su propio corchete de origen (algunas
[explicit], algunas[annotation: <key> from <source>]). Esta forma hace visible la fusión en la que lo explícito gana campo a campo: cuando una vinculación explícita y una contribución de anotación apuntan a la misma instancia de Feature en el mismo Component pero escriben hojas distintas, ambas contribuciones se mantienen en sus respectivas hojas y la salida de inspect nombra individualmente el origen de cada hoja.
La representación de inspect lee los mapas por pilar values_provenance e infra_provenance de la IR —rellenados durante la expansión de anotaciones junto con la inyección de las vinculaciones sintéticas— y emite la forma de corchete que mejor resume el origen colectivo de las hojas. El mecanismo de inspect es la superficie de introspección canónica para entender por qué una determinada vinculación de Feature acabó en un determinado Component y de dónde proceden sus valores.