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

Contratos sociales

Aggrega es, por diseño, un compilador sin opiniones propias. Según los invariantes fundacionales documentados en architecture/05-invariants.md, el compilador analiza YAML, recorre grafos, evalúa intersecciones de etiquetas y canaliza cadenas entre componentes — pero no vigila lo que los desarrolladores ponen en values, parameters, infra, provides o locals; no impone convenciones de nombrado, convenciones de puertos ni las etiquetas semánticas que inventa un Arquitecto; no adivina el propósito de un componente a partir de los nombres. Muchas disciplinas que suenan a reglas del compilador son en realidad contratos sociales: buenas prácticas sostenidas por una convención de autoría y no por la aplicación del esquema o en tiempo de ejecución.

Dónde se detiene esa neutralidad merece decirse con claridad, porque es una sola línea y es fácil sobreinterpretarla. Algunas claves son propias de Aggrega — reservadas, con los valores que aceptan escritos en el esquema publicado — y esas sí las comprueba el esquema, del mismo modo que comprueba cualquier otro campo declarado. Declarar el conjunto de valores de una clave que define la propia plataforma no es el compilador leyendo un significado en lo que escribiste; es la plataforma diciendo qué significa su propia clave. Todo lo que escribes bajo una clave propia queda exactamente tan sin vigilar como describe esta página.

Esta página es el inventario canónico de los contratos sociales del lenguaje. Los autores que aprenden los contratos en esta página pueden razonar por qué el compilador acepta una compilación mal formada según la convención (la acepta — el compilador no interpreta la convención) y dónde recae la responsabilidad de detectar la infracción (disciplina de autoría, atención de los revisores o un plugin linter ejecutado por aggrega lint).

Tres clases de disciplina

Las disciplinas de Aggrega se dividen en tres clases según cómo se impone la disciplina. La clasificación importa porque cada clase tiene un modo de fallo distinto cuando se viola la disciplina.

Impuesta por el esquema

La disciplina se impone mediante la validación JSON Schema 2020-12 en el momento de carga (el JSON Schema de la envoltura de la entidad, más las declaraciones schema: a nivel de pilar en las entidades Component y Feature). Una violación produce una detención fatal antes de que la compilación avance; el compilador se niega a continuar. Los autores que intentan violar una disciplina impuesta por el esquema ven un error de validación explícito que señala el campo y la restricción.

Ejemplos: los campos obligatorios de la envoltura de la entidad (apiVersion / kind / metadata.name / metadata.version); la regex SemVer sobre metadata.version; el conjunto cerrado de valores de la etiqueta reservada component.aggrega.ai/type; la prohibición mecánica de los bloques values: en el esquema de la Release (según el invariante 5); el rechazo de extends junto con aggregate en la Release (el invariante de la fuente única de verdad); las reglas de forma de la Recipe que imponen el contrato de composición de tipos de entrada.

Las disciplinas impuestas por el esquema son las garantías más fuertes que ofrece el lenguaje. El compilador se niega a renderizar cualquier cosa que las viole.

Impuesta por un plugin de políticas

La disciplina la impone un plugin Wasm que se ejecuta en uno de los puntos de socket documentados (el rol de gobernanza label-transform durante la construcción de la topología; el rol de gobernanza ir-verdict durante el análisis estático; el socket del linter fuera de banda). Una violación produce o bien un fallo de política que detiene la compilación (sockets en banda) o bien una advertencia consultiva (sockets fuera de banda), según la semántica de bloqueo del socket.

Una disciplina se impone de esta manera solo donde se ejecuta un plugin que la comprueba: el runtime de Wasm invoca los plugins en los puntos de socket documentados, y una disciplina que ningún plugin comprueba sigue siendo una convención. El linter de publicación, que ejecuta aggrega lint, comprueba parte de una convención de esta página — consulta Convenciones que comprueba una regla del linter. Ninguna regla del linter de publicación comprueba la hermeticidad (la FuncMap de Sprig expone helpers que rompen el determinismo de la salida, según la advertencia sobre el determinismo de templates/sprig-functions.md) ni la nomenclatura de recursos en la nube (Recipes cuyas salidas de valuesMapping: hacen referencia a campos de nombres de recursos en la nube sin interpolación de release_name / instance_id, según entities/recipe.md «Cloud-resource naming discipline (Disciplina de nomenclatura de recursos en la nube)»); un plugin linter propio puede comprobar cualquiera de las dos.

Para la superficie del contrato de plugins Wasm y el criterio de ubicación (el socket del linter frente a los roles de veredicto de gobernanza), consulta plugins/plugin-contract.md.

Mantenida por convención

La disciplina se mantiene únicamente mediante la disciplina de autoría y la atención de los revisores. El compilador no la impone; ningún esquema rechaza la violación; ningún plugin Wasm la señala. Los autores aprenden la disciplina en la documentación, la siguen porque la forma arquitectónica depende de ella y confían en la revisión de PR para detectar los descuidos. Una violación no produce ninguna señal en tiempo de compilación — la compilación tiene éxito, la salida renderizada funciona hasta donde sabe el compilador, y la violación de la disciplina solo aflora cuando las herramientas posteriores o el comportamiento en tiempo de ejecución dependen de la convención.

Las disciplinas mantenidas por convención son la lista fundamental que los autores deben aprender en la documentación. El compilador no las interpreta; equivocarse en ellas no rompe la compilación, pero sí rompe la forma arquitectónica de la que depende Aggrega. La mayor parte de esta página las documenta.

Las convenciones

Los siguientes contratos sociales se mantienen por convención. Cada entrada nombra la disciplina, la superficie donde se documenta la convención y el modo de fallo si se viola. Cada uno conserva su número dondequiera que esté: el contrato 3, la disciplina de prefijos reservados, lo comprueba una regla del linter para las claves de anotación y se describe en Convenciones que comprueba una regla del linter.

1. Elegir el tipo operativo que se ajusta al componente

La etiqueta reservada component.aggrega.ai/type nombra qué clase de cosa es un componente, tomada de un conjunto cerrado de primitivas universales de la nube: server, worker, task, function, stateful-server, resource. La pertenencia a ese conjunto la impone el esquema, no se mantiene por convención. Aggrega define esta clave y los valores que acepta, el esquema del Component los enumera, y un documento que lleve cualquier otro valor se rechaza al cargarse — E0215, la condición entity-envelope-invalid, nombra la etiqueta y enumera los valores que acepta. Ese rechazo es lo que esta entrada no cubre.

Lo que sigue siendo convención es cuál de los valores se ajusta al componente que tienes delante. Nada comprueba que una base de datos relacional esté etiquetada stateful-server en lugar de server, ni que un consumidor de una cola sea worker en lugar de task; el selector evalúa cualquier valor que encuentre sin atribuirle significado. El Arquitecto que escribe un Component elige el valor que describe cómo debe tratarlo la infraestructura, y los selectores posteriores, los plugins de políticas y los plugins de renderizado Wasm confían todos en que esa elección sea honesta.

Clasificar en un eje propio. El conjunto cerrado rige esta única clave reservada y nada más. Un catálogo que necesita una clasificación que Aggrega no define — un nivel, una zona de datos, una clase de servicio o una división más fina de las primitivas operativas — añade su propia clave de etiqueta junto a la reservada. El esquema del Component acepta cualquier otra clave de etiqueta con un valor de cadena, y la misma maquinaria de selectores la lee, de modo que acme.aggrega.ai/storage-tier: oltp convive con component.aggrega.ai/type: stateful-server y el appliesTo de una Feature o el selector de un socket pueden apuntar a cualquiera de las dos. La extensión se hace en una clave propia, nunca en un valor dentro de la de Aggrega.

Documentado en: architecture/02-ecosystem-philosophy.md (la ontología operativa) + labels-and-annotations.md (disciplina de prefijos) + errors/sentinels.md (E0215).

Modo de fallo: Un valor del conjunto que no se ajusta al componente confunde a todo lo que lee la etiqueta. Un almacén de datos etiquetado server es rechazado por una Feature o un socket que selecciona stateful-server — una detención que nombra el selector, no la etiqueta equivocada — y un plugin de políticas o un plugin de renderizado que lee la etiqueta lo trata como cómputo sin estado. Donde solo esos lectores lo ven, la compilación tiene éxito; el error solo aflora cuando los artefactos renderizados llegan al clúster.

2. Separación de .context.annotations.* en tres contenedores

Las anotaciones en cascada llegan a tres contenedores con nombre — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — cada uno con una intención distinta. El objetivo de la disciplina: release es «dónde se ejecuta este componente, gobernado por Ops»; catalog es «qué es este componente, escrito por el Arquitecto»; aggregate es «qué hace este componente, escrito por el Desarrollador».

El compilador no impone los límites entre los contenedores. Los tres contenedores comparten una forma plana string → string; la plantilla de una Recipe puede leer los tres, y nada impide que una anotación del límite de la Release se interprete como metadatos cognitivos o que una anotación del catálogo se encamine a infra:. La separación la mantienen los autores que escriben las anotaciones en el contenedor correcto y los revisores que detectan fugas entre contenedores.

Documentado en: labels-and-annotations.md (la separación en tres contenedores es un contrato social).

Modo de fallo: La lógica de enrutamiento que depende de la distinción de intención entre contenedores (p. ej., una Recipe que encamina .context.annotations.release.aggrega.ai/region a un campo region de Terraform) consume silenciosamente cualquier anotación que aparezca en el contenedor, sin importar la intención de autoría. La compilación tiene éxito; la salida renderizada puede llevar valores semánticamente incorrectos.

4. Autocontención de provides: en la Recipe

Las plantillas provides: de la Recipe se cierran solo sobre los datos propios del nodo — .values, .infra, .context.instance_id, .context.rendered_name donde el proveedor del nodo informe uno, los .locals resueltos del nodo, más cadenas estáticas. Las referencias a .context.inject y .context.uses están prohibidas porque la evaluación de provides ejecuta esas plantillas en cualquier orden; leer datos de otros nodos la acoplaría al orden de iteración topológica, que el diseño evita deliberadamente. .locals forma parte de la superficie en lugar de quedar fuera: los locals del nodo se resuelven en el preámbulo de la misma etapa, antes de sus provides, y son locales al nodo, de modo que leerlos no cuesta nada en cuanto al orden. Nombrar una clave que el bloque locals no declara provoca una detención.

Esta es una regla con dos mitades, cada una de las cuales indica dónde se comprueba. El compilador comprueba la primera: la evaluación de provides comprueba cada plantilla frente a una lista de permitidos positiva de las raíces que define su contexto antes de que la plantilla se ejecute, de modo que una lectura de .context.inject / .context.uses se detiene con un error explícito en lugar de renderizarse vacía; la regla también está documentada en templates/expansion-matrix.md, fila 6. La convención mantiene la segunda: el patrón más amplio (provides-is-public; locals-is-private) está anclado en la convención.

Documentado en: templates/expansion-matrix.md fila 6 + vocabulary/data-pillars.md «provides: and locals: — public face vs private face (provides: y locals: — cara pública frente a cara privada)».

Modo de fallo: el compilador detecta las referencias prohibidas y detiene la compilación en el momento de evaluar las plantillas cuando aparecen directamente en provides:. La disciplina más amplia de lo público frente a lo privado (no exponer estado interno a través de claves de provides:) es solo una convención — los autores que tratan provides: como un espacio de nombres interno de la Recipe producen contratos de los que dependen los llamadores; la refactorización se convierte en un cambio incompatible.

5. Determinismo — helpers no herméticos en las plantillas de la ruta de renderizado

El invariante de salida determinista de Aggrega (invariante 8 en architecture/05-invariants.md) exige una salida idéntica byte a byte para una entrada idéntica byte a byte. La FuncMap completa de Sprig expone helpers que leen el estado del entorno (lectores del reloj now / date; generadores aleatorios randAlpha / uuidv4; lectores de variables de entorno env / expandenv; resolutores de red getHostByName). Los autores que invocan estos helpers desde una plantilla que contribuye a la salida renderizada rompen el contrato de determinismo.

El compilador no detecta ni bloquea el uso de helpers no herméticos. La FuncMap de Sprig los expone según templates/sprig-functions.md «Determinism caveat (Advertencia sobre el determinismo)»; la disciplina la mantienen los autores que evitan esos helpers en las plantillas de la ruta de renderizado y los revisores que detectan su uso en la revisión de PR.

Documentado en: templates/sprig-functions.md «Determinism caveat (Advertencia sobre el determinismo)».

Modo de fallo: La salida de la compilación difiere entre ejecuciones de la misma entrada. La discrepancia aflora en el momento del diff de GitOps, cuando las herramientas posteriores (ArgoCD, Flux) ven una deriva inesperada entre el manifiesto confirmado y el estado del clúster, o en el momento de una auditoría, cuando dos compilaciones de la misma entrada producen artefactos distintos.

Ninguna regla del linter de publicación comprueba en las plantillas las invocaciones de helpers no herméticos. El nombre del helper está escrito en la plantilla, de modo que un plugin linter propio puede encontrarlo (consulta Convenciones que comprueba una regla del linter).

6. Límites de los pilares (señales, no muros)

Los límites de los pilares son disciplina de autoría, no una imposición del lenguaje. El motor de plantillas permite lecturas entre pilares en cualquier punto, salvo que las prohíban explícitamente las reglas de autocontención (p. ej., provides: y source: de la Recipe que leen .context.inject / .context.uses). Los autores deberían:

  • Leer .values para la carga útil cognitiva (intención escrita por el desarrollador).
  • Leer .infra para el dimensionamiento físico (dimensionamiento escrito por Ops).
  • Leer .context.uses.<alias>.provides.<key> para las cadenas de puntero entre componentes.
  • Leer .context.inject para la tubería de entrega posterior a la hidratación.

El motor de plantillas no controla la lectura. Una plantilla de Recipe que lee .infra.replicas para alimentar un campo values: funciona; nada impide la ruta entre pilares. El objetivo de la disciplina son señales — los límites describen la intención de autoría (quién es dueño de los datos) más que una restricción en tiempo de ejecución.

Documentado en: vocabulary/data-pillars.md «Pillar boundaries and authoring discipline (Límites de los pilares y disciplina de autoría)».

Modo de fallo: Fuga entre pilares — la carga útil cognitiva del desarrollador contiene detalles de dimensionamiento físico, o el dimensionamiento escrito por Ops contiene metadatos cognitivos. La compilación tiene éxito; la división de autoría en cuatro dominios se difumina con el tiempo a medida que los autores atajan los pilares; el mantenimiento posterior se vuelve más difícil a medida que se debilita la correspondencia entre pilares y flujo de datos.

7. Semántica de doble origen de containers.<name>.variables del Workload

El mapa variables: combina dos fuentes de datos distintas mediante expresiones de plantilla de Go: literales del pilar del desarrollador (entradas que leen .values / .infra / .locals) y datos de la tubería entre componentes (entradas que leen .context.inject.env.<KEY>). Los autores eligen una fuente por entrada según si el valor es local al componente o derivado de otros componentes.

El compilador no distingue las dos fuentes; ambas fluyen a la misma lista env: de Kubernetes en el Deployment renderizado. La semántica de doble origen existe solo en tiempo de autoría — la disciplina consiste en nombrar la intención (esta entrada es local al componente; aquella entrada se deriva de otros componentes) para que los futuros mantenedores puedan leer qué entradas dependen de qué salidas de la hidratación de inject.

Documentado en: entities/workload.md «Field-semantics essentials (Aspectos esenciales de la semántica de los campos)» (variables).

Modo de fallo: Los autores que no distinguen las dos fuentes pierden el rastro de «qué entradas están acopladas a los provides: de qué destino». Refactorizar las claves de provides: de un destino rompe silenciosamente cada entrada variables: del llamador que leía a través de la tubería de inject.

8. Disciplina de nomenclatura de recursos en la nube

Las Recipes que emiten nombres de recursos en la nube (nombres de buckets de S3, identificadores de bases de datos de RDS, nombres de roles de IAM, nombres de stacks de CloudFormation — cualquier campo cuyo valor ocupa un espacio de nombres global en el proveedor de nube) deben concatenar {{ .metadata.release_name }} y/o {{ .context.instance_id }} en el nombre renderizado para evitar colisiones cuando la misma Recipe se ejecuta en varias Releases o instancias de componentes.

El compilador no inspecciona las salidas de valuesMapping: en busca de campos de nombres de recursos en la nube sin estas interpolaciones. La disciplina la mantienen los autores de la Recipe (que saben qué campos nombran recursos globalmente únicos para el proveedor de destino) y los revisores (que detectan patrones de recursos sin nombre en la revisión de PR).

Documentado en: entities/recipe.md «Cloud-resource naming discipline (Disciplina de nomenclatura de recursos en la nube)».

Modo de fallo: Dos Releases del mismo Aggregate (prod-billing y staging-billing) intentan ambas desplegar un recurso con el mismo nombre global; el segundo despliegue falla en tiempo de ejecución con un rechazo del lado de la nube. La compilación de Aggrega tiene éxito; el fallo del despliegue solo aflora cuando se aplica la segunda Release.

Ninguna regla del linter de publicación comprueba que los campos de nombres de recursos en la nube lleven las interpolaciones requeridas; un plugin linter propio puede hacerlo (consulta Convenciones que comprueba una regla del linter).

9. Granularidad del Component — un servicio coherente por Component

Un Component modela un servicio coherente — un único servicio expuesto, o la carga o cargas de trabajo de un servicio junto con sus cargas de trabajo auxiliares solo internas. Cuando un chart agrupa servicios que otro componente podría usar con sentido por separado mediante use — en especial infraestructura ajena como una base de datos, una caché o un broker de mensajes que Aggrega ya modela como su propio Component — la biblioteca estándar compone Components por servicio en un módulo de subagregado (spec.aggregates + exportedComponents) en lugar de envolver todo el producto como un único Component opaco. La disciplina: varias cargas de trabajo están bien dentro de un Component; la usabilidad independiente es la línea que divide un Component en un stack.

El compilador es agnóstico respecto a esta granularidad. Renderiza cualquier cosa que supere la validación del esquema — no inspecciona cuántos servicios agrupa la Recipe de un Component, ni si uno de ellos es utilizable de forma independiente. Un autor que envuelve un producto de cinco servicios como un único Component produce un Component que el compilador acepta y renderiza sin objeciones; la convención la mantienen la disciplina de autoría y la atención de los revisores.

Documentado en: ../../architecture/06-data-taxonomy-and-composition.md (un servicio coherente por Component — el límite de la carga de trabajo única).

Modo de fallo: Un envoltorio monolítico multiservicio se compila correctamente, pero los servicios agrupados son invisibles para la topología, el selector y las políticas — no pueden escalarse, reemplazarse ni usarse como dependencia de forma independiente. Refactorizar más adelante el monolito en Components por servicio es un cambio incompatible para cada consumidor que hacía referencia al único nodo envuelto.

Por qué existen las convenciones

Cada una de estas convenciones es disciplina de autoría por diseño, aunque un esquema o una política Wasm podría imponer cualquiera de ellas. El razonamiento por tipo de contrato:

Extensibilidad. La disciplina de prefijos reservados (contrato 3) describe el vocabulario de la biblioteca estándar, no el universo del vocabulario válido. Los catálogos empresariales escriben sus propios prefijos y claves de etiqueta para extender la biblioteca estándar; imponer por esquema la convención de prefijos convertiría «la disciplina de la biblioteca estándar» en «la única forma permitida del lenguaje» — ese es el muro que la arquitectura evita deliberadamente. El eje del tipo operativo (contrato 1) mantiene la misma extensibilidad en otra superficie: la clave reservada que define Aggrega lleva un conjunto cerrado impuesto por el esquema, y un catálogo extiende añadiendo una clave de etiqueta propia junto a ella en lugar de un valor dentro de la de Aggrega. Lo que el esquema comprueba es el conjunto de valores de una clave que le pertenece; lo que queda abierto es cualquier otra clave, que es donde vive el vocabulario propio de un catálogo.

Pureza AOT. La disciplina de nomenclatura de recursos en la nube (contrato 8) y la disciplina del determinismo (contrato 5) requieren inspeccionar el contenido de las plantillas para determinar si un campo es un nombre de recurso en la nube o la invocación de un helper no hermético. La pureza AOT (invariante 2) impide que el compilador dependa del estado en tiempo de ejecución; la inspección estática de plantillas es factible (un plugin linter lee las plantillas de la entidad tal como están escritas), pero hacerla dentro del compilador central acopla la lógica interna del compilador a cuestiones de autoría propias de cada dominio. La arquitectura saca estas comprobaciones del compilador y las lleva a plugins Wasm según el invariante 6 (el límite de la ABI de Wasm).

Flexibilidad de autoría. La disciplina de los límites de los pilares (contrato 6) y la semántica de doble origen de variables (contrato 7) describen patrones de autoría y no restricciones en tiempo de ejecución. La misma sintaxis de plantilla puede expresar un patrón que respeta la disciplina o uno que la viola; convertir la disciplina en una comprobación en tiempo de ejecución exigiría que el compilador interpretara una intención de autoría a la que no tiene acceso. La arquitectura trata la convención como documentación de la que aprenden los autores y no como un invariante en tiempo de ejecución. La granularidad del Component (contrato 9) también encaja aquí: las empresas pueden envolver un producto con la granularidad que prefiera su catálogo, y el compilador — neutral respecto al contenido y sin opiniones propias según el invariante 1 — no tiene forma de saber si una carga de trabajo agrupada es utilizable de forma independiente, así que el límite de un servicio coherente sigue siendo disciplina de autoría y no un muro de esquema. La elección del tipo operativo (contrato 1) tiene la misma forma: el esquema establece qué valores existen, pero cuál de ellos describe un componente dado es un juicio de modelado sobre cómo debe tratarlo la infraestructura, y nada en una Recipe ni en un bloque values le dice al compilador si el juicio fue acertado.

Imposición en dos mitades. La autocontención de provides: en la Recipe (contrato 4) la impone en parte el compilador — la ruta de renderizado detecta lecturas de .context.inject / .context.uses en las plantillas provides: y se detiene. La disciplina más amplia de lo público frente a lo privado (no exponer estado interno) está anclada en la convención, porque el compilador no puede determinar qué cadenas deben seguir siendo internas de la Recipe sin la intención de autoría.

Las tres vías importan porque cada una indica dónde recae la responsabilidad de detectar las violaciones. Impuesta por el esquema: el compilador. Impuesta por un plugin de políticas: el plugin que la comprueba, donde se ejecute uno. Mantenida por convención: los autores y los revisores. Los autores que interiorizan las vías entienden qué errores detectará el compilador y cuáles pasarán silenciosamente a las herramientas posteriores o al tiempo de ejecución.

Convenciones que comprueba una regla del linter

El linter de publicación, que ejecuta aggrega lint, comprueba en parte una convención de esta página: las claves de anotación del contrato 3, más abajo. Su hallazgo es consultivo, y la parte de la convención que no alcanza se mantiene por convención, como las entradas anteriores.

Ninguna regla del linter de publicación comprueba ninguna otra convención de esta página. Dos de ellas pueden comprobarse con una regla del linter, porque la violación está escrita en la entidad: el determinismo (contrato 5) — una plantilla que llama a un helper no hermético — y la nomenclatura de recursos en la nube (contrato 8) — una salida de valuesMapping: que nombra un recurso en la nube sin interpolación de release_name / instance_id. También pueden comprobarse las claves de etiqueta bajo los prefijos reservados (contrato 3). Un workspace puede adjuntar plugins linter propios bajo plugins.linter, junto al linter de publicación, para comprobar cualquiera de ellas; Las reglas de disciplina enumera las reglas que lleva el linter de publicación.

Las demás convenciones (1, 2, 4, 6, 7, 9) dependen de lo que el autor quiso decir, que ninguna regla lee a partir de lo escrito. La separación en contenedores está impulsada por la extensibilidad (los catálogos empresariales la sobrescriben) — la imposición por esquema entraría en conflicto con esa flexibilidad. Lo que queda del eje del tipo operativo después de que el esquema establece el conjunto de valores — elegir la primitiva que se ajusta al componente — está impulsado por la intención de autoría: el compilador no puede distinguir un tipo operativo bien elegido de uno mal elegido, porque ambos son valores que acepta. La disciplina de los límites de los pilares y la semántica de doble origen de variables están impulsadas por la intención de autoría — el compilador no puede determinar la intención solo a partir de la sintaxis de las plantillas. La autocontención de provides: en la Recipe se impone en parte; la disciplina más amplia de lo público frente a lo privado depende de qué claves quiso el autor mantener internas, algo que nada en la Recipe declara. La granularidad del Component también está impulsada por la intención de autoría — si una carga de trabajo agrupada es utilizable de forma independiente es un juicio de modelado que el compilador no puede leer en el contenido de la Recipe.

3. Disciplina de prefijos reservados

Las claves de anotación y de etiqueta siguen una forma <namespace>/<name>. Cinco prefijos reservados llevan reglas de autoría específicas: aggrega.ai/ (solo para la plataforma), feature.aggrega.ai/ (atajos oficiales de Feature), component.aggrega.ai/ (rasgos intrínsecos del Component), aggregate.aggrega.ai/ (identidad de módulo del Aggregate) y <any-other-domain>/ (empresa / comunidad).

El compilador no rechaza una anotación escrita bajo un prefijo reservado en una entidad del catálogo o en una Release; solo un enlace de anotación de un Manifest o una etiqueta de salida de una Recipe que reclame una clave bajo aggrega.ai/ detiene la compilación. Una empresa que declara aggrega.ai/internal-billing-tag: "..." fuera del vocabulario de la plataforma produce una anotación que el compilador acepta y propaga en cascada por el sistema de contenedores; las actualizaciones posteriores de la plataforma que introduzcan un aggrega.ai/internal-billing-tag real colisionan silenciosamente.

Documentado en: labels-and-annotations.md (Disciplina de prefijos) + providers/well-known-annotations.md.

Modo de fallo: Las anotaciones personalizadas bajo prefijos reservados colisionan con futuras anotaciones de la plataforma con el mismo nombre; el comportamiento esperado de la plataforma sobrescribe silenciosamente el valor escrito por la empresa o coexiste con él, según el orden.

El linter de publicación, que ejecuta aggrega lint, marca una clave de anotación de una entidad del catálogo bajo aggrega.ai/ que no es una de las anotaciones conocidas de la plataforma, y una bajo feature.aggrega.ai/ en una entidad que no es una Feature, como hallazgo consultivo (E0277). Las claves de etiqueta, los demás prefijos reservados y las anotaciones fuera de los metadata.annotations de una entidad — las que escribe una Release, por ejemplo — no se comprueban, así que para ellas la disciplina sigue siendo una convención.

Referencias cruzadas