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

Manifest

El papel conceptual de la entidad Manifest (Dominio 4 — la tabla de mapeo que vincula interfaces abstractas a Recipes concretas) se describe en architecture/04-entity-taxonomy.md. Esta página cubre la superficie de autoría del Manifest: cómo se sitúa junto a la Release, la forma del mapeo de URI planos, la composición mediante extends, las reglas de abreviatura de URI, los enlaces de Feature basados en anotaciones y el prefijo aggrega.ai/ reservado por la plataforma.

Manifest frente a Release: separación de responsabilidades

El Manifest y la Release tienen responsabilidades que no se solapan:

  • El Manifest dicta qué Recipe realiza cada tipo del catálogo y, a través del spec.capability de esa Recipe, el provider (p. ej., Helm, Helm-chart, Compose) que lo renderiza. Es la tabla de mapeo — un registro por proyecto, confirmado en Git, de qué Recipe concreta implementa cada interfaz abstracta; las versiones y los digests a los que una compilación ata esas Recipes se fijan por separado, en el lockfile de cada Release.
  • La Release dicta el destino (p. ej., la carpeta de salida física para la generación de artefactos GitOps). Es el enrutador del despliegue — una descripción por entorno de dónde terminan los artefactos compilados.

El esquema de la Release no tiene ningún campo provider en ningún nivel de anidamiento; el despacho del provider pertenece exclusivamente al Manifest.

La ruta de compilación. Cuando un usuario ejecuta aggrega build --release release.yaml, el compilador resuelve los artefactos físicos combinando ambas fuentes:

  1. Leer el destino. El compilador recorre las fronteras de la Release — por ejemplo, la frontera ovh-cluster-3 contiene el componente user-db (tipo: core/postgres:1.0.0).
  2. Examinar el Manifest. Abre el Manifest al que apunta la Release mediante su campo manifest:.
  3. Búsqueda en dos niveles. Comprueba primero el nivel name para "user-db". Si no lo encuentra, comprueba el nivel type para "core/postgres:1.0.0" (con versión) y luego "core/postgres" (sin versión).
  4. Resolver la Recipe. El valor de la entrada coincidente es un URI de Recipe; la Recipe que nombra declara en spec.capability qué provider la renderiza.
  5. Generación de la salida. El compilador conoce ahora la carpeta de destino (dist/boundaries/ovh-cluster-3/), el provider (renderizado de Helm mediante Wasm) y el artefacto (el código fuente de la Recipe). Las fronteras GitOps ahead-of-time se respetan de extremo a extremo.

Mapeo plano de URI

El bloque mappings: del Manifest es un mapa plano de URI de tipo de componente a URI de Recipe (y de URI de tipo de funcionalidad a URI de FeatureRecipe). El mapeo es agnóstico respecto a la capacidad en el nivel del Manifest; la determinación de la capacidad deriva del campo spec.capability de cada Recipe resuelta en el momento del renderizado, no de la forma estructural del Manifest. El bloque organiza los mapeos bajo dos claves de nivel superior:

  • components.type asigna un URI de tipo de componente a un URI de Recipe. Cada instancia de componente del tipo declarado se resuelve en la Recipe especificada. El mapeo es uno a uno por tipo de componente. Una clave que no nombra el tipo exacto de una instancia la alcanza igualmente por la base del tipo, cuando ninguna clave nombra ese tipo exacto y no hay otra clave escrita para la misma base — así, una clave escrita sin versión (core/postgres), o una que nombra otra versión (core/postgres:1.0.0), puede alcanzar una instancia de core/postgres:2.0.0 —, pero la Recipe que nombra debe implementar la versión propia de cada una de esas instancias: una instancia de core/postgres:2.0.0 alcanzada de ese modo y asignada a una Recipe que declara implements: core/postgres:1.0.0 detiene el build. Asigna esa instancia, con una clave que nombre su versión (core/postgres:2.0.0), a una Recipe que la implemente.
  • features.type asigna un URI de tipo de funcionalidad a un URI de FeatureRecipe. Cada vinculación de Feature del tipo declarado se resuelve en la FeatureRecipe especificada. Las Features de credenciales (etiquetadas con feature.aggrega.ai/kind: secret) residen en el mismo mapa features.type que las Features operativas — el modelo unificado de entidad Feature.

Cada bloque acepta también un nivel name junto a type, que asigna un nombre de instancia concreto a un URI de Recipe (o de FeatureRecipe). El nivel de nombre tiene prioridad sobre el nivel de tipo: una instancia nombrada en components.name se resuelve en esa Recipe, mientras que todas las demás instancias del mismo tipo se resuelven mediante components.type. Esto expresa una sustitución por instancia — dos instancias de un mismo tipo de componente pueden desplegarse mediante dos Recipes distintas (por ejemplo, la mayoría de las instancias de base de datos usan la Recipe asignada en bloque mientras que una instancia queda fijada a una implementación física distinta), sin bifurcar el tipo de componente ni duplicar el Manifest. La sustitución se aplica de forma uniforme: la instancia nombrada se renderiza mediante la Recipe de sustitución y también fija su origen a partir de ella. features.name es el nivel simétrico para las vinculaciones de Feature, indexado por el nombre propio de la vinculación — la clave bajo la que está escrita en el features: de un componente —, nunca por el nombre del componente al que está vinculada. El ejemplo de sustitución de receta por instancia recorre de principio a fin un caso mínimo con dos instancias.

Una vinculación que lleva una conexión se indexa por el nombre que adopta en el componente consumidor: <alias>.<slot>, el alias bajo el que está escrita la conexión, un punto y la ranura que ocupa la vinculación (consulta la entrada de conexión del Aggregate). Así, la credencial de una conexión puede materializarse de forma distinta a cualquier otra vinculación de su tipo:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

La entrada se fija y se verifica como cualquier otra entrada del nivel de nombre, como describe el párrafo siguiente. La Feature que nombra la vinculación también se fija y se verifica, exactamente igual que la Feature de una vinculación escrita en el propio componente, bajo la entrada de conexión que escribió su autor — consulta El lockfile.

Una clave name tiene que nombrar algo que el build contiene. El nivel se compara por nombre exacto, de modo que una clave components.name que no es una instancia de componente del build, o una clave features.name que no es una vinculación en él — casi siempre el nombre del componente en el que está una vinculación, escrito donde corresponde el nombre propio de la vinculación —, no sería consultada por nada, y las instancias a las que iba destinada se resolverían silenciosamente mediante el nivel type. En su lugar, el build se detiene ante esa clave, antes de renderizar nada, nombrando el Manifest, la clave, los nombres de ese tipo que el build sí contiene y el nombre que probablemente querías indicar — consulta A Manifest name mapping names nothing in the build (Un mapeo por nombre del Manifest no nombra nada en el build).

Una materialización vinculada por nombre se fija y se verifica igual que una vinculada por tipo. aggrega pull obtiene cada Recipe y FeatureRecipe que vincula cualquiera de los dos niveles — desde un directorio de catálogo, la caché o un registro — y registra cada una en el lockfile de la Release con su versión resuelta y su digest de contenido, bajo la entrada de mapeo que la vincula: manifest.spec.mappings.components.name.<instance> para una entrada del nivel de nombre, junto a manifest.spec.mappings.components.type.<type> para una del nivel de tipo. aggrega build sujeta cada una de ellas a su fijación. Un lockfile que no registra ninguna fila para una materialización que el Manifest vincula detiene el build por estar desactualizado, nombrando la materialización y la entrada que la vincula; una materialización cuyo contenido ha cambiado desde el pull lo detiene del mismo modo, nombrando ambos digests. En ambos casos, aggrega pull --release <release> registra la materialización tal como está ahora. Al igual que una entrada type, una entrada name se fija tanto si la Release declara una instancia con ese nombre como si no, de modo que una entrada name que nombra una Recipe que ningún catálogo ni registro contiene detiene el pull; una entrada name que no nombra ninguna instancia que el build contenga también se fija, y detiene el build como describe el párrafo anterior.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Determinación de la capacidad en el momento del renderizado. La entrada del Manifest vincula un tipo de componente a un URI de Recipe. Un URI de Recipe tiene como máximo dos segmentos — una capacidad inicial opcional y luego el nombre de la receta — más un :version opcional; el resolvedor divide solo en la primera /, de modo que una referencia con un tercer segmento no nombra ninguna receta y detiene la resolución. En el momento del renderizado, el resolvedor carga la Recipe mediante una búsqueda directa por URI en el lockfile y el catálogo, y el campo spec.capability de cada Recipe determina la agrupación de despacho por (ruta, capacidad). La forma estructural del Manifest sigue siendo plana, independientemente de cuántos proveedores admita el catálogo en general.

Búsqueda directa por URI

El valor de mapeo del Manifest es un URI de Recipe. El compilador resuelve el URI directamente contra el lockfile y el catálogo, y devuelve la Recipe correspondiente. No itera sobre las declaraciones spec.implements para encontrar una Recipe que «implemente» un tipo de componente. Cada entrada del Manifest vincula el tipo de componente escrito por el desarrollador a un URI de Recipe concreto; la elección es explícita e inequívoca en el contenido del Manifest.

spec.implements es una comprobación de coherencia sobre la tabla de mapeos. El valor spec.implements de la Recipe resuelta DEBE coincidir con la clave de tipo de componente del Manifest para esa entrada de mapeo — o con una base que esa clave extiende mediante extends, a cualquier profundidad de la cadena, ya que una Recipe escrita para una base implementa todo lo que la extiende. Un valor que no coincide con ninguna de las dos produce un OPS_ERROR con un diagnóstico claro que nombra la entrada del Manifest, la Recipe resuelta y el valor spec.implements en conflicto. La comprobación se ejecuta una vez por entrada de mapeo del Manifest, sobre el Manifest compuesto y antes de que se resuelva ninguna Recipe — estática, determinista y sin recorrer nada más allá de la propia cadena extends del tipo mapeado. Una clave components.type que alcanza una instancia de componente en una versión que no nombra se juzga una vez más para esa instancia, del mismo modo, con el tipo propio de la instancia, en la versión con la que el build la compila, en el lugar de la clave, como describe Mapeo plano de URI. Consulta ../vocabulary/inheritance-and-interface.md para saber qué le ahorra y qué no le ahorra la Recipe de una base a una especialización.

Todo comando que lee las dependencias de una Release la ejecuta, y cada uno decide por sí mismo qué significa un hallazgo: aggrega build y aggrega pull se detienen, ya que ambos producen algo que usarías a continuación, mientras que aggrega validate y aggrega lint lo informan junto con el resto de sus hallazgos y terminan con un código distinto de cero, y el editor lo publica como un diagnóstico más entre los demás. aggrega lint es la excepción en el juicio de una instancia: juzga las entradas de mapeo y no las instancias que estas alcanzan, así que no lo informa, mientras que aggrega build, aggrega pull y aggrega validate --release sí lo hacen. Consulta ../errors/fatal-halts.md para ver el diagnóstico y cómo corregirlo.

La comprobación de coherencia es la única superficie de mapeo que lee la cadena extends. La selección de la Recipe sigue siendo exacta sobre la clave de mapeo: un tipo de componente que extiende una base mapeada sigue necesitando aquí su propia entrada, y no obtiene ninguna por herencia.

spec.implements también sugiere candidatas. Una instancia cuyo tipo no tiene ningún mapeo en el Manifest detiene el build con un OPS_ERROR que enumera como candidatas para fijar las recetas cuyo spec.implements puede implementar ese tipo; el autocompletado del editor sobre un valor de mapeo sitúa primero esas mismas recetas coincidentes. Ambas superficies leen spec.implements frente al propio tipo solicitado, de modo que una receta que implementa una de las bases de ese tipo no se ofrece como candidata aunque el mapeo se consideraría coherente. Así, spec.implements declara lo que una receta puede implementar e informa la elección de la persona — en la comprobación de coherencia, en el diagnóstico de falta de mapeo y en el autocompletado —, pero nunca resuelve un build. El mapeo del Manifest es la elección de despliegue explícita del usuario, fijada en el lockfile para la reproducibilidad; el catálogo nunca elige un despliegue en nombre del usuario.

Tres formas para el segmento de versión del URI

Un URI de Recipe en el Manifest puede llevar la versión en cualquiera de tres formas:

  • Exacta — helm/postgres:1.2.0. El lockfile debe fijar exactamente esta versión; en la primera resolución del lockfile, el resolvedor fija esta versión; si el catálogo o el registro no contiene esta versión en el momento de la resolución, la carga del espacio de trabajo se detiene con un error.
  • Rango — helm/postgres:^1.2.0. Rango semver con la regla MVS estándar; en la primera resolución del lockfile, el resolvedor fija la versión disponible más alta que satisface el rango.
  • Sin versión — helm/postgres. Sin sufijo :version; en la primera resolución del lockfile, el resolvedor fija la última versión disponible.

Los builds posteriores usan la versión fijada en el lockfile, independientemente de la forma que escribió el usuario. Volver a resolver a 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, o aggrega pull --upgrade --release <release> las vuelve a resolver todas —; el lockfile es la fuente de verdad para los builds; la forma que escribe el usuario es la manera en que expresa la restricción de versión al escribir.

Referencias calificadas por capacidad

La identidad de una Recipe en el catálogo tiene ámbito de capacidad: dos recetas pueden compartir un metadata.name y una versión y declarar valores de spec.capability distintos. La identidad en el registro es recipe/{capability}/{name}:{version}, derivada del tipo de la receta, de su spec.capability sin ninguna fijación de versión que lleve, y de su nombre; el árbol del catálogo de la biblioteca estándar refleja esa coordenada en recipe/{capability}/{name}/ por convención. Un valor de mapeo del Manifest nombra la receta con cualquiera de las dos precisiones:

  • Simple — mariadb:1.0.0. Se resuelve cuando exactamente una receta del catálogo lleva ese nombre; la forma predominante en la práctica.
  • Calificada por capacidad — compose/mariadb:1.0.0. El segmento anterior a la primera / nombra el spec.capability de la receta, sin su fijación de versión — una fijación escrita en la referencia se rechaza (E0095). Obligatoria cuando más de una receta publica el mismo nombre: una referencia simple que coincide con dos recetas es ambigua y se detiene de forma explícita en la resolución en lugar de elegir una en silencio.

Un URI de Recipe no tiene más posiciones. El resolvedor divide solo en la primera /, de modo que compose/mariadb nombra la capacidad compose y la receta mariadb, y una referencia de tres segmentos no coincide con ninguna receta en ninguna de las dos precisiones.

Las formas del segmento de versión anteriores se aplican a ambas variantes.

Entidades publicadas en un registro en los mapeos

Una entidad consumida desde un registro en lugar de un catálogo local se referencia exactamente con la misma identidad que usa una local: la referencia no lleva ningún host de registro ni ningún segmento de tipo de entidad. El resolvedor aporta ambos — el host a partir del registro predeterminado configurado en el espacio de trabajo, el segmento de tipo a partir del lugar donde está la referencia en el esquema — según las reglas de URI abreviados sensibles al contexto que se describen más abajo. Cuando ni un directorio de catálogo local ni la caché contienen una copia, aggrega pull — o un build ejecutado con --auto-pull — obtiene la entidad de la ubicación derivada, la guarda en caché y fija la versión resuelta y el digest de contenido en el lockfile; los builds posteriores consumen la caché sin acceso a la red.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Como el host y el segmento de tipo de entidad se derivan en lugar de escribirse, escribir cualquiera de ellos en la referencia no apunta a la entidad publicada — produce una identidad que ninguna entrada del catálogo lleva. Una referencia a un Component o a una Feature es su metadata.name literal más un :version opcional, tanto si la entidad se resuelve desde el catálogo local como desde la caché o desde un registro. Un espacio de trabajo que consume un registro privado nombra ese host en su propia configuración en lugar de en cada referencia.

Comprobación de completitud

Una vez resueltos todos los mapeos, el compilador verifica que cada instancia de componente y de vinculación (una Feature de credenciales es una vinculación como cualquier otra) en el Aggregate del desarrollador tenga una Recipe o una FeatureRecipe resuelta. Las entidades sin mapear provocan una detención fatal con un diagnóstico explícito que enumera cada entidad ausente y sugiere qué clave components.type o features.type añadir para cubrir el hueco.

Anclas YAML para manifiestos DRY

Para evitar que el YAML se infle en grandes conjuntos de mapeos, el Manifest admite un bloque defs: opcional para anclas YAML estándar (& y *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Negociación de Feature

El intercambio de capacidades usa el mismo mapeo plano de URI:

  1. El desarrollador vincula core/data-masking a un componente en el Aggregate, bajo un nombre propio en el mapa features: de ese componente.
  2. El compilador busca core/data-masking en el mapa features.type del Manifest.
  3. Si la búsqueda se resuelve en un URI de FeatureRecipe (p. ej., helm/data-masking-litellm:1.0.0), la capacidad existe y el pipeline de la FeatureRecipe se ejecuta en el orden definido.
  4. Si features.type no contiene ninguna entrada coincidente, el compilador detiene el build y enumera la Feature sin mapear.

El Manifest también acepta un bloque features.annotations — una superficie de autoría paralela que permite a un subsistema de una Release o de un Aggregate vincular Features por clave de anotación en lugar de por declaración por componente. La forma de la vinculación, la partición side-vs-pillar que determina qué superficie de autoría usa qué rutas de enrutamiento, la disciplina según la cual gana la vinculación explícita y la regla de valores predeterminados del esquema se encuentran en la sección dedicada Vinculaciones de Feature guiadas por anotaciones más abajo.

Composición mediante extends

Un Manifest puede declarar una única referencia extends: que nombra un Manifest base cuyos mappings hereda. La referencia no es un URI y nunca se resuelve a través del catálogo: un Manifest pertenece al lado del despliegue, se escribe junto a la Release en lugar de publicarse, por lo que el valor es o bien una ruta relativa a un archivo de Manifest — ./base-manifest.yaml — o bien el metadata.name sin más de un Manifest situado en el propio directorio de la Release. Una ruta relativa debe llevar a un Manifest dentro del workspace — o, cuando la Release se indicó fuera del workspace (en la línea de comandos o mediante la configuración del workspace), dentro del directorio que contiene esa Release, y para un Manifest que indiques por sí solo en la línea de comandos fuera del workspace, dentro del directorio que contiene el Manifest: una ruta que sale subiendo, o que un enlace simbólico lleva fuera, se rechaza antes de leer el archivo que nombra (consulta errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Una referencia a otro archivo sale del directorio en el que debe permanecer)”). Los mappings hijos sobrescriben los de la base en caso de colisión de claves, lo que admite patrones de superposición por entorno (paridad staging/prod con diferencias quirúrgicas por entorno) y patrones de desarrollo local sin tener que copiarlo todo.

Semántica de fusión. Cuando un Manifest local extiende un Manifest base, el compilador realiza un reemplazo superficial de claves por nivel — los diccionarios type y name se fusionan de forma independiente, no en profundidad —, lo que garantiza búsquedas O(1) en los diccionarios y mantiene predecible el comportamiento de la herencia. Dentro de cada nivel, las claves hijas sobrescriben las claves padre.

El patrón puente para el desarrollo local. Un uso habitual de extends es intercambiar una FeatureRecipe de credenciales para el prototipado local sin tocar el Aggregate. En producción, el Manifest base asigna la Feature de credenciales core/aws-secrets-manager a una FeatureRecipe de producción en el nivel features.type. Para el prototipado local, el equipo de plataforma proporciona un local-manifest que extiende la base y sobrescribe quirúrgicamente la asignación de la Feature de credenciales para usar host-env-injector — una FeatureRecipe local que entrega la credencial en el archivo Compose como una referencia a variable como ${SECRET_NAME}, que Docker Compose sustituye desde el entorno del shell o un archivo .env cuando se inicia el stack. El desarrollador obtiene un flujo de trabajo local estándar, y el Aggregate sigue siendo agnóstico respecto a las capacidades para producción.

URI abreviados según el contexto

El compilador de Aggrega utiliza la inferencia según el contexto al resolver URI OCI en los Manifests. Si un ingeniero omite el nombre de dominio completo (Fully Qualified Domain Name, FQDN) y el tipo de entidad arquitectónica, el compilador recurre automáticamente al registro predeterminado (configurado en .aggrega-config.yaml) e infiere el tipo de entidad según dónde se encuentre la cadena en el esquema.

Las reglas de inferencia:

  1. Dominio predeterminado: a cualquier URI sin dominio (p. ej., python-worker-helm:1.0) se le antepone el default_registry configurado (predeterminado: hub.aggrega.ai/).
  2. Expansión contextual de la entidad: el compilador añade la ruta de entidad correcta según el diccionario estricto del esquema:
    • Las cadenas bajo Aggregate.spec.components[].type se expanden a /component/.
    • Las cadenas bajo Aggregate.spec.aggregates[].type se expanden a /aggregate/.
    • Las cadenas bajo Manifest.spec.mappings.components.type o Manifest.spec.mappings.components.name se expanden a /recipe/.
    • Las cadenas bajo Manifest.spec.mappings.features.type o Manifest.spec.mappings.features.name se expanden a /featurerecipe/. Esto incluye las Features de credenciales (etiquetadas con feature.aggrega.ai/kind: secret) — usan la misma ruta de FeatureRecipe.
    • Las cadenas asignadas a pipeline[].plugin se expanden a /plugin/.
  3. Precedencia de tres niveles: antes de aplicar la inferencia OCI, el compilador busca en los directorios de catálogo del workspace y en la caché de artefactos (el nivel de workspace y caché), tal como se define en el modelo de resolución de entidades de tres niveles. La inferencia OCI solo se aplica cuando la entidad llega al nivel del registro. Una clave o un valor de mapping nunca se lee como ruta de archivo: una Recipe o FeatureRecipe escrita localmente se encuentra en un directorio de catálogo — catalog/ en la raíz del workspace, o uno de los que enumera workspace.catalog_dirs — y se nombra por su referencia.

La forma abreviada en acción:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

Sin prefijo ops/. Los nombres de Recipe no llevan prefijo ops/ — el directorio de tipo de entidad recipe/ de la taxonomía OCI ya identifica el dominio, y las Recipes se publican bajo recipe/{capability}/{name} sin prefijos adicionales. Los Manifests hacen referencia a las Recipes mediante {capability}/{name}, o mediante el nombre sin más para la inferencia según el contexto. Consulta architecture/13-catalog-and-registry.md §6 para la taxonomía OCI completa.

Enlaces de Feature dirigidos por anotaciones

El bloque features.annotations del Manifest declara enlaces entre claves de anotación y tipos de Feature, además de las rutas de enrutamiento por las que cada enlace envía el valor de la anotación. El enlace es la superficie de autoría para comprimir las vinculaciones repetitivas de Feature por componente — el patrón en el que decenas de componentes de un mismo límite llevan cada uno un bloque features: idéntico — en declaraciones de anotación únicas en los límites de la Release o en los subsistemas del Aggregate.

Forma del esquema:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Un enlace lleva un campo feature que nombra el tipo de Feature de destino y un bloque maps que agrupa las rutas de subclaves en notación de puntos por pilar de destino. El campo feature hace referencia a un tipo de Feature que también debe aparecer en la sección hermana features.type (que es donde reside el enlace de versión de la FeatureRecipe). El bloque maps declara dos listas indexadas por pilar — maps.infra y maps.values —, cada una con cadenas de rutas en notación de puntos que apuntan a las propiedades spec.schema.<pillar>.<path> de la Feature de destino. Un enlace debe declarar al menos una ruta entre las dos listas (el JSON Schema impone minProperties: 1 en maps).

El polimorfismo de Provider para la misma clave de anotación — p. ej., feature.aggrega.ai/rewrite-host enlazada a core/k8s-dns-resolver en un despliegue de Kubernetes pero a core/compose-bridge en un despliegue local de Compose — se expresa eligiendo tipos de Feature distintos en Manifests distintos; cada Manifest enlaza la anotación con una sola Feature, y la FeatureRecipe de la Feature elegida contiene la implementación específica del proveedor.

La partición lado/pilar. La invariante del Aggregate como superficie de autoría restringe cada lado de autoría a las rutas de enrutamiento de un solo pilar. Las anotaciones del lado del Aggregate solo se enrutan por rutas maps.values; las anotaciones del lado de la Release solo se enrutan por rutas maps.infra. Un enlace que declara rutas en ambos pilares admite la composición entre lados: una anotación del lado del Aggregate activa el subconjunto del pilar values; una anotación del lado de la Release sobre la misma clave activa el subconjunto del pilar infra; ambas contribuciones se componen en una única vinculación de Feature por par (Component, Feature) con ambos pilares rellenados. Una discrepancia lado/pilar — p. ej., una anotación del lado del Aggregate sobre un enlace que solo declara maps.infra — detiene la compilación con un diagnóstico claro que nombra la clave de anotación, el pilar enrutado, el lado de autoría y la ubicación en el código fuente, clasificado bajo el dominio del documento en el que se escribió el valor de la anotación.

Validación de los destinos de ruta. Al cargar el catálogo, el compilador verifica que cada ruta en notación de puntos declarada bajo maps.infra y maps.values corresponda a una propiedad que spec.schema.<pillar> de la Feature de destino declare realmente. Un enlace que enruta a una ruta que el esquema de la Feature no enumera detiene la carga del catálogo con un OPS_ERROR claro que nombra el enlace, la Feature de destino, y el pilar y la ruta por los que enrutó. Las formas de esquema que escapan a un simple recorrido de propiedades ($ref, patternProperties, composición oneOf / anyOf / allOf) terminan la comprobación estática en esa rama y dejan que la validación de esquema posterior detecte cualquier discrepancia.

Formas de los valores de anotación. Un enlace consume valores de anotación en tres formas. Escalar — un único valor YAML (cadena, número, booleano). Un escalar emparejado con un enlace que declara exactamente una ruta entre ambos pilares enruta el valor a esa única ruta; un escalar emparejado con un enlace que declara más de una ruta es un enrutamiento ambiguo y detiene la compilación con un diagnóstico claro, clasificado bajo el dominio del documento en el que se escribió el valor de la anotación. Estructurado — un mapa YAML cuyas subclaves de primer nivel coinciden cada una con una entrada de ruta en notación de puntos bajo maps.infra o maps.values; cada subclave se enruta de forma independiente a su pilar declarado, y la partición lado/pilar se aplica por subclave. null YAML explícito — excluye el enlace heredado en el ámbito de la cascada (un null por subclave dentro de un valor estructurado excluye subclaves individuales mientras las hermanas se mantienen). Para la guía de referencia sobre la autoría de valores estructurados — fusión en cascada por subclave, composición entre lados, validación de tipo por subclave, la disciplina del valor predeterminado relajado para campos de esquema sin un type declarado — consulta providers/well-known-annotations.md §“Valores de anotación estructurados”.

La vinculación explícita gana en caso de colisión de claves. Cuando un componente de una Release o un componente de un Aggregate lleva tanto una entrada features: explícita como una anotación que se expande a la misma clave de Feature, la entrada explícita se conserva y la expansión de la anotación para esa clave en ese componente no tiene efecto. La vinculación sintética nunca sobrescribe una instancia de Feature declarada por el autor. Por tanto, los autores pueden usar la expansión de anotaciones para la mayoría de los componentes y sobrescribir quirúrgicamente componentes individuales escribiendo una entrada features: explícita con la misma clave — la entrada explícita lleva la personalización por componente, y la anotación se propaga en cascada sin cambios a todos los demás componentes.

Lo explícito gana por hoja en la composición entre lados. Cuando una vinculación explícita y una contribución de anotación rellenan ambas la misma instancia de Feature pero escriben hojas distintas, ambas contribuciones se mantienen y la Feature resultante lleva ambas hojas, con una procedencia por hoja que registra el origen de cada una. Cuando una vinculación explícita y una contribución de anotación apuntan a la misma hoja dentro del mismo pilar, gana la contribución explícita y la IR registra la procedencia de la anotación suprimida como marcador de anulación en esa hoja. La carga del catálogo hace visible esta anulación en tiempo de compilación mediante una advertencia de lint consultiva que nombra la clave de anotación suprimida + el origen.

Valores predeterminados del esquema en el momento de la expansión. La vinculación de Feature sintética que produce la expansión de anotaciones solo lleva las hojas que el valor de la anotación rellena a través de las rutas declaradas del enlace. Los valores predeterminados declarados en spec.schema de la Feature de destino no se fusionan en la vinculación sintética en el momento de la expansión. La materialización de los valores predeterminados es responsabilidad de la capa de renderizado de la FeatureRecipe, que se aplica de manera uniforme a las vinculaciones explícitas y sintéticas para que ambas rutas produzcan la misma salida posterior para la misma configuración efectiva.

Separación de espacios de nombres de anotaciones:

PrefijoPropietarioPropósito
aggrega.ai/Solo la plataforma AggregaAnotaciones nativas de la plataforma que el proveedor lee directamente (p. ej., aggrega.ai/namespace).
feature.aggrega.ai/Biblioteca estándar oficialAtajos de anotación de Feature enlazados en el Manifest.
{any-other-domain}/Empresa / comunidadAtajos de anotación de Feature personalizados.

Reserva del prefijo aggrega.ai/

Los enlaces features.annotations de un Manifest no pueden usar el prefijo aggrega.ai/ sin más — está reservado para las anotaciones nativas de la plataforma que emite el compilador (etiquetas OTel/de procedencia, etc.). Los subprefijos con ámbito (component.aggrega.ai/*, compliance.aggrega.ai/*, acme.aggrega.ai/* empresarial) siguen disponibles para la autoría de los usuarios. Consulta providers/well-known-annotations para el conjunto de anotaciones reservadas por la plataforma.