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

Resolución de dependencias

Resolución de dependencias de Aggrega & el pilar de la topología estructural

En la arquitectura de Aggrega, las dependencias topológicas se asignan explícitamente mediante el pilar de esquema uses para mantener una carga útil values totalmente opaca. Resolver «quién habla con quién» plantea un reto específico: hay que mapear topologías de aplicación complejas y de varios nodos sin obligar al desarrollador a escribir un enrutamiento de red explícito, órdenes de ejecución a nivel de orquestador o dependencias de infraestructura.

1. La filosofía central: ¿por qué uses?

El bloque uses declara las dependencias entre componentes como topología pura: el Component A depende del contrato público provides del Component B, no de la dirección física ni de los detalles de conexión del Component B. La topología vive en uses; la configuración vive en values. La separación permite al compilador ver explícitamente todas las aristas entre componentes sin inferirlas del contenido de values.

Aggrega lo resuelve elevando la topología a un pilar de esquema de primera clase llamado uses.

  • El argumento del proxy semántico: la palabra clave uses representa una intención semántica L7. Si un agente uses una base de datos, eso sigue siendo semánticamente cierto aunque Platform Ops inyecte mallas de proxies Wasm transparentes entre ellos.
  • Neutralidad matemática: el compilador Go analiza de forma nativa la estructura uses para dibujar el grafo de la representación intermedia (IR). Nunca intenta analizar ni consultar la lógica de aplicación del desarrollador (values).
  • Atomicidad de la Feature: el pilar uses se aplica de forma idéntica a los Components y a las Features (incluidas las Features de credenciales). Esto permite que un proxy sidecar (una Feature) o un recuperador de credenciales declare de forma autónoma sus propias dependencias de red sin contaminar la configuración de su Component padre.

2. La mecánica del contrato de esquema unificado

Para extraer instrucciones operativas sin analizar la carga útil de la aplicación, el sistema se basa en declaraciones estrictas de JSON Schema 2020-12 que rigen estructuras YAML explícitamente separadas.

Dominio 2: el esquema dividido (usesSchema & schema) Para evitar que el catálogo de la plataforma se fragmente en archivos de esquema inmanejables, Aggrega utiliza un motor de esquema dividido. El usesSchema en YAML nativo define y valida estrictamente la topología, mientras que schema: (JSON Schema 2020-12 — normalmente escrito mediante la abreviatura de forma compacta) valida el contenido de los pilares values e infra y declara la forma del pilar provides. Los values que escribe un desarrollador y la infra que establece un operador se comprueban frente a sus tipos declarados; el subesquema provides declara los nombres de clave y los tipos del contrato descendente que produce una Recipe, y el compilador comprueba que cada referencia inject nombre una clave provides declarada — pero los valores provides producidos viajan aguas abajo como cadenas opacas que el compilador canaliza sin interpretarlas, no como valores cuyo tipo comprueba, porque el núcleo no interpreta qué significa un valor canalizado. El usesSchema es donde se declara un socket, y declararlo es lo que le da un contrato. Un socket que declara la entidad del catálogo lleva las restricciones de esa entidad: un selector que indica a qué destinos puede llegar, una lista de permitidos inject y valueSchema / infraSchema por arista. Dentro del usesSchema, los arquitectos de la plataforma usan el campo selector: — leído como la cadena que escribió el arquitecto, no copiado en ningún esquema generado — y el motor de selectores nativo de Go lo evalúa para imponer la seguridad de tipos entre nodos sobre los sockets declarados. Garantiza que, si un socket requiere una base de datos, el desarrollador no pueda conectar un servidor web.

El selector se somete a su gramática en el momento en que se evalúa, es decir, una vez por cada arista cableada a través del socket. Un selector que el motor no puede leer como una de sus seis formas de requisito — un requisito vacío dejado por una coma sobrante, una clave con espacios en blanco o con uno de los caracteres que la gramática usa para distinguir sus formas (=, !, (, ) y la coma), o un conjunto sin su paréntesis de cierre — detiene la compilación en esa arista, nombrando el requisito, en lugar de leerse como otro selector. Esta rigurosidad es lo que mantiene honesta la comprobación: leído con indulgencia, !tier=frontend, escrito para excluir los frontends, solo pediría que ninguna etiqueta se llame tier=frontend, y todos los destinos — frontends incluidos — pasarían. La misma gramática rige los selectores de ranuras de adjuntos y el appliesTo de una Feature; la gramática de selectores enumera cada forma y cada rechazo. Una compilación nunca evalúa un socket por el que no se cablea ninguna arista, así que aggrega validate — sobre todo el catálogo, o sobre el Component o la Feature que declara el socket — lee el selector de cada socket declarado y rechaza ya ahí uno mal formado, con el mismo código y en los mismos términos que usa una compilación que cablea el socket.

Sin embargo, declarar el socket no es la única forma de trazar una arista. El autor de un Aggregate puede nombrar en su propio componente un socket que la entidad del catálogo no declara — incluso en un tipo de componente que no declara ningún usesSchema — y la arista se construye. Un catálogo que no declara ninguna entrada para un socket no ha previsto la conexión, lo que no equivale a prohibirla, y la topología de la aplicación pertenece al desarrollador. Un socket así se llama ad hoc, y lo que cuesta es exactamente lo que aporta declararlo: no hay entrada en el catálogo, así que no hay selector ni contrato por arista, y la seguridad de tipos entre nodos no tiene nada que evaluar. Lo que la arista puede transportar no cambia — cada clave que inyecta debe seguir nombrando una clave que declare el provides del destino, y el destino debe seguir existiendo. Cada arista del grafo emitido registra cuál de los dos casos es, de modo que un consumidor nunca tenga que adivinar; consulta governance-and-compliance para ver cómo un operador prohíbe por completo los sockets ad hoc.

Dos superficies no están abiertas de este modo a propósito, porque no escriben la topología de la aplicación. El uses de un adjunto de Feature solo puede nombrar un socket que declare la Feature adjunta, y el uses por arista de una Release solo puede nombrar un socket que la entidad del catálogo del componente consumidor declare en su usesSchema, nunca uno que el Aggregate haya escrito ad hoc — un operador configura y cablea dentro de una arquitectura, y una Feature participa en la topología que declara su propia entidad del catálogo. Además, declarar el socket en el catálogo sigue siendo el mejor camino y es lo que hace el catálogo de la biblioteca estándar: un socket ad hoc es una vía de escape, no un nuevo comportamiento predeterminado.

Dominio 1: la experiencia del desarrollador (polimorfismo) Los desarrolladores escriben uses: al mismo nivel que values: y features:. Para garantizar una UX sin fricciones, el esquema admite polimorfismo de forma nativa:

  • Arrays de cadenas: se usan para referencias lógicas simples a componentes (p. ej., tools: ["search-api"]) cuando el enrutamiento estándar es suficiente.
  • Mapas de objetos: se usan cuando se requieren contratos de entrega estrictos (p. ej., databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • Sin comodines: no existe ninguna forma con comodín, lo que evita las «dependencias fantasma» y la conexión automática no autorizada: cada entrada nombra un único componente, de modo que ["*"] detiene la compilación como un destino inexistente — ningún nombre de componente puede contener *.

Dominio 3: la realidad de Ops (normalización) Para mantener predecibles las plantillas Go, el compilador Go normaliza las entradas polimórficas de uses. Los arrays de referencias lógicas a componentes se convierten en objetos estándar antes de pasarse al diccionario plano y estricto conocido como .context.uses.


3. Ejemplos de principio a fin

Los dos ejemplos siguientes demuestran las dos propiedades distintas del pilar explícito de la topología: el ejemplo A prueba si una conexión está autorizada (seguridad de tipos entre nodos), y el ejemplo B prueba cómo se entregan físicamente los datos de la conexión (polimorfismo & normalización).

Ejemplo A: validación topológica y seguridad de tipos entre nodos

Este escenario muestra cómo el selector de un socket declarado detecta que un agente de IA está a punto de conectarse a una base de datos que carece de las etiquetas de cumplimiento requeridas, y detiene la compilación. El compilador evalúa el selector de etiquetas que escribió el arquitecto frente a las etiquetas del destino, como cadenas; no interpreta qué significa una etiqueta, y no interviene ningún plugin de políticas.

1. La biblioteca estándar (el schema: unificado en el catálogo) El Platform Architect define la estructura del esquema, separando de forma nativa la lógica cognitiva de los destinos topológicos.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/enterprise-agent
version: 1.0.0
labels:
component.aggrega.ai/type: "worker"
spec:
usesSchema:
datastores:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema:
# 1. The Cognitive Intent
values:
system_prompt: { type: string, required: true }

2. La intención del desarrollador (el Aggregate) El desarrollador separa limpiamente lo que hace el agente (values) de aquello a lo que el agente se conecta (uses).

components:
my_secure_vector_db:
type: core/qdrant-secure:1.0.0
values:
collection_name: finance_data
auditing_agent:
type: core/enterprise-agent:1.0.0
values:
system_prompt: "You are a financial auditing AI..."
uses:
datastores:
finance_memory: { target: "my_secure_vector_db" }

3. Ejecución del compilador y validación topológica

  1. Validación local: el compilador Go evalúa el objeto completo contra el JSON Schema resuelto durante la resolución. Comprueba las etiquetas de catálogo subyacentes de my_secure_vector_db. Si a la base de datos le faltara la etiqueta restricted, el compilador detendría de inmediato la compilación con una violación de seguridad de tipos.
  2. Trazado del grafo: durante la construcción de la topología, el compilador Go ignora por completo el contenido validado por el esquema. Lee uses.datastores.finance_memory.target de forma nativa desde el YAML y traza la arista explícita en el grafo IR.

Ejemplo B: polimorfismo y el .context.uses normalizado

Este escenario muestra cómo el compilador maneja tanto una herramienta de IA de caja negra (pasada como array) como una base de datos relacional heredada (que requiere un mapa con un contrato inject).

1. El catálogo (dominio 2): la declaración schema: El Architect permite arrays polimórficos para las herramientas, pero exige objetos estrictos para las bases de datos.

spec:
usesSchema:
# Polymorphic Array Socket (No injection needed)
tools:
selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract)
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file"]
schema:
values:
system_prompt: { type: string, required: true }

2. La intención del desarrollador (dominio 1): el Aggregate El desarrollador usa un array sencillo para la herramienta y un mapa explícito para la base de datos.

components:
my-agent:
type: core/python-worker:1.0.0
values:
system_prompt: "You are an HR bot."
uses:
# 1. Polymorphic Array: Simple logical component reference
tools:
- "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery
databases:
hr_db:
target: corporate-hr-db
inject:
env:
- in: HR_DATABASE_URI # Local env var
from: "host" # Target provides key

3. La realidad de Ops (dominio 3): la Recipe El compilador Go normaliza el polimorfismo. Ops recibe un diccionario .context.uses plano y predecible. Basta con recorrer la tubería .context.inject en las secciones pertinentes de su plantilla.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: generic-worker
version: 1.0.0
spec:
capability: helm
implements: core/python-worker:1.0.0
source: "./charts/internal/python-runner"
locals:
primary_compute: worker-container
valuesMapping: |
env:
# Ops uses the pre-resolved inject map, kept apart from values and topology loops
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }}
value: "{{ $value }}"
{{- end }}