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

Contrato de los plugins Wasm

El pipeline de compilación de Aggrega incluye puntos de socket designados en los que los plugins WebAssembly (Wasm) amplían el comportamiento del compilador: los cuatro roles del socket de gobernanza, entre ellos un Mutation Gate en la construcción de la topología y un Validation Gate en el análisis estático; un pipeline de plugins posterior al renderizado para los pasos de FeatureRecipe y Recipe; un socket de renderizado de proveedores; un socket de analizador; un socket de importador; y un socket de linting fuera de banda. Esta página documenta el contrato público de los plugins Wasm: qué sockets existen, qué consume y produce cada socket, dónde se sitúa cada socket en el pipeline de compilación y el sandbox dentro del cual se ejecuta cada plugin.

Esta página trata los sockets — los puntos del pipeline y sus formas de entrada/salida. Para el plugin — la entidad Plugin, las declaraciones de capacidades por export, los límites de ejecución y el ciclo de vida publish→pull→build — consulta la guía para desarrolladores de plugins Wasm.

Aggrega incorpora un runtime host de Wasm — Extism sobre el motor Wazero — que carga y ejecuta los plugins detrás de un cortafuegos de pureza AOT: el host no concede a un guest ninguna capacidad ambiental — sin red, sin sistema de archivos, sin entorno, stdio descartado, un reloj de pared observable congelado en un instante invariante entre compilaciones — así que un plugin no puede romper las garantías ahead-of-time del compilador. La superficie completa de capacidades — la regla de módulos de importación en la carga, las denegaciones en el momento de la instanciación y las funciones host seleccionadas — es el contrato del sandbox más abajo. Los autores de Plugin se dirigen al host a través del PDK en tres lenguajes (Go, Rust, TypeScript). aggrega lint invoca el socket del linter — el linter de publicación estándar — a través del host. aggrega build invoca los roles de tiempo de compilación del socket de gobernanza cuando un espacio de trabajo los configura: el rol annotation-transform durante la resolución y el rol label-transform en la construcción de la topología (ambos dan forma a la salida), además del veredicto IR en el análisis estático y el veredicto de renderizado sobre los artefactos renderizados. Cada uno es una operación nula cuando no hay ningún plugin vinculado a ese rol, así que una compilación sin configuración de gobernanza no cambia. aggrega build invoca también el pipeline: de la FeatureRecipe y la Recipe en el pipeline de plugins que cierra el renderizado — cada paso declarado se ejecuta a través del host sobre el conjunto de documentos renderizados, aplicando los parches RFC 6902 del paso y emitiendo sus efectos secundarios. Consulta Estado del lenguaje → Fases del pipeline de compilación.

El contrato del sandbox

Cada socket invoca su plugin a través del mismo sandbox del host. El sandbox tiene dos capas independientes — una comprobación estructural en la carga y la denegación de capacidades en la instanciación — y juntas definen lo que un plugin puede alcanzar, lo que no puede alcanzar y aquello de lo que es responsable.

La regla de módulos de importación (en la carga). El cargador recorre la sección de importaciones del binario del plugin y admite importaciones de funciones solo bajo tres espacios de nombres de módulo: wasi_snapshot_preview1 (el runtime WASI preview-1 con el que se enlaza el runtime de un lenguaje guest), extism:host/env (la ABI del runtime de Extism — los intrínsecos de memoria y E/S propios del PDK) y extism:host/user (las funciones host seleccionadas de Aggrega). Un guest puede importar cualquier nombre de función bajo un módulo permitido; una importación bajo cualquier otro módulo nombra una superficie que el host no proporciona, y el plugin se rechaza en la carga con un diagnóstico que nombra el módulo y la importación. La regla deliberadamente no censura nombres individuales de funciones WASI: el runtime de un lenguaje enlazado estáticamente importa funciones de sistema de archivos y de sockets que sus rutas de código activas nunca llaman — arrastradas de forma transitiva por las dependencias — y nombrar una importación no concede nada. Es la denegación de capacidades en la instanciación, y no la censura de importaciones, lo que garantiza que no haya E/S.

Ninguna capacidad ambiental (instanciación). El host instancia el guest con un comportamiento WASI real y ninguna autoridad ambiental:

  • sin sistema de archivos — sin directorios preabiertos, así que una llamada al sistema de archivos falla en el límite de la llamada;
  • sin sockets de red;
  • un entorno vacío;
  • stdio descartado — nada de lo que el guest escribe en stdout o stderr llega a los flujos del host;
  • un reloj de pared observable congelado, fijado en un instante invariante entre compilaciones, así que un guest que lee la hora no puede filtrar la hora de compilación a su salida;
  • un reloj monotónico real que avanza — el runtime de un lenguaje guest necesita uno para arrancar, y el tiempo monotónico mide una duración transcurrida, no un instante del reloj de pared;
  • entropía real del host — una entropía fijada estabilizaría la semilla de hash interna del runtime de un lenguaje y enmascararía el no determinismo del guest en lugar de dejar que aflore como salidas diferentes;
  • un único nombre de programa sintético como argv.

Una llamada de E/S que un guest realmente hace — abrir un archivo, conectarse a un socket — falla en el límite de la llamada. Es el propio modelo de seguridad de WASI basado en capacidades: el sandbox deniega la capacidad en lugar de vigilar el código.

Las entradas llegan solo a través de la carga útil y de las funciones host seleccionadas. Un plugin recibe todo lo que renderiza o evalúa en la carga útil que transporta su socket — proyecciones del grafo y de los nodos, valores y contexto de renderizado. La codificación en la que llega una carga útil está fijada por socket y se indica en la sección propia de ese socket más abajo; cada tipo de carga útil publicado incluye un punto de entrada de codificación y uno de decodificación para la codificación de su socket, así que un guest llama a una función en lugar de elegir un analizador. Para un renderizado de proveedor con fuente, la carga útil transporta un listado de la fuente en lugar de los bytes de la fuente: un conjunto ordenado de entradas {path, is_dir} bajo la raíz de la fuente del nodo, sin ninguna interpretación de la estructura del proveedor por parte del host. El guest aplica su propia lógica de estructura — seleccionar el único archivo compose, descender hasta la raíz de un chart, exigir un Chart.yaml, vendorizar un módulo de forma recursiva — y vuelve a leer exactamente la porción que selecciona mediante un callback del host. Más allá de la carga útil, el host expone un conjunto seleccionado de funciones host de mínimo privilegio, y concede a un plugin exactamente las que importa su binario:

  • aggrega_log — una línea de registro en el destino de registro del host.
  • aggrega_emit_warning — una advertencia estructurada que el host muestra después de la llamada.
  • aggrega_fetch_external_input — el canal de obtención de entradas externas (más abajo).
  • aggrega_pack_source — el callback de selección de la fuente: el guest nombra una selección {file | dir | tree, path} bajo la raíz de la fuente y el host lee y empaqueta exactamente eso dentro de un sandbox que resuelve las rutas bajo la raíz y rechaza ...
  • aggrega_read_source_file — una lectura del contenido de un único archivo dentro del mismo sandbox, para una selección de la fuente que depende del contenido.
  • aggrega_parse_source — el callback de consumo de productores: el guest nombra un formato sintáctico y entrega los bytes de la fuente, y el host resuelve un analizador para ese formato, lo ejecuta y devuelve el árbol canónico que produjo. Es la forma en que un consumidor obtiene la salida de un productor a través del host en lugar de invocar él mismo un guest productor, y el host lo limita a un solo nivel — un productor alcanzado de esta forma que vuelve a llamarlo es rechazado — así que un consumidor lo llama una vez por fuente y puede consumir muchas fuentes en secuencia.

El host deriva el conjunto que importa un plugin a partir de su binario .wasm, lo valida contra la lista de permitidos seleccionada y lo contrasta con las funciones host que declara el describe() del guest. aggrega plugin sync registra el conjunto en el spec.runtime.hostFunctions de la entidad, y una publicación rechaza una entidad cuyo registro difiere del binario, así que la superficie host de cada plugin es visible en el catálogo y no puede divergir del binario.

Los fallos de callback llevan un código comparable por máquina, bajo hostfunc_error_code. Los callbacks del host que devuelven una respuesta — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file y el callback de consumo de productores aggrega_parse_source — comunican el fallo en banda: el sobre de respuesta lleva un mensaje legible por personas y, junto a él, un código opcional comparable por máquina bajo hostfunc_error_code, tomado de un vocabulario cerrado. El mensaje es prosa libre para una persona; el código es la identidad estable sobre la que un guest se ramifica sin analizar el mensaje. En caso de éxito el código está ausente; en caso de fallo el host establece ambos. El PDK expone el par como un error tipado cuyo texto es el mensaje y cuyo campo de código un guest compara con las constantes de código reexportadas del lenguaje. Un guest tolera un código ausente y un código que no reconoce recurriendo al mensaje — así que comparar un código es un refinamiento de mejor esfuerzo superpuesto al mensaje siempre presente, nunca un sustituto de él. El conjunto cerrado de valores es el esquema de códigos de error de las funciones host.

🔴 Dos vocabularios distintos nombran un fallo en este límite, y la clave que lees indica cuál de ellos tienes entre manos. Confundirlos es el único error que merece la pena señalar aquí, porque un valor de cualquiera de los dos es una simple cadena y ni el host ni el guest comprueban de qué conjunto proviene.

  • hostfunc_error_code, en una respuesta que el host envía a un guest. Su valor es un miembro del catálogo cerrado enlazado arriba — una lista fija, que cambia lentamente, de las formas en que un callback del host puede fallar. Como el conjunto es cerrado, un guest puede comparar un valor con una constante con nombre que su kit reexporta y ramificarse según el resultado.
  • condition_code junto a condition_short_code, en una salida de socket que un guest devuelve al host. Son los dos identificadores de una condición de detención que el propio guest generó, y provienen del conjunto abierto y creciente de condiciones que el compilador registra, no del catálogo. condition_code es el código descriptivo con el que está registrada la condición; condition_short_code es la forma compacta — la letra E y cuatro dígitos — que un lector cita, busca y pega en un informe. El host imprime el código corto en la cabecera entre corchetes del diagnóstico que renderiza, así que una condición que genera un guest se puede citar exactamente igual que una que genera el compilador. No deriva ninguno de los dos valores, pero sí los comprueba: un código corto que no se resuelve en ninguna condición que este compilador declare, o que se resuelve en una cuyo número se ha retirado, detiene la compilación en lugar de llegar a un lector como un identificador que no se resuelve en nada.

Los dos identificadores del lado del guest se informan juntos: un guest que establece uno y no el otro ha nombrado una condición que el host no puede resolver, y entonces el host informa en su lugar de su propia condición genérica de fallo de plugin, con el mensaje que sigue llevando el fallo completo. Y un condition_code nunca es miembro del catálogo de funciones host, así que compararlo con una constante reexportada nunca coincide — por eso cada clave nombra su propio vocabulario en lugar del fallo en general.

Las ranuras de cada callback llevan una codificación declarada, y toda ranura que contiene un documento de carga útil lo contiene en binario. Cada argumento que recibe un callback del host es un puntero a la memoria del guest, salvo el nivel numérico de aggrega_log; un callback que devuelve una respuesta también responde con un puntero. Lo que contiene cada una de esas ranuras está fijado por callback:

CallbackRanuras de argumentoRanura de respuesta
aggrega_log, aggrega_emit_warningTexto UTF-8 — ningún documento de carga útilsin respuesta
aggrega_fetch_external_inputuna URL UTF-8 sin más — ningún documento de carga útilCBOR canónico
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_sourceCBOR canónico (RFC 8949 §4.2.1)CBOR canónico

La tabla se divide según lo que contiene cada ranura y no según la identidad del callback: una ranura que contiene un documento de carga útil transporta CBOR canónico, y una ranura que contiene una cadena simple — una línea de registro, un campo de diagnóstico, una URL — transporta texto UTF-8. aggrega_fetch_external_input es el único cuyas dos ranuras difieren: su argumento es una URL sin más, leída como texto UTF-8, y su respuesta es un documento de carga útil en CBOR canónico.

Qué hace un guest en una ranura que lleva una carga útil, y qué no debe hacer. 🔴 Una ranura que contiene un documento de carga útil contiene una secuencia de bytes opaca, no texto UTF-8 — así que esta es la forma que declara un guest, no solo los bytes que pone ahí. Un guest que asigna una solicitud así como cadena, o lee una respuesta así como cadena, no interopera: una conversión de texto en cualquiera de los dos sentidos corrompe los bytes binarios. El fallo es manifiesto en lugar de parcial — una solicitud que el host no puede decodificar vuelve como un sobre de respuesta que lleva el código request_undecodable, con la misma forma en banda que cualquier otro fallo de callback, así que el guest lo informa en lugar de continuar con una carga útil leída a medias. Los tipos de carga útil son SourcePackRequest y SourcePackResponse para aggrega_pack_source, SourceFileRequest y SourceFileResponse para aggrega_read_source_file, ParseInput y ParseSourceResponse para aggrega_parse_source, y solo el tipo de respuesta FetchExternalInputResponse para aggrega_fetch_external_input, cuya URL se asigna como texto. En concreto, por kit:

  • Go — construye la solicitud con EncodeCBOR() del tipo de solicitud, asígnala con pdk.AllocateBytes (no pdk.AllocateString) y lee la respuesta con ReadBytes() sobre la memoria a la que se resuelve el puntero de respuesta, hacia DecodeCBOR del tipo de respuesta. La URL de obtención es la excepción del lado de la solicitud, asignada con pdk.AllocateString; su respuesta se lee como cualquier otra. La declaración //go:wasmimport es un puntero en ambos casos, así que nada en la firma muestra la forma — esta reside en la asignación y en la lectura.
  • Rust — la declaración #[host_fn] indica la forma directamente: cada uno de los tres callbacks de carga útil se lee fn <callback>(request: Vec<u8>) -> Vec<u8>;, y el callback de obtención se lee fn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Construye la solicitud con encode_cbor() del tipo de solicitud y lee la respuesta con decode_cbor(&raw) del tipo de respuesta.
  • TypeScript — construye la solicitud con la función encodeCBOR… del tipo de solicitud, asígnala con Memory.fromBuffer (no Memory.fromString) y lee la respuesta con readBytes() hacia la función decodeCBOR… del tipo de respuesta. La URL de obtención se asigna con Memory.fromString; su respuesta se lee con readBytes() como las demás. Como en Go, la entrada declare module es un puntero en ambos casos.

Un guest que llama a un wrapper del PDK no necesita nada de eso. Los wrappers — FetchExternalInput, PackSource, ReadSourceFile y ParseSource, con la grafía propia de cada lenguaje — hacen la asignación y la codificación, y ninguna de sus firmas nombra un tipo de transmisión, así que un guest que llega a estos callbacks a través de su kit no asigna ni decodifica nada por sí mismo; un guest que declara y llama por sí mismo a las funciones host asigna y lee su memoria como se describe arriba. Una solicitud asignada como texto se rechaza en lugar de atenderse a medias, y una respuesta leída como texto no se puede decodificar, así que una discrepancia entre los dos lados es manifiesta en lugar de silenciosa.

Dos propiedades en las que confiar. La respuesta lleva la misma codificación tanto si tiene éxito como si falla: un guest lee una sola ranura y no puede saber antes de decodificar cuál de los dos casos contiene, así que un solo punto de entrada de decodificación lee ambos, y el código de error y el mensaje descritos arriba llegan a través de él. Y un guest rellena un campo con valor de bytes en el tipo de campo propio de su kit — un slice de bytes en Go, una cadena base64 en Rust y TypeScript — porque la conversión a la secuencia de bytes en bruto que transporta la codificación binaria es tarea del codificador generado, hecha a la salida y revertida a la entrada. Eso cubre los bytes de la fuente de ParseInput, el contenido del archivo que devuelve aggrega_read_source_file, el contenido que obtuvo aggrega_fetch_external_input y el contenido de cada archivo empaquetado en una respuesta pack-source: esos bytes cruzan el límite una sola vez en lugar de codificados dos veces, y ningún guest codifica en base64 nada que el codificador esté a punto de decodificar de base64. El campo content de las respuestas read-source-file y fetch se omite cuando está vacío, así que la respuesta para un archivo vacío o una carga útil obtenida de longitud cero no lleva ningún contenido; tal respuesta sigue siendo un éxito, porque un fallo siempre lleva su mensaje y su código, y el wrapper de cada kit devuelve bytes vacíos para ella. El árbol que devuelve aggrega_parse_source viaja como una secuencia de bytes que contiene su propio documento JSON tal cual; el host no lo lee ni lo remodela. Un analizador lee el mismo ParseInput, con la misma codificación, en su propio export parse — consulta el socket de analizador.

Canónico significa que una entrada idéntica produce bytes idénticos en cada lado, que es lo que permite comparar una carga útil entre los tres kits de plugins en lugar de solo hacerle un viaje de ida y vuelta, y es la razón por la que la salida de una compilación se mantiene idéntica byte a byte. No se necesita ninguna biblioteca CBOR en un guest y nada analiza bytes a mano: cada tipo de carga útil publicado incluye los puntos de entrada de codificación y decodificación que necesita la codificación de su ranura.

El determinismo es responsabilidad del autor del plugin. El host consume los bytes de salida de un guest tal cual y no les aplica ningún serializador, así que el contrato que todo plugin debe cumplir es: una entrada idéntica produce bytes de salida idénticos. El sandbox elimina las fuentes ambientales de no determinismo — la hora del reloj de pared, el entorno, el estado del sistema de archivos — pero deliberadamente no enmascara el resto: un guest que codifica entropía o tiempo monotónico transcurrido en su salida produce bytes visiblemente distintos entre ejecuciones en lugar de un defecto oculto de forma estable.

El canal de obtención de entradas externas. aggrega_fetch_external_input es el único canal sancionado para el contenido remoto, y está mediado por el host, no es un acceso del guest a la red: el guest nombra una URL y el host sirve los bytes según la disciplina de fijación de entradas externas. Una URL fijada en el archivo de bloqueo de la Release se sirve desde el almacén local direccionado por contenido y se verifica contra su digest registrado; una URL no fijada se rechaza con un diagnóstico que nombra la URL y el paso que la fija, porque un renderizado consume el cierre que registra su archivo de bloqueo y nunca lo amplía. Las fijaciones se escriben cuando se resuelven las dependencias de la Release, que es el único momento en que se fija algo. La guía para desarrolladores contiene las instrucciones de creación y la disciplina de fijación al completo.

Mapas que conservan su orden

Algunos mapas que transporta una carga útil están marcados como mapas que preservan el orden en el esquema de su socket, porque el orden de sus entradas forma parte de lo que transportan: los nodos de una compilación, las etiquetas de un nodo, las vinculaciones de un nodo, las entradas y salidas de un paso del pipeline, los espacios de claves que declara un proveedor. Los tipos de carga útil publicados guardan cada uno de esos mapas en un contenedor que mantiene sus entradas en el orden en que se establecieron:

KitContenedor
Goaggrega.OrderedMap[V] — el nombre que da el kit a abi.OrderedMap[V] del paquete ABI
RustOrderedMap<V> del crate aggrega-abi, reexportado por el kit
TypeScriptel Map<string, V> propio del lenguaje

Los contenedores de Go y Rust ofrecen las operaciones de un mapa — buscar una clave, establecerla, eliminarla, leer las claves, recorrer las entradas en orden, contarlas. Establecer una clave que el contenedor ya contiene sustituye su valor y conserva su posición; una clave nueva va después de todas las existentes.

El orden sobrevive a ambas codificaciones. En la codificación binaria, un mapa marcado se escribe como una lista ordenada de entradas — cada entrada una lista de dos elementos, la clave y luego el valor — en el orden del contenedor, donde la codificación canónica escribiría de otro modo un mapa con sus claves ordenadas. En la codificación de texto es un objeto JSON cuyos miembros se escriben en el orden del contenedor. Un decodificador, en cualquiera de las dos codificaciones, rechaza un mapa que repite una clave, indicando la clave. Un mapa que el esquema no marca conserva la forma de mapa ordenado por claves en la codificación binaria y el tipo de mapa ordinario de un lenguaje en los tipos publicados.

Tres consecuencias para un guest:

  • El orden es salida. Como un mapa marcado se escribe en el orden en que se llenó, un guest que llena uno a partir de una fuente sin orden fijo — iterando un mapa nativo de Go, por ejemplo — escribe bytes que difieren entre ejecuciones con una entrada idéntica. Llénalo en un orden fijo.
  • El orden se mantiene solo mientras el mapa permanece en su contenedor. Un guest que convierte una carga útil en un tipo de valor genérico de su propio lenguaje obtiene en su lugar el orden de ese tipo: un map[string]any de Go no tiene ninguno, y el serde_json::Value de Rust mantiene ordenadas las claves de los objetos salvo que el crate se compile con su funcionalidad preserve_order.
  • En TypeScript, lee y escribe a través de las funciones generadas. Un tipo que contiene un mapa marcado decodifica su JSON miembro a miembro, de modo que una clave que se lee como un índice de array, como "8080", conserva su posición donde JSON.parse la movería al principio del objeto; y su codificador escribe cada Map como un objeto, donde JSON.stringify escribe un Map como {}. Object.keys de un Map también está vacío: lee las claves de un Map con su propio keys().

Valores que una entrada marca como sensibles

Un plugin nunca cita, en un rechazo o una advertencia que devuelve, un valor que su entrada marca como sensible — por su clave, o como parte de una carga útil marcada en su totalidad. Un rechazo es el error que lleva una salida; una advertencia es un Diagnostic que lleva la salida, sea cual sea su severidad, o una emitida a través de aggrega_emit_warning. El host reproduce ese texto sin cambios dondequiera que lo informa — la línea de comandos, el servidor de lenguaje y la lista de problemas del editor, las herramientas del asistente — y no lee ningún valor de él, así que el plugin es la única parte capaz de mantener fuera el valor. Indica en su lugar la clave, el ajuste o la posición: desde ahí un lector encuentra el valor.

La regla cubre el texto que una biblioteca escribe para el plugin tanto como el texto que el plugin escribe por sí mismo. Un motor de plantillas informa de los datos que estaba evaluando, un validador de esquemas cita un valor que no cumple un pattern, un analizador cita el token que no pudo leer. Donde un fallo así se produjo sobre un valor que la entrada marca, infórmalo sin el valor — por ejemplo, ejecuta de nuevo el mismo paso con cada valor marcado sustituido por un marcador de posición, informa del fallo de esa ejecución cuando falla en el mismo lugar y, en caso contrario, indica que el texto del fallo se retiene. Bajo una carga útil marcada en su totalidad, cada valor de esa carga útil es un valor marcado, mientras que sus claves — la forma del documento — siguen siendo legibles.

Dónde una entrada marca como sensible una clave o una carga útil, escrito como lo nombran los datos transmitidos:

Socket y exportDónde se lee el marcado
proveedor render_node y validate_node_input (RenderNodeInput)node.sensitive_rendered_keys: cada clave nombra una entrada de node.values cuando esos valores son los propios del Component, indexados por las hojas que declara — el valuesMapping de una Recipe escribe claves que ninguna declaración nombra, así que ninguna de ellas está marcada aquí — o una entrada del mapa attachments del contenedor de una carga de trabajo que lee una ranura declarada sensible. node.sensitive_values marca node.values en su totalidad: es true cuando un valuesMapping — el de la Recipe, o el de la FeatureRecipe de una vinculación — produjo esos valores y lee un valor que un autor declaró sensible. workload_projection.sensitive_workload marca del mismo modo cada valor de la carga de trabajo cuando la plantilla de la carga de trabajo lee uno, y cada entrada de artifacts_projection.entries lleva sensitive_content para su propio contenido, incluido el mensaje de un analizador sobre ese contenido. Cada entrada de omits lleva sensitive cuando la plantilla que produce su kind, su nombre o su namespace lee uno, y entonces cada campo de esa entrada es un valor marcado. Cada entrada de node.features lleva el marcado de su propia vinculación: sensitive_payload_leaves (las hojas values.<path> e infra.<path> que su Feature declara sensibles), sensitive_inject (las claves de entrega inject que leen una clave provides que su Feature declara sensible) y sensitive (si la vinculación maneja o no material declarado sensible).
gobernanza ir-verdict (PolicyInput)graph: las sensitive_payload_leaves de cada nodo, y las sensitive_payload_leaves, sensitive_inject y sensitive de cada vinculación. Cada valor que nombran esos marcados llega ya como el marcador de retención {"aggrega_withheld": "declared"}, así que el valor en sí nunca llega al plugin.

Ninguna otra entrada de socket, ni la entrada de ningún otro export de proveedor, lleva un marcado. Un marcado de clave nombra solo lo que une exactamente a una declaración, así que una clave ausente nunca significa que un valor pueda citarse sin riesgo: significa que no se pudo unir ninguna declaración a esa clave. Un marcado de carga útil se lee de las referencias de la plantilla que produjo la carga útil — una referencia que alcanza un valor declarado, la plantilla que pasa la totalidad de sus datos, o una plantilla que no se puede analizar — y nunca de un valor, así que su ausencia significa que esa plantilla no leyó ningún valor declarado, hasta donde muestran sus referencias, o que ninguna plantilla produjo la carga útil; no es una afirmación de que la carga útil no lleve nada sensible.

Ubicación de los sockets Wasm en el pipeline

El pipeline de compilación reserva los siguientes puntos de socket. Las etiquetas de forma siguen la taxonomía de cuatro etiquetas de la página de estado.

SocketUbicación en el pipelineEstado actual
Socket de gobernanza, rol annotation-transformResolución (antes de la expansión de anotaciones)disponible — se invoca cuando un espacio de trabajo vincula un plugin annotation-transform; inyecta anotaciones que la expansión convierte en vinculaciones de Feature
Socket de gobernanza, rol label-transformConstrucción de la topología (el constructor de topología)disponible — se invoca cuando un espacio de trabajo vincula un plugin label-transform; etiqueta automáticamente los nodos mediante JSON Patch
Socket de gobernanza, rol ir-verdictAnálisis estático (el analizador estático, sobre el grafo IR)disponible — se invoca cuando un espacio de trabajo vincula un plugin ir-verdict; un veredicto halt detiene la compilación
Socket de gobernanza, rol render-verdictRenderizado (sobre los artefactos renderizados)disponible — se invoca cuando un espacio de trabajo vincula un plugin render-verdict; un veredicto halt detiene la compilación
Plugins de pipeline: de FeatureRecipe y RecipeEl pipeline de plugins (mutación posterior al renderizado)disponible — cada paso declarado se ejecuta sobre el conjunto de documentos renderizados, aplicando parches RFC 6902 y emitiendo efectos secundarios
Plugins de renderizado de Provider (helm, helm-chart, compose, terraform, cloudformation)Renderizado base (los proveedores)disponible — cada proveedor renderiza a través de su guest Wasm; el renderizado es solo Wasm, sin renderizador de respaldo dentro del host
Plugins de analizador (parse:<format>)Renderizado, para una política render-verdict; y fuera de banda, para una importacióndisponible — se llama para un artefacto en un formato que una política render-verdict no lee de forma nativa, para un importador a través de aggrega_parse_source, y para reconocer el formato de una importación que no indica ninguno
Plugins de importador (import:<format>)Fuera de banda (aggrega import)disponible — lo invocan aggrega import, la sesión del editor y la herramienta orientada al asistente
Plugins de linter (linter/publishing)Fuera de banda (aggrega lint)disponible — el linter de publicación se distribuye y se ejecuta a través del host mediante aggrega lint

La subfase de expansión de Feature guiada por anotaciones, parte de la resolución, es un paso nativo de Go en el pipeline, no un socket Wasm. Valida los valores de las anotaciones con el spec.schema de la Feature de destino e inyecta vinculaciones de Feature sintéticas en el momento de compilación del IR. Consulta vocabulary/labels-and-annotations.md para las seis superficies que llevan anotaciones y etiquetas y providers/well-known-annotations.md para la forma de los enlaces y la guía para escribirlos.

Contrato de forma de salida — lo que existe hoy

El socket de gobernanza ofrece una superficie de contrato tipada en cada uno de sus cuatro roles, y el rol determina cuál. Los autores de Plugin implementan código del lado del guest que produce las formas documentadas; el host las lee en tiempo de compilación, una vez por cada plugin configurado, cuando un espacio de trabajo vincula un plugin a ese rol. Las subsecciones siguientes siguen el orden en que el pipeline los invoca.

El rol annotation-transform — salida de inyección de anotaciones

Ubicación en el pipeline. Resolución, después de que se resuelven los componentes y antes de que se ejecute la expansión de Feature guiada por anotaciones.

Forma de entrada (host → guest). Un documento AnnotationTransformInput que contiene:

  • targets — los destinos de la inyección: los componentes resueltos que el guest puede anotar — los que un límite nombra directamente, y cada componente que una entrada de enrutamiento bajo los aggregates: de un límite hace entrar, tanto si la entrada lo nombra como si no — cada uno con su boundary_path, su component_name (para un componente enrutado, su id con puntos en el grafo de compilación, como metrics.query) y las annotations que la Release escribe en él, de modo que un guest puede decidir qué añadir sin desplazar un valor escrito por el autor. Cada valor de anotación llega tal como está escrito — una cadena, un objeto de subclaves, o null donde el componente renuncia a una anotación que heredaría — y cada clave que lleva el componente está presente sea cual sea su valor. Ordenados de forma determinista por el host.
  • binding_keys — las claves de anotación para las que el Manifest registra un enlace, en el orden del autor. Una inyección bajo una clave registrada se expande después en una vinculación de Feature, así que un guest lee esta lista para inyectar claves que tendrán efecto. El host no exige que una inyección nombre una clave registrada: una anotación inyectada no registrada se comporta exactamente como una anotación escrita por el autor sin enlace.
  • sources — los archivos de definición que la vinculación declaró bajo with.sources, cada uno con su ruta de nombre base y su contenido, ordenados por ruta.
  • settings — el objeto de ajustes de forma libre que la vinculación declaró bajo with.settings, entregado al guest tal cual.

settings y sources son el mismo canal with, agnóstico respecto al motor, que lee cada uno de los demás roles, y ambos están ausentes cuando la vinculación no declara ninguno. Como la salida de este rol da forma a la compilación, los ajustes y el contenido de las fuentes de la vinculación se fijan en el archivo de bloqueo de la release en el pull y se reconstruyen a partir de él en la compilación.

Forma de salida (guest → host). Un documento AnnotationTransformOutput que contiene:

  • injections — las anotaciones que se añaden, en orden. Cada una nombra una coordenada de destino existente (boundary_path y component_name) más la annotation_key y su annotation_value: una cadena, o un objeto de subclaves, que alimenta un enlace que enruta varias subclaves a la vez.

El host aplica solo adiciones de anotaciones, a coordenadas que él mismo proporcionó, cada una con un valor que un autor podría escribir en esa anotación. Lee un valor inyectado exactamente como lee el mismo valor escrito en la Release — las subclaves de un objeto en el orden en que el guest las escribió — de modo que la expansión lo encuentra como encuentra uno escrito por el autor. Una inyección que nombra una coordenada que la carga útil no lleva, o que lleva null, una lista, un número, un booleano o un objeto sin subclaves, detiene la compilación con un mensaje que nombra la coordenada y la anotación, en lugar de descartarse o aplicarse en silencio; toda la salida se comprueba antes de aplicar cualquier parte de ella. Ese confinamiento es lo que acota el rol: un operador que vincula aquí un plugin ha declarado la inyección de anotaciones y nada más. Donde la compilación rechaza más tarde una anotación inyectada por cómo enruta, por un valor de subclave que el esquema de la Feature enlazada no admite, o por un pilar que una anotación del lado de la Release no puede usar, su mensaje nombra el plugin que la inyectó y el rol al que está vinculado.

Codificación de transmisión. La carga útil y el resultado de este rol viajan como CBOR canónico (RFC 8949 §4.2.1), en ambas direcciones. Un guest los lee y los escribe a través de los puntos de entrada que llevan los tipos de carga útil — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, decodeCBORAnnotationTransformInput y encodeCBORAnnotationTransformOutput en TypeScript — así que no se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. En Rust el export recibe y devuelve Vec<u8>; en TypeScript lee Host.inputBytes() y escribe Host.outputBytes(...). Las annotations de cada destino son un mapa que el esquema marca como mapa que preserva el orden, así que viajan como una lista ordenada de entradas en el orden en que el destino las guarda, y un guest las lee a través del contenedor de su kit que mantiene el orden; cada valor viaja como los bytes de su JSON, como hace el annotation_value de una inyección en la otra dirección. settings viaja como los bytes de su documento JSON, que un guest analiza como JSON para examinar su contenido. Una respuesta que no es un AnnotationTransformOutput en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — detiene la compilación, nombrando el plugin y su export, en lugar de leerse como una lista vacía de inyecciones. Llamado directamente con aggrega plugin run-local --export transform_annotations, un guest recibe la carga útil JSON escrita por el autor convertida a esta codificación, y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Definiciones de tipos. Los tipos de transmisión de annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — se publican en los tres paquetes ABI, generados a partir de un único códec para que los tres sigan sincronizados.

El rol label-transform — salida JSONPatch

Ubicación en el pipeline. Construcción de la topología, después de que el grafo se aplana y antes de que se construya el grafo IR, de modo que los selectores de socket y de Feature que evalúa el analizador leen las etiquetas que deja el rol.

Forma de entrada (host → guest). Un documento MutatorInput que contiene:

  • compilation_context — la identidad de la release (release_name, environment).
  • graph — una proyección MutatorGraph de los nodos de la topología: de cada nodo, su Component, la versión resuelta, las etiquetas y los values que declara su instancia.
  • settings — el objeto de ajustes de forma libre que la vinculación declaró bajo with.settings, entregado al guest tal cual.
  • sources — los archivos de definición que la vinculación declaró bajo with.sources, cada uno con su ruta de nombre base y su contenido, de modo que un mutador puede guiarse por un archivo de reglas o de mapeo versionado en lugar de por ajustes en línea.

El grafo es una proyección y no el grafo IR: cada nodo lleva su conjunto de etiquetas resuelto y los valores que su instancia declara en el Aggregate, mientras que las aristas y las cargas útiles de las funcionalidades permanecen dentro del compilador. Los valores son los del propio Aggregate, con sus plantillas ya evaluadas con sus parámetros, de modo que un valor elevado a un parámetro llega como el valor que proporcionó la Release; un valor predeterminado que declara el esquema del Component, y cualquier cosa que aporte una Recipe o una Feature, no están entre ellos, y un nodo que no declara valores no lleva ninguna clave values. Un valor que el Component del nodo declara sensible se retiene exactamente como lo retiene el veredicto sobre el grafo — se lee como {"aggrega_withheld": "declared"} — mientras que cada valor hermano al que no llega ninguna declaración llega tal como está escrito. Eso es lo que permite que una configuración que declaró el desarrollador decida una etiqueta — una base de datos cuyos valores habilitan una extensión vectorial promovida a datastore.aggrega.ai/engine: vector, por ejemplo. settings y sources son el mismo canal with, agnóstico respecto al motor, que leen los roles de veredicto; el host los pasa sin interpretar nunca su contenido. Como la salida de un mutador da forma a la compilación, los ajustes y el contenido de las fuentes de la vinculación se fijan en el archivo de bloqueo de la release en el pull y se reconstruyen a partir de él en la compilación, de modo que la entrada del mutador es invariante ante un cambio de cualquiera de los dos posterior al pull, hasta el siguiente pull.

Forma de salida (guest → host). Un documento MutatorOutput que contiene:

  • patches — un array de documentos JSONPatch opacos (RFC 6902) que el host aplica únicamente a las etiquetas de los nodos; los valores que llevaba la entrada son de solo lectura.

Cada parche direcciona las etiquetas de un nodo concreto mediante JSON Pointer (RFC 6901); el host aplica los parches en el orden del array y vuelve a incorporar el conjunto de etiquetas modificado al grafo IR. La tarea del rol label-transform es el etiquetado automático empresarial — añadir etiquetas de cumplimiento / observabilidad / atribución de costos declaradas por la política de la empresa sin modificar el contenido del catálogo. La superficie de etiquetas es el único destino autorizado de este rol: un parche que toca un campo del nodo distinto de sus etiquetas, añade o elimina un nodo, o establece un valor de etiqueta que no es una cadena detiene la compilación en lugar de absorberse en silencio. RFC 6901 es la base de referencia de la gramática de rutas para cada superficie de ruta de documento en Aggrega — el contrato de plugins Wasm aquí, más los exports *_path de .locals, más los campos de esquema *Path en otras partes del corpus. Consulta 02-naming-conventions.md «Disciplina de sufijos de nomenclatura de rutas de documento» para la declaración canónica de esa base de referencia y la disciplina de sufijos *Path / *_path que distingue los dos lados de la escritura.

Codificación de transmisión. La carga útil y el resultado de este rol viajan como CBOR canónico (RFC 8949 §4.2.1), en ambas direcciones. Canónico significa que una entrada idéntica produce bytes idénticos en cada lado, lo que permite comparar una carga útil entre los tres kits de plugin en lugar de solo codificarla y volver a decodificarla, y es la razón por la que la salida de una compilación sigue siendo idéntica byte a byte. Un guest los lee y los escribe a través de los puntos de entrada que ya lleva el tipo de carga útil de su kit — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, decodeCBORMutatorInput y encodeCBORMutatorOutput en TypeScript — así que no se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. En Rust el export recibe y devuelve Vec<u8>; en TypeScript lee Host.inputBytes() y escribe Host.outputBytes(...). Los nodes del grafo, las labels de cada nodo y los values de cada nodo son mapas que el esquema marca como mapas que preservan el orden, así que viajan como listas ordenadas de entradas — los nodos en el orden en que la compilación los guarda, que es el orden del autor, las etiquetas de cada nodo en el orden en que el nodo las lleva, y los valores de cada nodo en el orden en que el Aggregate los escribe — y un guest lee los tres a través del contenedor de su kit que mantiene el orden. Cada valor viaja como los bytes de su documento JSON: los kits de Go y Rust se lo entregan al guest como ese JSON, para analizarlo tanto como necesite una regla, y el kit de TypeScript como el valor ya analizado.

Dos cosas que esto no cambia. El array patches sigue siendo JSON: el socket lleva cada documento de parche tal cual como contenido opaco y ninguno de los dos lados lo lee por dentro, así que la forma propia de un documento de parche es independiente de la codificación que lleva su socket. Y settings y sources se siguen entregando tal cual — settings llega como los bytes que escribió la vinculación, que un guest analiza como JSON si necesita examinar su contenido.

Todos los demás roles de gobernanza llevan la misma codificación — el rol annotation-transform y los dos roles de veredicto lo dicen cada uno en su propia sección — así que un guest que sirve más de un rol habla CBOR canónico en cada rol que sirve, leyendo cada carga útil a través del punto de entrada de decodificación de su propio tipo.

Definiciones de tipos. Los tipos de transmisión del mutador — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — se publican en los tres paquetes ABI (github.com/aggrega-ai/aggrega-abi/go, el crate aggrega-abi y @aggrega-ai/aggrega-abi), generados a partir de un único códec para que los tres sigan sincronizados. El host ensambla la entrada y aplica los parches que devuelve el guest.

Los roles de veredicto — salida de array de veredictos

Un guest de política inspecciona una compilación y devuelve una lista de veredictos; el host actúa según la severidad de cada veredicto y nunca interpreta la política en sí. El tratamiento completo — los cuatro roles, las severidades, el canal de entrada proporcionado por el operador, la escritura de una política para cualquiera de los dos motores que se incluyen dentro del compilador, el encapsulado de un motor de políticas externo, los guests de referencia y cómo un operador vincula una política — está en la página del socket de gobernanza. Esta sección recoge la ubicación en el pipeline y las formas tipadas de transmisión.

Ubicación en el pipeline. Una política se vincula exactamente a un rol de veredicto, que determina dónde se evalúa:

  • ir-verdict — se evalúa en el análisis estático, antes del renderizado base. El analizador ensambla la carga útil en cada compilación.
  • render-verdict — se evalúa después del renderizado, sobre los artefactos emitidos.

Cuando un espacio de trabajo vincula un plugin de un rol de veredicto, el pipeline serializa la carga útil de ese rol hacia el plugin y vuelve a leer sus veredictos.

Forma de entrada (host → guest). El rol selecciona la carga útil:

  • El PolicyInput de ir-verdict lleva graph — el grafo IR completo, agnóstico respecto a las capacidades (la misma forma que emite el constructor de topología), con cada detalle de nodos, aristas y vinculaciones que tiene el compilador, salvo que un valor que un autor declaró sensible llega retenido (consulta Valores que una entrada marca como sensibles) — y precalculated_paths, las rutas de enrutamiento que el analizador enumera junto a él, de modo que una política puede razonar sobre la alcanzabilidad sin volver a recorrer el grafo. El grafo es el grafo IR versionado, con su única fuente en el esquema ir-v1beta1; la forma del IR no es secreta (es el mismo grafo que emite aggrega inspect) y los secretos que contiene son punteros, nunca texto plano.
  • El RenderPolicyInput de render-verdict lleva artifacts — los archivos de salida renderizados ordenados por ruta, de modo que los datos transmitidos son idénticos byte a byte entre ejecuciones con una entrada idéntica. Cada entrada lleva el path de salida del artefacto y su content renderizado; también lleva el format en el que se renderizó, cuando el proveedor que lo produjo declaró uno, y un tree, la vista canónica analizada de un formato que el guest no lee de forma nativa, que el host analiza mediante el analizador resuelto y pasa de forma opaca. Ambos están ausentes cuando no corresponden — un formato que el guest lee de forma nativa (JSON, YAML) se deja sin analizar para que el guest lo lea de content.

Ambos roles llevan además las sources de la vinculación (archivos de definición de políticas que el host lee en tiempo de compilación y entrega al guest tal cual, con las rutas como nombres base y el contenido opaco) y los settings (un objeto de forma libre que se pasa sin modificar). Ambos están ausentes cuando la vinculación no declara ninguno.

Forma de salida (guest → host). Un documento PolicyOutput que contiene:

  • results — un array de entradas Diagnostic, cada una con una severity (halt, warn o info) y una cadena message. Un veredicto también puede establecer code, rule_id, classification, source_ref, location y suggest en la misma entrada; el host añade al veredicto mostrado cualesquiera de ellos que llevara el veredicto, en cada ruta de severidad.

Solo aparecen los veredictos disparados; una evaluación que permite devuelve un array vacío. El host recorre los veredictos y asigna a cada severidad una acción: halt detiene la compilación (mostrando cada mensaje halt), warn señala el veredicto y deja que la compilación continúe, info lo registra sin afectar al resultado. Un halt detiene la compilación a través del mismo punto de control que usa una infracción de un selector o de appliesTo.

Codificación de transmisión. Las cargas útiles de ambos roles, y el PolicyOutput que un guest devuelve en cualquiera de ellos, viajan como CBOR canónico (RFC 8949 §4.2.1). Un guest los lee y los escribe a través de los puntos de entrada que llevan los tipos de carga útil — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput y encodeCBORPolicyOutput en TypeScript — así que no se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. En Rust cada export recibe y devuelve Vec<u8>; en TypeScript lee Host.inputBytes() y escribe Host.outputBytes(...). Los mapas del grafo que preservan el orden, entre ellos sus nodes y las labels de cada nodo, viajan como listas ordenadas de entradas en el orden en que la compilación los guarda, y un guest los lee a través del contenedor de su kit que mantiene el orden; en qué orden los encuentra una política con cada motor de políticas se explica en la página del socket de gobernanza. settings, y el tree analizado de un artefacto, viajan como los bytes de sus documentos JSON, que un guest analiza como JSON para examinar su contenido. Una respuesta que no es un PolicyOutput en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — detiene la compilación, nombrando el plugin y su export, en lugar de leerse como una lista vacía de veredictos. Llamado directamente con aggrega plugin run-local --export verdict_ir o --export verdict_render, un guest recibe la carga útil JSON escrita por el autor convertida a esta codificación, y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Definiciones de tipos. Los tipos de transmisión de las políticas se publican en los mismos tres paquetes ABI: PolicyInput (rol ir-verdict), RenderPolicyInput (rol render-verdict), el PolicySource compartido y PolicyOutput, cuyas entradas results son valores Diagnostic. La severidad de un diagnóstico es uno de tres valores que comparten todos los sockets — halt, warn o info — y los tres se publican como constantes junto a los tipos de transmisión en cada uno de los tres paquetes, de modo que un guest informa a partir del mismo conjunto cerrado sobre el que enruta el host. Un guest que devuelve cualquier otro valor detiene la compilación, con el mensaje nombrando el plugin y el valor que devolvió: una severidad que no se puede enrutar es un defecto del plugin que el host informa, en lugar de un diagnóstico que descarta.

Contrato de forma de salida — el pipeline de FeatureRecipe y los sockets de proveedor

Los sockets siguientes ofrecen superficies de contrato tipadas que el compilador invoca en tiempo de compilación. Los pasos de pipeline: de FeatureRecipe y Recipe se ejecutan en el pipeline de plugins sobre el conjunto de documentos renderizados; el socket de renderizado de proveedores se ejecuta en el renderizado base; el linter de publicación se ejecuta fuera de banda.

Parches RFC 6902 (el pipeline de plugins)

Los pasos de pipeline: de FeatureRecipe y Recipe que se ejecutan en el pipeline de plugins emiten operaciones JSON Patch RFC 6902 sobre el conjunto de documentos renderizados. El host entrega a cada paso el conjunto de documentos indexado por clave completo; el paso selecciona por contenido los documentos a los que se dirige y devuelve parches direccionados por clave, que el motor de aplicación aplica a los documentos direccionados — normalmente añadiendo un contenedor sidecar, montando un volumen de secreto o reescribiendo una variable de entorno. Un paso también devuelve side_effects (más abajo), diagnostics — cada entrada con la misma forma compartida Diagnostic en la que cada socket informa de los problemas — y outputs (más abajo). Descrito en examples/04-secrets.md.

Estado actual: disponible. Cada paso declarado se ejecuta durante aggrega build.

Codificación de transmisión. La entrada de un paso (FRPStepInput) y su respuesta (FRPStepOutput) viajan como CBOR canónico (RFC 8949 §4.2.1), en ambas direcciones. Un guest decodifica su entrada y codifica su respuesta a través de los puntos de entrada que llevan los tipos de carga útil — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust (sobre los tipos que publica el crate aggrega-abi), decodeCBORFRPStepInput y encodeCBORFRPStepOutput en TypeScript — leyendo y escribiendo bytes (Vec<u8> en Rust, Host.inputBytes() y Host.outputBytes(...) en TypeScript). No se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. La entrada with del paso (step_input), los outputs que devuelve y los conjuntos de documentos own y host son mapas que el esquema marca como mapas que preservan el orden, así que viajan como listas ordenadas de entradas en el orden en que el pipeline los guarda, y un guest los lee y los escribe a través del contenedor de su kit que mantiene el orden — que es lo que permite que las salidas de un paso lleguen a .steps.<id>.outputs en el orden en que el paso las devolvió. El tree de cada unidad, cada valor de step_input y outputs, el value de un parche, el crd de un efecto secundario y el context de renderizado viajan como los bytes de sus documentos JSON, que un guest analiza como JSON para examinar su contenido; los bytes de una unidad viajan como una secuencia de bytes en bruto que el decodificador generado vuelca en el tipo de campo propio del kit — un slice de bytes en Go, una cadena base64 en Rust y TypeScript. Cada diagnóstico viaja en la forma compartida Diagnostic. Una respuesta que no es un FRPStepOutput en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — hace fallar el paso, nombrando la función que ejecuta, lo que detiene la compilación salvo que el paso sea optional. Llamado directamente con aggrega plugin run-local --export step, un paso recibe la carga útil JSON escrita por el autor convertida a esta codificación, y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Efectos secundarios — emisión de recursos (plugins de credenciales en el pipeline de plugins)

Los pipelines de FeatureRecipe de credenciales (principio del Plugin en dos partes: Fetcher + Injector) emiten recursos completos junto a un parche a través de los side_effects de un paso, cada uno de los cuales declara uno de los dos tipos que define el contrato: emit_crd, un documento de recurso personalizado como una CRD ExternalSecret o VaultSecret que el clúster obtiene en tiempo de ejecución, o emit_file, un archivo escrito. Un paso que devuelve cualquier otro tipo detiene la compilación, nombrando el nodo, el índice del efecto secundario y el tipo que declaró. El paso del Fetcher emite el recurso completo; el paso del Injector devuelve un parche que monta el Secret de Kubernetes resultante. Descrito en examples/04-secrets.md.

Estado actual: disponible.

Salida de un paso (mapa outputs de un paso de pipeline:)

Un paso del pipeline de plugins publica salidas con nombre que los pasos posteriores consumen mediante {{ .steps.<id>.outputs.<key> }}. La forma de salida la define el proveedor para cada plugin; las salidas de los pasos tienen como ámbito el mismo pipeline y solo son visibles para los pasos posteriores en el orden de declaración. Documentado en templates/expansion-matrix.md, fila 10.

Estado actual: disponible.

Renderizado de Provider — el socket dirigido por el guest

Un proveedor es un guest Wasm. El renderizado es solo Wasm: el nombre de capability: de una Recipe se resuelve en el Plugin de renderizado de proveedores (pluginType: provider) que enumera ese nombre en sus spec.provider.capabilities y anuncia un export render_node, y el guest de ese plugin renderiza el nodo. No hay ningún renderizador dentro del host al que recurrir; un nombre de proveedor que no se resuelve en ningún Plugin que lo sirva detiene la compilación en el momento del enrutamiento. Añadir un proveedor estándar consiste en distribuir un guest .wasm y una entidad Plugin del catálogo — el host no lleva código específico de ningún proveedor.

Una capacidad que sirve un proveedor no lleva dos puntos, y tampoco una con la que un paso de pipeline se declara compatible. El capability: de una Recipe se lee como la capacidad hasta sus últimos dos puntos, seguida de una fijación de versión — helm:1.0.0 pide helm en la versión 1.0.0 — así que un nombre que contiene dos puntos es uno que ninguna Recipe puede pedir. El host rechaza un nombre así en las capabilities de describe() para un guest provider o pipeline-step cuando el guest se carga y cuando su entidad se genera para su publicación, nombrando el guest y el nombre. El parse:<format> de un analizador y el import:<format> de un importador conservan sus dos puntos: se buscan por formato, nunca a través del capability: de una Recipe.

El host es un enrutador genérico. Lee el autoinforme describe() del guest — incluido su contrato de comportamiento de renderizado — y despacha los exports del guest sin entender ningún formato de proveedor. Ese contrato dirige el despacho como datos:

  • input_kinds (sourced, synthesized, artifacts_standalone) — qué tipos de entrada de Recipe renderiza el guest; el host comprueba el tipo de entrada de un nodo frente a este conjunto.
  • boundary_assembly (none | merge | nest) — cómo combina el guest la salida de un grupo de despacho: merge clasifica la salida de cada nodo como fragmentos que el ensamblador fusiona en un único artefacto, nest anida los archivos de cada nodo bajo un envoltorio ensamblado, none escribe directamente la salida de cada nodo.
  • nest_segment (opcional) — para un ensamblado nest, el directorio bajo el que se coloca el subdirectorio propio de cada contribuidor, escrito como un único nombre de directorio; si falta, el subdirectorio de cada contribuidor queda directamente en la posición de despacho.
  • assembly_name_annotation (opcional) — una anotación de límite cuyo valor resuelto da nombre al artefacto que el guest ensambla a partir de un grupo de despacho; si falta, el guest nombra su ensamblado solo a partir de la ruta de despacho.
  • cross_boundary_linking (opcional) — si el guest conecta una arista uses entre límites a través de sus exports link_publish y link_resolve; un guest lo declara verdadero exactamente cuando exporta ambos, y la carga rechaza un guest cuyo indicador y cuyos exports no coinciden.
  • artifact_delimiters (opcional) — el par de delimitadores de plantillas Go que el guest aplica a los cuerpos de los artefactos.
  • reusable_instance (opcional) — si una única instancia cargada puede servir cada cruce de la compilación (consulta Determinismo y reutilización de instancias más abajo).
  • omits (opcional) — si el guest respeta las entradas de omisión que lleva un renderizado de fuente (consulta Dejar fuera unidades renderizadas más abajo).
  • boundary_artifacts (opcional) — si el destino del guest acepta los archivos que una Recipe aporta a la salida compartida de su límite (consulta Aceptar los archivos que una Recipe aporta al límite más abajo).
  • source_ignore (opcional) — los archivos que el ecosistema del guest nunca distribuye junto a una fuente que renderiza (consulta Declarar lo que el ecosistema de una fuente nunca distribuye más abajo).

El socket es un conjunto fijo de exports — uno obligatorio, el resto opcionales y anunciados en describe():

  • render_node (obligatorio) — renderiza un nodo IR en archivos nativos del proveedor.
  • assemble_boundary (opcional) — fusiona la salida por nodo de un grupo de despacho en un único artefacto por ruta (presente cuando boundary_assembly es merge o nest).
  • validate_node_input (opcional) — validación estructural de la entrada de un nodo antes del renderizado; un diagnóstico halt detiene la compilación, un warn aparece en el resultado de la compilación.
  • carve / reassemble (opcionales, emparejados) — el códec de parches propio del guest, fiel byte a byte, para los pasos de pipeline posteriores al renderizado, que se usa solo cuando ambos están anunciados.
  • name_bound (opcional) — el guest juzga si un nombre que el host propone como identidad de un componente produce nombres que su destino acepta, respondiendo con una restricción en lugar de con un nombre propio.
  • rendered_name (opcional) — el guest informa del nombre que su destino da a los recursos que renderiza para un nodo.
  • link_publish / link_resolve (opcionales, emparejados) — el guest conecta una arista uses entre límites: el extremo consumido publica un identificador, y el extremo consumidor lo resuelve en su propia salida ensamblada.

Los artifacts: de una Recipe se integran en render_node mediante una proyección de artefactos en la entrada: el host realiza la lectura de $import, la evaluación de las plantillas Go y el cálculo de las claves/valores de procedencia, y entrega al guest cada entrada ya leída y evaluada; el guest se encarga de la ubicación y la emisión en el formato que solo él conoce. Documentado en architecture/13-catalog-and-registry.md.

La entrada de un renderizado de fuente lleva los valores del nodo en node.values, y node.values_mapped indica de dónde proceden: es true cuando son la salida del valuesMapping de la Recipe — o, para el renderizado propio de una vinculación, del de su FeatureRecipe — y está ausente cuando son los valores propios del componente entregados tal como están escritos. Que un guest lo lea o no forma parte del contrato propio de ese guest. El proveedor cloudformation enlaza los Parameters de una plantilla procedente de una fuente solo a valores que produjo un mapeo, porque los valores propios de un componente pueden haberse escrito para las otras entradas de la Recipe; el proveedor terraform escribe los argumentos de un módulo procedente de una fuente a partir de los valores que recibe su ensamblado, y no lee el indicador. Esos valores viajan en cada nodo renderizado de una entrada de assemble_boundary para un nodo renderizado a partir de una fuente — los de un componente, tanto si un mapeo los produjo como si no, los de una Feature vinculada solo donde los produjo el valuesMapping de su FeatureRecipe — y el mismo indicador viaja junto a ellos y solo donde ellos viajan, de modo que un ensamblador lee la misma respuesta que leyó el renderizado propio del nodo; el proveedor cloudformation lo lee ahí para saber qué parámetros rellenó el enlace de un nodo, y rechaza una referencia a uno de ellos desde cualquier otro lugar del stack, incluido el componente anfitrión de una Feature vinculada. El indicador registra cómo se produjeron los valores y nunca se deriva de una clave ni de un valor.

Codificación de transmisión. Cada export de este socket recibe su entrada y devuelve su salida como CBOR canónico (RFC 8949 §4.2.1), en ambas direcciones. Un guest decodifica su entrada y codifica su salida a través de los puntos de entrada que ya llevan los tipos de carga útil — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, y en TypeScript las funciones decodeCBOR y encodeCBOR de cada tipo, como decodeCBORRenderNodeInput y encodeCBORRenderNodeOutput — leyendo y escribiendo bytes (Vec<u8> en Rust, Host.inputBytes() y Host.outputBytes(...) en TypeScript). No se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. El content de un archivo renderizado, y cualquier otro campo de bytes, viaja como una secuencia de bytes en bruto que el decodificador generado vuelca en el tipo de campo propio del kit: un slice de bytes en Go, una cadena base64 en Rust y TypeScript. Los mapas que el esquema marca como mapas que preservan el orden — entre ellos los values, features y uses de un nodo, las derived_keys de una respuesta y los values de un contribuidor de un ensamblado — viajan como listas ordenadas de entradas en el orden en que la compilación los guarda, y un guest los lee a través del contenedor de su kit que mantiene el orden. Cada valor de los values de un nodo viaja como los bytes de su propio documento JSON, de modo que las claves dentro de un valor conservan el orden en que se escribieron; lo mismo ocurre con cada entrada de vinculación de features, el contexto de renderizado, la carga de trabajo analizada, cada arista enriquecida, cada unidad recortada y cada operación de parche, y un guest los analiza como JSON para examinar su contenido. Cada diagnóstico viaja en la forma compartida Diagnostic. Una respuesta que no tiene la forma de salida de su export en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — detiene la compilación, nombrando el export al que llamó. Los ejemplos de cargas útiles de esta página están escritos como JSON para facilitar su lectura. Llamado directamente con aggrega plugin run-local --export render_node, o con cualquier otro export del socket, un guest recibe la carga útil JSON escrita por el autor convertida a esta codificación, y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Estado actual: disponible para los cinco proveedores. El guest helm renderiza charts procedentes de una fuente (resolviendo la raíz del chart), cargas de trabajo sintetizadas y artefactos independientes como manifiestos planos de Kubernetes. El guest helm-chart ensambla un umbrella chart, anidando el chart procedente de una fuente de cada nodo como subchart, y lleva un códec de parches fiel byte a byte y delimitadores de artefacto entre corchetes ([[ ]]). El guest compose renderiza archivos compose procedentes de una fuente y cargas de trabajo sintetizadas y fusiona un grupo de despacho en un único docker-compose.yaml, uniendo un servicio a las redes de los componentes que nombra su x-aggrega-networks-of. El guest terraform emite la configuración de Terraform tal cual (HCL o JSON) o incorpora un módulo procedente de una fuente y suministra sus entradas como argumentos del bloque module de ese componente, valida estructuralmente el HCL de un módulo procedente de una fuente antes del renderizado, y compone un límite en una única configuración raíz que declara cada componente como un bloque module cuyo origen es el subdirectorio propio de ese componente. El guest cloudformation renderiza plantillas procedentes de una fuente y fragmentos de stack independientes, fusiona un grupo de despacho en una única plantilla de stack, y conecta una arista uses entre límites a través de link_publish y link_resolve. Cada uno renderiza sin conexión y de forma determinista.

Declarar los nombres que deriva un guest

Un guest de proveedor suele derivar nombres que su salida necesita pero que nadie escribió — el identificador con el que un destino se dirige a un recurso, el nombre con el que se publica una salida para que otra haga referencia a ella — a partir de la identidad del nodo y del recurso que está emitiendo. Dos nodos pueden llegar a un mismo nombre siempre que coincidan las partes de las que se derivan, y como el nombre vive dentro de los bytes del archivo que el host escribe tal cual, el host no puede ver el conflicto: tendría que analizar el formato del proveedor para encontrarlo, que es exactamente el conocimiento que permanece en el guest.

Por eso render_node devuelve en su salida unas derived_keys opcionales, y la dirección se invierte — en lugar de que el host inspeccione la salida, el guest declara y el host comprueba:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"derived_keys": {
"logical-ids": ["paymentsapiQueue", "paymentsapiTopic"],
"export-names": ["aggrega--prod--api--orders-db--host"]
}
}

Cada clave de derived_keys es un espacio de claves al que el guest da nombre, y cada espacio lleva los nombres que el guest derivó en él, en orden de derivación. Tanto los nombres de los espacios como los nombres dentro de ellos son tu vocabulario: el host los lee solo como cadenas que compara por igualdad dentro de un mismo espacio. No analiza ningún nombre, no aprende qué significa un espacio o un nombre y nunca deriva uno por sí mismo — así una sola comprobación cubre todo tipo de nombre que deriva cualquier proveedor, y un proveedor nuevo no necesita código nuevo en el host. En los tipos publicados, derived_keys es un mapa que mantiene el orden, de modo que los espacios viajan en el orden en que tu guest los establece.

Lo que el host hace con ellos se reduce a una sola pregunta: dentro de un espacio, ¿es cada nombre declarado distinto entre los contribuidores cuya salida se fusiona en un único ensamblado? Dos contribuidores que declaran un mismo nombre en un mismo espacio detienen la compilación, y la detención nombra el espacio, el nombre y ambos contribuidores, de modo que un autor puede actuar sin leer el proveedor. Los nombres distintos, y los nombres que coinciden por casualidad entre dos espacios diferentes, pasan.

Conviene conocer tres propiedades cuando decides qué declarar:

  • El ámbito es una salida ensamblada — el conjunto de contribuidores cuyos archivos se fusionan. Un guest que quiere unicidad en un ámbito más estrecho o más amplio que ese expresa el ámbito en el nombre del espacio que declara, lo que deja la elección en tus manos y no en las del host.
  • Un contribuidor puede repetir un nombre libremente. Un nodo puede renderizarse en varios cruces — un renderizado de fuente, una síntesis de carga de trabajo, una colocación de artefactos — y las declaraciones se fusionan. El mismo nombre declarado dos veces por un contribuidor es ese contribuidor describiendo un mismo recurso dos veces, no un conflicto.
  • Declarar no cambia ningún byte. El campo es una afirmación sobre lo que el guest derivó, nunca un cambio en lo que emitió, de modo que la salida renderizada de un guest es idéntica tanto si declara como si no. Omitir derived_keys es válido y deja la comprobación inactiva para ese guest.

Informar de hechos sobre lo que emitió un guest

Algunas cosas del renderizado de un nodo solo son visibles para el proveedor que lo produjo — qué contienen los documentos que escribió, qué nombres definen, cuántos elementos de algo emitió — porque extraerlas de los bytes del archivo supone entender el formato del proveedor. render_node puede informar de esas cosas por sí mismo, en una lista opcional render_facts junto a sus archivos:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

Cada hecho es un name y un value, y ambos pertenecen a tu proveedor: qué hechos informa, qué significa cada nombre y qué contiene cada entrada forman parte del contrato documentado propio de tu proveedor, así que documéntalos para los autores que los leerán.

Informa del valor de cada hecho como una lista — un array JSON — incluso cuando contiene una sola entrada. Un mismo nombre puede ser informado por más de un renderizado de un componente: su propio renderizado puede requerir varias llamadas — un renderizado de chart y una colocación de artefactos, por ejemplo — y cada Feature vinculada al componente se renderiza mediante una llamada al proveedor propia. Ningún proveedor puede saber, al renderizar, si su informe será el único bajo un nombre, así que cada informe es una lista, y el compilador une en una sola lista las listas que recibe un nombre. Un hecho cuyo valor sea cualquier otra cosa — un objeto, una cadena, un número, un booleano, null — se rechaza cuando tu guest lo devuelve: la compilación se detiene con el código corto E0325, nombrando el hecho, el nodo y tu guest, e indicando cuál era el valor. Las entradas dentro de una lista son valores JSON cualesquiera en la forma que documentes.

Que un valor sea una lista es lo único que el compilador aprende sobre él. Indexa los hechos por nombre y entrega cada lista a las plantillas que la leen — los hechos del componente anfitrión a cada Feature vinculada a él, los hechos de cada llamador a una Feature que declara que lee los hechos de renderizado de sus llamadores, y los hechos de cada destino a una Feature que declara que lee los hechos de renderizado de los componentes a los que está conectado su componente anfitrión, como describe el contexto de plantilla — decodificando cada lista en un valor que una plantilla puede recorrer. Nunca aprende qué significa un nombre o una entrada y nunca deriva un hecho por sí mismo, de modo que un proveedor nuevo puede informar de hechos nuevos sin ningún cambio del lado del compilador. Los hechos que una Feature vinculada al nodo informa desde su propio renderizado se mantienen separados de los que informó el renderizado propio del nodo.

Conviene conocer cuatro propiedades cuando decides qué informar:

  • El orden es tuyo. Los hechos mantienen el orden en que tu guest los enumera, y cada valor conserva sus propios bytes — el orden de las entradas de una lista y de las claves de cada objeto es el orden que escribió tu guest. Enumera los hechos en un orden fijo, y escribe cada entrada con un orden de claves fijo, para que los mismos datos de entrada produzcan bytes idénticos; una lista de hechos en lugar de un mapa existe precisamente para que ese orden sobreviva en el tipo de secuencia propio de cada kit sin nada que marcar, mientras que un mapa conserva el orden que escribió un guest solo cuando su esquema lo marca como mapa que preserva el orden y el guest rellena el contenedor que mantiene el orden de su kit.
  • Informar no cambia ningún byte. Los archivos que escribe el compilador son los archivos que devolvió tu guest, tanto si los acompañan hechos como si no.
  • Un nodo puede informar en varios cruces. Un nodo puede renderizarse como renderizado de fuente, síntesis de carga de trabajo y colocación de artefactos; los hechos que informa cada uno se mantienen en el orden en que se ejecutaron los cruces, y un nombre informado por más de uno de ellos se lee como una sola lista que los une en ese orden.
  • No informar de nada es completo. Omitir render_facts es válido, y un proveedor que no informa de nada renderiza exactamente como lo haría sin el campo.

El tipo RenderFact se publica en los tres paquetes ABI y lo reexporta el kit de desarrollo de plugins de cada lenguaje, y los ejemplos de renderizado de los kits informan de dos hechos junto a sus archivos. En Go, un valor es el JSON que escribe tu guest; serializar un slice de structs en lugar de mapas es lo que mantiene las claves de cada entrada en el orden en que las declaraste:

type stackFact struct {
Name string `json:"name"`
Resources int `json:"resources"`
}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})
if err != nil {
pdk.SetError(err)
return 1
}
out := aggrega.RenderNodeOutput{
Files: files,
RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},
}

Dejar fuera unidades renderizadas

Un renderizado de fuente puede nombrar unidades que el proveedor debe dejar fuera de lo que renderiza — un Secret que un chart obtenido genera de nuevo en cada renderizado, por ejemplo. Qué unidad renderizada nombra una entrada es un conocimiento que solo tiene tu proveedor, así que las entradas viajan hasta tu guest y es tu guest quien las deja fuera. Llegan en la entrada de render_node como una lista opcional omits junto al source_listing:

{
"node": { "id": "payments-api" },
"context": { },
"source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] },
"omits": [
{ "kind": "Secret", "name": "payments-api-token", "namespace": "payments" },
{ "kind": "ConfigMap", "name": "payments-api-dashboards" }
]
}

Cada entrada es un kind, un name y un namespace opcional, ya resueltos a cadenas simples y enumerados en el orden en que el autor los declaró; una entrada que no se aplica a la compilación no se transmite. Lo que seleccionan los tres campos es el contrato propio de tu proveedor — el tipo, el nombre y el namespace de un recurso en el formato de tu destino — así que documéntalo para los autores que escriben las entradas.

Un autor puede construir los campos de una entrada a partir de un valor que declaró sensible — un recurso con el nombre de un ajuste sensible, por ejemplo. Una entrada así llega con "sensitive": true, y tu guest la trata como trata cualquier otro valor marcado que lleva la entrada de renderizado (consulta Valores que una entrada marca como sensibles): sigue haciendo coincidir y contando la entrada por sus campos, que es para lo que sirve la entrada, y mantiene cada uno de sus campos fuera de un rechazo, una advertencia o una línea de registro. El marcado cubre la entrada entera, porque el compilador no dice qué campo produjo el valor. Está ausente cuando ningún campo se construyó a partir de un valor así.

Un guest que respeta las entradas hace tres cosas:

  • Hace coincidir cada entrada con lo que renderizó, en los términos de tu formato.
  • Deja cada unidad coincidente fuera de todo lo que devuelve — sus files, los nombres que declara en derived_keys y los hechos que informa en render_facts — de modo que nada de lo que recibe el compilador la sigue describiendo.
  • Informa de un recuento por entrada en una lista opcional omitted en su salida, en el orden en que llegaron las entradas, cada uno el número de unidades con las que coincidió esa entrada, contadas tanto si otra entrada también coincidió con ellas como si no:
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

Un cero es una respuesta completa: esa entrada no coincidió con nada de lo que renderizó tu guest. Los recuentos son todo lo que vuelve sobre lo que se dejó fuera; las unidades mismas simplemente están ausentes de lo que devolvió tu guest.

Un proveedor que hace las tres cosas lo declara con omits: true en su contrato. La entidad Plugin registra la misma declaración como spec.provider.contract.omits; donde la entidad lleva un contrato de comportamiento de renderizado, la carga rechaza un guest cuyo describe() informa de un valor distinto. Las entradas acompañan a un listado de la fuente y a nada más: un renderizado de una carga de trabajo sintetizada o de un conjunto de artefactos nunca las lleva.

Un renderizado que no lleva entradas no cambia por los campos. Ambos campos son opcionales y están ausentes cuando están vacíos, de modo que un renderizado que no lleva entradas atraviesa el socket byte a byte como lo haría si los campos no existieran, y a un guest que nunca los lee no le afectan. El tipo OmitEntry se publica en los tres paquetes ABI y lo reexporta el kit de desarrollo de plugins de cada lenguaje.

Qué hace el compilador con tu respuesta. Las entradas proceden de la clave omits: que un autor escribe en una Recipe o una FeatureRecipe (Recipe → El campo omits:); el compilador evalúa las plantillas de cada entrada y entrega a tu guest las que se aplican. Después lee tus recuentos, y solo tus recuentos — nunca mira dentro de un archivo devuelto para comprobarlos:

Estado actual: disponible. Los guests helm, compose y cloudformation distribuidos con el compilador hacen la declaración y respetan las entradas. El guest helm no escribe ningún campo de ninguna entrada en un texto que devuelve. Los guests compose y cloudformation nombran el tipo, el nombre y el namespace de una entrada cuando rechazan la entrada, y las unidades que una entrada dejó fuera cuando rechazan un archivo o una plantilla que aún las nombra, y muestran allí cada campo de una entrada marcada como <redacted>. Los guests helm-chart y terraform no hacen la declaración, así que se rechaza un documento que declara omits: y que renderiza uno de ellos.

Aceptar los archivos que una Recipe aporta al límite

Algunos archivos pertenecen a un límite en su conjunto y no a uno de sus componentes — una configuración de proveedor que un destino lee una sola vez para todo lo que el límite despliega, por ejemplo. Una Recipe los escribe bajo spec.boundary.artifacts, y es el compilador, no tu guest, quien hace el trabajo: evalúa cada archivo en el contexto en que se evalúa una entrada artifacts:, fusiona por nombre los archivos que declaró cada contribuidor del grupo de despacho, y escribe cada uno una sola vez en el directorio que contiene la salida ensamblada del grupo, junto a lo que devuelve tu assemble_boundary. Tu guest no recibe ninguno de estos archivos en ningún export y nunca se le pregunta por ninguno, así que no hay nada que implementar — solo una afirmación que hacer sobre tu destino:

"contract": {
"input_kinds": { "sourced": true, "artifacts_standalone": true },
"boundary_assembly": "nest",
"boundary_artifacts": true
}

Declara boundary_artifacts: true solo cuando tu destino lee un archivo colocado en ese directorio como parte de la salida del límite. La entidad Plugin registra la misma declaración como spec.provider.contract.boundaryArtifacts; donde la entidad lleva un contrato de comportamiento de renderizado, la carga rechaza un guest cuyo describe() informa de un valor distinto. Una Recipe que declara el bloque cuyo proveedor no lo declara se rechaza antes de que se renderice nada, nombrando el proveedor y el componente; consulta The provider does not support boundary artifacts (El proveedor no admite artefactos de límite). Un archivo que una de estas fusiones coloca bajo un nombre que tu ensamblado también escribe detiene la compilación como dos contribuidores que escriben una misma ruta de salida, así que los nombres que escribe tu ensamblado forman parte de lo que documentas para los autores.

Estado actual: disponible. El guest terraform distribuido con el compilador hace la declaración, y Terraform lee cada archivo junto a la configuración raíz del límite; los guests helm, compose, helm-chart y cloudformation no la hacen.

Declarar lo que el ecosistema de una fuente nunca distribuye

El directorio de fuente local de una Recipe — un chart ubicado junto a ella, un módulo — se publica con la Recipe, y no todos los archivos que contiene le pertenecen. Un guest de proveedor indica lo que su propio ecosistema nunca distribuye mediante source_ignore en su contrato, como reglas de exclusión en la sintaxis que usa .gitignore:

"contract": {
"input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false },
"boundary_assembly": "none",
"source_ignore": {
"patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"],
"files": [".helmignore"]
}
}
  • patterns son reglas que se leen desde la raíz del directorio de la fuente y se aplican en orden, de modo que una coincidencia posterior prevalece sobre una anterior.
  • files nombra los archivos de exclusión que tu ecosistema respeta dentro de una fuente. Dondequiera que el recorrido de una fuente encuentre uno, sus líneas se leen como reglas adicionales para el directorio que lo contiene, después de tus patrones.

La declaración se lee cuando se fija una entidad, no cuando se renderiza. El paso de fijación del autor resuelve, en su espacio de trabajo, el plugin que sirve la capacidad de la entidad, compone tus reglas con su propio .aggregaignore — cuyas líneas van al final y por eso prevalecen en cualquier ruta que nombren — y registra el nombre de tu plugin, sin versión, junto con las reglas compuestas exactas, en el entity.lock de la entidad. Cada publicación, comparación y renderizado posteriores de esa entidad aplican las reglas registradas; el host las hace coincidir y no tiene ninguna opinión propia sobre ningún ecosistema. Así, los archivos que recibe tu guest en el renderizado — el listado, y cada archivo que pide al host que empaquete o lea — son exactamente los archivos que lleva una publicación de la entidad, y a un archivo que las reglas dejan fuera se le responde que no existe, nombrándolo. Un enlace simbólico dentro de una fuente se rechaza antes de que se invoque tu guest.

La compatibilidad se deriva de lo que se registró. Un guest puede renderizar una Recipe publicada para su capacidad cuando habla la misma versión de la ABI, su contrato coincide con la declaración de su entidad y no necesita ningún archivo fuera del conjunto publicado. Un guest que necesita un archivo que el conjunto dejó fuera debe hacer fallar su compilación de forma visible y nombrar el archivo — el rechazo por parte del host de un empaquetado o de una lectura lo nombra, y un guest lo traslada a su propio fallo. Cuando el plugin que el espacio de trabajo de un consumidor enlaza a una capacidad declara reglas distintas de las que registra el archivo de bloqueo de una entidad, el pull del consumidor imprime una advertencia que nombra ambos plugins y la diferencia; nunca se detiene por ello.

Omitir source_ignore no declara ninguna regla, y una fuente que renderizas conserva entonces cada archivo que conservan las reglas propias del autor. El campo es opcional y no necesita una versión de ABI propia: un guest que lo omite se carga como uno que no declara nada. La entidad Plugin registra la misma declaración como spec.provider.contract.sourceIgnore; cuando lo hace, la carga rechaza un guest cuyo describe() informa de algo distinto.

Determinismo y reutilización de instancias

El host consume los bytes de salida de un guest tal cual, así que un guest debe producir una salida idéntica a partir de una entrada idéntica. De forma predeterminada, un guest se carga de nuevo para cada nodo — ningún estado se traslada de un nodo a otro, por construcción. Un guest que declara por sí mismo reusable_instance se carga en cambio una sola vez por compilación y su única instancia sirve cada cruce, lo que recupera el costo de instanciación por nodo, que es el dominante. Como la reutilización solo es segura para un guest sin estado, aggrega build --verify-determinism renderiza cada nodo dos veces a través de la misma instancia y detiene la compilación si los dos renderizados de cualquier nodo difieren; la compilación predeterminada renderiza una vez y confía en la declaración. La caché de compilación de Wasm reside en disco y es común a todo el proceso, así que un guest se compila una vez y las compilaciones en caliente omiten la recompilación.

El socket de linter — el linter de publicación

El socket de linter se distribuye como el publishing-linter estándar, un punto de control fuera de banda que se ejecuta mediante aggrega lint en lugar de en tiempo de compilación. Consume una entidad del catálogo (y, en modo --pre-publish, la versión actualmente publicada de la entidad) y devuelve una lista de hallazgos, cada uno con una severidad y un mensaje; en modo --pre-publish también devuelve una clasificación del incremento de versión. El host lo despacha a través del runtime de Wasm integrado, detrás del mismo cortafuegos de pureza AOT que cualquier otro socket. El conjunto completo de reglas, las severidades y las exclusiones por regla están documentados en cli/aggrega-lint.md.

El linter es una disciplina de catálogo de adopción voluntaria: el compilador no lo ejecuta durante aggrega build (con la única excepción del aviso que desaconseja x-aggrega-*, que aparece con severidad warn durante la compilación y con severidad halt con aggrega lint --pre-publish). Como las reglas residen en un plugin, una empresa puede dirigir aggrega lint a otro plugin de linter para hacer cumplir su propia disciplina.

Ningún valor de parámetro llega a un plugin de linter, en ningún ámbito en el que se ejecute aggrega lint. Antes de entregar cualquier documento, el host retiene los valores predeterminados de los parámetros de un Aggregate, los valores que pasa a cada módulo que importa y los parámetros de una Release, y conserva el contrato de cada declaración de parámetro — solo las claves con las que está escrita una declaración, en cada nivel de anidamiento — y cualquier texto de plantilla que lee un parámetro: el valor de un parámetro puede ser en sí mismo una credencial, y el plugin vinculado aquí puede ser código que el espacio de trabajo no escribió. Lo que lleva cada documento se expone en Qué recibe un plugin de linter.

Codificación de transmisión. La entrada y la salida viajan ambas como CBOR canónico (RFC 8949 §4.2.1). Un guest decodifica su entrada y codifica su salida a través de los puntos de entrada que ya llevan LinterInput y LinterOutput de su kit — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, decodeCBORLinterInput y encodeCBORLinterOutput en TypeScript — leyendo y escribiendo bytes (Vec<u8> en Rust, Host.inputBytes() y Host.outputBytes(...) en TypeScript). No se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. Los documentos de entidad — proposed, previous, implemented_component y release — y cada valor de components viajan como los bytes de sus documentos JSON, así que un guest los analiza como JSON para examinar su contenido. components es un mapa que el esquema marca como mapa que preserva el orden, así que en la entrada de una regla que lee una Release entera viaja como una lista ordenada de entradas en el orden en que el Aggregate declara sus instancias de componente, y un guest la lee a través del contenedor de su kit que mantiene el orden. policies viaja como un mapa que contiene solo los indicadores establecidos, así que un indicador que no contiene se lee como falso, y cada hallazgo viaja en la forma compartida Diagnostic. Una respuesta que no es un LinterOutput en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — hace fallar el lint, nombrando el export al que llamó, en lugar de leerse como una ejecución que no encontró nada. Llamado directamente con aggrega plugin run-local --export lint_rules, un linter recibe la carga útil JSON escrita por el autor convertida a esta codificación, y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Estado actual: disponible. El publishing-linter se distribuye y se ejecuta a través del host mediante aggrega lint.

El socket de analizador — salida de árbol canónico

Un analizador convierte una fuente escrita en un formato que el compilador no lee de forma nativa en un árbol estructurado canónico, así que un consumidor lee el árbol en lugar de llevar un analizador propio. El host resuelve el analizador que anuncia el formato solicitado como parse:<format> y llama a su export parse en tres lugares: cuando a una política del rol render-verdict se le entrega un artefacto renderizado en un formato que no lee de forma nativa, cuando un importador pide al host un árbol a través de aggrega_parse_source, y cuando se reconoce una importación que no nombra ningún formato (consulta el socket importador más abajo). Un guest nunca llama a un analizador por sí mismo.

Forma de entrada (host → guest). Un documento ParseInput que contiene:

  • format — el formato solicitado, una de las capacidades parse:<format> del analizador sin su prefijo.
  • bytes — los bytes de la fuente.
  • options — un documento de opciones que el consumidor proporciona para un comportamiento específico del analizador, entregado tal cual. Ausente cuando el consumidor no proporciona ninguno.

Forma de salida (guest → host). Un documento ParseOutput que contiene el tree — la fuente analizada como documento JSON, cuyo nivel superior puede ser un objeto, un array o un escalar — los diagnósticos que haya en la forma compartida Diagnostic, rangos de fuente opcionales que ubican los nodos del árbol en los bytes originales, y un fallo en error cuando el análisis no pudo completarse. Cada campo y sus restricciones están en la referencia del esquema del socket de analizador generada.

Codificación de transmisión. La entrada y la salida viajan ambas como CBOR canónico (RFC 8949 §4.2.1), la codificación en la que viaja el mismo ParseInput cuando un guest lo entrega a aggrega_parse_source. Un guest decodifica su entrada y codifica su salida a través de los puntos de entrada que ya llevan ParseInput y ParseOutput de su kit — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, decodeCBORParseInput y encodeCBORParseOutput en TypeScript — leyendo y escribiendo bytes (Vec<u8> en Rust, Host.inputBytes() y Host.outputBytes(...) en TypeScript). No se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. Los bytes de la fuente viajan como una secuencia de bytes en bruto, y el decodificador generado los vuelca en el tipo de campo propio del kit: un slice de bytes en Go, una cadena base64 en Rust y TypeScript. options y tree viajan como los bytes de sus documentos JSON, así que el árbol que escribe un analizador llega a su consumidor tal cual. Un analizador que no puede completar indica por qué en el error de la salida, y el análisis falla nombrando el analizador y ese mensaje; una respuesta que no es un ParseOutput en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — también hace fallar el análisis, nombrando el analizador y su export parse. Un análisis fallido detiene una compilación en el rol render-verdict, y llega a un importador como el fallo con el que responde aggrega_parse_source. Lo mismo ocurre con una fuente que el analizador rechaza — una a la que responde con un diagnóstico halt junto a su árbol: la llamada del importador falla con el mensaje de cada uno de esos diagnósticos, en el orden del analizador, y nunca recibe el árbol. Llamado directamente con aggrega plugin run-local --export parse, un analizador recibe la carga útil JSON escrita por el autor convertida a esta codificación — la fuente escrita en esa carga útil como base64, igual que JSON escribe cualquier campo de bytes — y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Definiciones de tipos. Los tipos de transmisión del analizador — ParseInput, ParseOutput, NodeSpan y SourceSpan — se publican en los tres paquetes ABI y los reexporta el kit de desarrollo de plugins de cada lenguaje, generados a partir de un único códec para que los tres sigan sincronizados. El ejemplo parse de cada kit lee su entrada y escribe su salida de esta manera, y lo mismo hacen los analizadores para HCL, TOML, YAML, JSON y JSON con comentarios que se distribuyen dentro del binario.

Estado actual: disponible — despachado en el rol render-verdict para un artefacto en un formato que la política no lee de forma nativa, a través de aggrega_parse_source para un importador, y para reconocer el formato de una importación que no nombra ninguno.

El socket de importador — salida de borradores de autoría

Un importador convierte una fuente escrita para otra herramienta — un flujo exportado desde un constructor de agentes, por ejemplo — en archivos de autoría de Aggrega en borrador. Se ejecuta fuera de banda: aggrega import, el método aggrega/import de la sesión del editor y la herramienta import orientada al asistente resuelven el importador que anuncia el formato solicitado como import:<format> y llaman a su export import una vez por importación. Una compilación nunca lo despacha. Qué importador se ejecuta, y qué le entrega un operador, se describe en Qué importador convierte una fuente en borradores. Los importadores propios del compilador, uno para cada formato que lee, se describen en Importadores core: qué formatos son, qué lee cada uno, qué genera como borrador, los ajustes que admite, su publicación con cada versión del compilador y cómo una importación descarga y verifica uno que la máquina aún no contiene.

Forma de entrada (host → guest). Un documento ImportInput que contiene:

  • format — el formato que solicitó la importación, una de las capacidades import:<format> del importador sin su prefijo.
  • bytes — los bytes de la fuente: el archivo completo para una importación de un archivo, y vacío para una importación de un directorio, cuyos archivos llegan bajo sources.
  • name — el nombre de la fuente, sin ningún directorio delante, para que el importador pueda nombrar la fuente en lo que informa y en lo que genera como borrador: para una importación de un archivo, el nombre base del archivo del que se leyó bytes; para una importación de un directorio, el nombre base del propio directorio, leído de su ruta completa, de modo que aggrega import . entrega el nombre del directorio en el que se ejecuta, mientras que los archivos del directorio siguen llegando cada uno con su propio nombre. Ausente donde la fuente no tiene ningún nombre que dar.
  • sources — las fuentes con nombre, cada una con su nombre y sus bytes, en una única lista ordenada por nombre: para una importación de un directorio, cada archivo suyo que seleccionan los patrones de archivo declarados del importador, excluida la carpeta de salida de compilación del espacio de trabajo, nombrado por su ruta separada por barras dentro del directorio; y los archivos que la entrada plugins.importer que vincula este importador declara bajo with.sources, cada uno con su nombre base. Un archivo del directorio y un archivo de with.sources con el mismo nombre hacen que la importación se rechace, en lugar de que uno oculte al otro. Ausente donde no hay ninguna.
  • settings — el objeto de ajustes que esa entrada declara bajo with.settings, como documento JSON con sus claves ordenadas, entregado tal cual. Ausente cuando ninguna entrada vincula el importador o la entrada no declara ninguno.
  • catalog — una vista de los Components que contiene el catálogo propio del espacio de trabajo: el catálogo del que se seleccionó el propio importador — las carpetas de catálogo del espacio de trabajo o, donde no nombra ninguna, la instantánea del catálogo que publica su registro predeterminado, guardada en esta máquina —, sin descargar nada para la propia vista. Su lista components contiene una entrada por nombre de Component, ordenada por nombre; donde el catálogo contiene varias versiones de un Component, la entrada describe la versión a la que se resuelve una referencia que lo nombra sin versión. Cada entrada lleva el name y la version del Component, sus labels, los nombres de las claves de nivel superior que declaran sus values y provides (values y provides, cada uno ordenado), y sus sockets — cada uno con el name del socket y el selector de etiquetas que debe satisfacer una dependencia conectada a través de él — en el orden en que el Component los declara. Un Component que extiende otro lleva lo que hereda además de lo que declara, y los sockets que hereda van primero. La vista contiene solo nombres, versiones, etiquetas y selectores — nunca un valor, un valor predeterminado ni un secreto — y su orden es fijo, así que un catálogo produce una única secuencia de bytes. Ausente cuando el catálogo no contiene ningún Component.

Forma de salida (guest → host). Un documento ImportOutput que contiene las entidades que produjo la importación — cada una una referencia a una entidad de catálogo existente o un cuerpo generado como borrador — las decisiones de mapeo que hay detrás de ellas, los diagnósticos que haya en la forma compartida Diagnostic, los archivos de andamiaje que se deben escribir, y un fallo en error cuando la importación no pudo completarse. Cada campo y sus restricciones están en la referencia del esquema del socket de importador generada.

Codificación de transmisión. La entrada y la salida viajan ambas como CBOR canónico (RFC 8949 §4.2.1). Un guest decodifica su entrada y codifica su salida a través de los puntos de entrada que ya llevan ImportInput y ImportOutput de su kit — DecodeCBOR y EncodeCBOR en Go, decode_cbor y encode_cbor en Rust, decodeCBORImportInput y encodeCBORImportOutput en TypeScript — leyendo y escribiendo bytes (Vec<u8> en Rust, Host.inputBytes() y Host.outputBytes(...) en TypeScript). No se necesita ninguna biblioteca CBOR y nada analiza bytes a mano. settings viaja dentro del documento binario como los bytes de su documento JSON, así que un guest lo analiza como JSON para examinar su contenido, como en cualquier otro socket. Un importador que no puede completar indica por qué en el error de la salida, y la importación se detiene nombrando el importador y ese mensaje; una respuesta que no es un ImportOutput en esta codificación — una escrita como JSON, o una que lleva un campo de nivel superior que la forma no declara — también detiene la importación, nombrando el importador y su export import. Llamado directamente con aggrega plugin run-local --export import, un importador recibe la carga útil JSON escrita por el autor convertida a esta codificación, y su respuesta se lee como la forma de salida del export y se imprime como JSON — una respuesta que no tiene esa forma se rechaza, nombrando el export, igual que la rechaza una compilación.

Cómo se reconoce una fuente de tu formato. Una importación puede no nombrar ningún formato, y el host reconoce entonces uno a partir de lo que declaran los importadores, sin conocer por sí mismo ningún formato. Un importador declara en su autoinforme describe(), bajo importer (un ImporterContract), una lista detect de las firmas por las que se reconoce una fuente de sus formatos. Cada DetectSignature nombra:

  • syntax — el formato sintáctico con el que se analiza la fuente, un formato que un plugin de analizador anuncia como parse:<syntax>, como json o yaml;
  • files — patrones opcionales de nombre de archivo que se comparan con el final del nombre de la fuente: un segmento con el propio nombre del archivo, varios segmentos separados por barras con otros tantos segmentos finales de su ruta, y *, ? y [...] coinciden dentro de un segmento. Una firma que no declara ninguno se aplica a una fuente que es un solo archivo, se llame como se llame, y a ningún archivo de un directorio;
  • match — los predicados que el árbol analizado debe satisfacer todos, cada uno un PathMatch con un path de claves unidas por puntos desde la cima del árbol (un segmento de número entero selecciona una posición de array), un is entre present, absent, object, array, string, number o boolean, y opcionalmente una cadena equals o una cadena prefix — como mucho una de las dos.

Cuando una importación no nombra ningún formato, el host compara las firmas de cada importador entre los que elige la importación — los del catálogo del espacio de trabajo y los importadores core del compilador — en el orden de su identidad y versión: analiza la fuente mediante el analizador que el catálogo sirve para una sintaxis — o, para una sintaxis para la que el catálogo no sirve ningún analizador, el que incluye el propio compilador — como mucho una vez por sintaxis, evalúa los predicados sobre el árbol y lee la fuente como el formato del único importador cuya firma coincide. Ese es también el analizador mediante el que se responde a la llamada aggrega_parse_source de un importador, así que un importador lee su fuente mediante el analizador con el que se reconoció. Una fuente que no se analiza en una sintaxis no coincide con ninguna firma que la nombre; una sintaxis para la que ni el catálogo ni el compilador sirven un analizador detiene el reconocimiento, nombrando la ausencia del analizador. Una fuente con la que no coincide ninguna firma se rechaza pidiendo el formato, y una reconocida como más de un formato se rechaza nombrándolos. Una firma reconoce una fuente como cada formato que anuncia su importador, así que un importador cuyas fuentes deban reconocerse sirve un solo formato, y uno que no declara ninguna firma solo se alcanza nombrando su formato.

La entidad Plugin del importador registra la misma lista como spec.importer.detect, derivada de describe() cuando la entidad se genera a partir del guest; el reconocimiento lee ese registro, así que el guest no se carga hasta que su formato está decidido. Cargar y publicar el guest rechazan uno cuyo autoinforme difiere del registro de su entidad, nombrando importer.detect, y una entidad que no registra ninguna no declara nada. El descriptor se rechaza al cargar donde el contrato se declara en un plugin que no es un importador, donde una firma no nombra ninguna sintaxis o nombra un patrón de archivo mal formado, y donde un predicado no nombra ninguna ruta, nombra un is fuera de los siete, o nombra a la vez equals y prefix.

Los importadores core del compilador y el ejemplo import del kit de Go declaran las suyas de esta manera. El importador Langflow lee una fuente como JSON y pide un array en data.nodes; el importador Flowise pide arrays en nodes y edges y nada en data.nodes; el importador n8n pide un array en nodes, un objeto en connections y nada en edges ni en data.nodes; el importador MCP declara una firma por cada configuración de cliente, que nombra su archivo — .mcp.json, claude_desktop_config.json y .cursor/mcp.json, leídos como JSON con un objeto en mcpServers, y .vscode/mcp.json, leído como JSON con comentarios, como lo lee Visual Studio Code, con un objeto en servers — y una que no nombra ningún archivo y pide una cadena $schema que empiece por https://static.modelcontextprotocol.io/schemas/; el importador Compose lee una fuente como YAML, nombra los archivos que Compose lee de forma predeterminada — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml y sus cuatro archivos de sobrescritura — y pide un objeto en services; el importador Dify lee una fuente como YAML, no nombra ningún archivo y pide la cadena app en kind y algo en app.mode y en version; el importador CrewAI nombra config/agents.yaml y config/tasks.yaml, leídos como YAML sin pedir nada al árbol, crew.jsonc y crew.json, leídos como JSON con comentarios con una lista en agents, y agents/*.jsonc y agents/*.json, leídos como JSON con comentarios con algo en role, de modo que no hay dos de ellos que coincidan con una misma fuente, y un archivo importado por sí solo sin nombrar ningún formato se lee como YAML además de como JSON; el importador LangGraph nombra langgraph.json, leído como JSON con un objeto en graphs, declara una firma que no nombra ningún archivo y pide un objeto en graphs y la cadena https://langgra.ph/schema.json en $schema, y no nombra ningún archivo de entorno, ya que el reconocimiento lee todo archivo que seleccionan los patrones de cualquier importador, así que un patrón que nombrara uno abriría los archivos de entorno de cada directorio importado sin nombrar ningún formato; el importador Google ADK nombra root_agent.yaml, leído como YAML con algo en name y en instruction, o una cadena en agent_class y algo en name, y no nombra ningún otro archivo, ya que la configuración de un subagente puede llamarse de cualquier forma y un patrón que nombrara todo archivo YAML abriría cada uno de ellos en cada directorio importado sin nombrar ningún formato; el importador Agent Framework lee una fuente como YAML, no nombra ningún archivo y pide la cadena Prompt en kind y un objeto en model; el ejemplo import del kit de Go lee una fuente como YAML y pide la cadena DemoSource en kind. En Go:

Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{
Syntax: "json",
Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},
}}},

Qué lee una importación de un directorio. Una fuente puede ser un directorio, y los patrones de archivo declarados del importador deciden qué lee: el host lee exactamente los archivos del directorio, a cualquier profundidad, que selecciona uno de los patrones files de las firmas del importador — cada uno comparado con el final de la ruta separada por barras del archivo dentro del directorio — y los entrega como sources en orden de nombre, con bytes vacío y el nombre del propio directorio como name. No se abre ningún otro archivo del directorio. La carpeta en la que una compilación del espacio de trabajo escribe sus archivos renderizados — dist/ bajo la raíz del espacio de trabajo — no se lee como parte de un directorio que la contiene: ninguno de sus archivos se entrega ni se reconoce, y un enlace que lleva a ella se omite, así que un directorio que se ha compilado se lee como el proyecto que contiene, mientras que un directorio que es esa carpeta, o está dentro de ella, se lee tal como se nombra. Una firma que no declara ningún patrón files no selecciona ningún archivo de un directorio, así que un importador que no declara ninguno lee un solo archivo y rechaza un directorio, y un directorio que no contiene ningún archivo que seleccionen sus patrones también se rechaza. El directorio queda confinado a sí mismo: un enlace entre los archivos que el host leería, o a un directorio, que lleva fuera del directorio se rechaza antes de leer nada, en un enlace a un directorio nunca se entra, y un enlace a un archivo que ningún patrón selecciona se omite sin leerlo. Reconocer el formato de un directorio sigue la misma regla — cada firma se prueba con los archivos que seleccionan sus patrones, en orden de nombre, cada archivo leído y analizado como mucho una vez por sintaxis, y una firma que no declara ningún patrón no se aplica a ninguno de ellos. El host no limita nada: un directorio demasiado grande para el importador lo rechazan los límites de ejecución propios del importador. Ninguno de los importadores Langflow, Flowise, n8n, Dify y Agent Framework del compilador declara patrones files, así que cada uno lee un solo archivo; su importador MCP declara los nombres de las cuatro configuraciones de cliente, así que lee cada una de ellas que contenga un directorio; su importador Compose declara los ocho nombres de archivo de Compose, así que recibe cada archivo Compose que contiene un directorio y combina los que leería Compose; y su importador CrewAI declara los seis nombres con los que se escriben las declaraciones de un proyecto CrewAI, así que recibe las declaraciones de un proyecto y nada de su programa; y su importador LangGraph declara langgraph.json, así que recibe la configuración de una aplicación y nada de su código ni de sus archivos de entorno, y un archivo de entorno le llega solo bajo el with.sources de su vinculación; y su importador Google ADK declara root_agent.yaml, así que recibe la configuración del agente raíz de una aplicación y nada de su código ni de su archivo de entorno, y las configuraciones que nombran sus subagentes le llegan solo bajo el with.sources de su vinculación.

Definiciones de tipos. Los tipos de transmisión del importador — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput y las formas de entidad, decisión y andamiaje que lleva — se publican en los tres paquetes ABI y los reexporta el kit de desarrollo de plugins de cada lenguaje, generados a partir de un único códec para que los tres sigan sincronizados, y lo mismo ocurre con los tipos de reconocimiento ImporterContract, DetectSignature y PathMatch que lleva el autoinforme describe. El paquete importer del kit de Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, lleva todo lo que hace un importador sea cual sea su formato, y los importadores core del compilador, todos ellos construidos sobre él, leen su entrada y escriben su salida de esta manera.

Frente a qué puntúa un importador construido sobre el kit de Go. El puntuador del kit pondera cada nodo de la fuente frente a los Components de la vista catalog y frente a nada más: los candidatos son el catálogo propio del espacio de trabajo — los Components de un catálogo empresarial exactamente igual que los de la biblioteca estándar — y el kit no lleva ningún candidato propio. De cada Component lee el nombre, la categoría que lleva su etiqueta component.aggrega.ai/category, sus etiquetas y los nombres de las claves que declaran sus values; sus claves provides y sus sockets no se ponderan. Un Component añadido al catálogo es un candidato en la siguiente importación, sin recompilar ningún importador. Donde la vista está ausente, porque el catálogo no contiene ningún Component, ningún nodo tiene candidato: ninguno se referencia ni se sugiere, y cada nodo al que el borrador da un Component propio se genera como borrador. Todo importador que puntúa mediante el kit puntúa de esta manera — entre ellos los importadores Langflow, Flowise, n8n y Compose del compilador, mientras que su importador MCP no pondera ningún candidato; un importador que no usa el kit lee la vista como prefiera.

Para qué lee un importador construido sobre el kit de Go los sockets de una plataforma. Los sockets no pesan nada en una puntuación, pero el kit los lee para disponer un borrador. Un formato cuyos flujos una plataforma ejecuta tal como están escritos — como hacen los de Langflow, Flowise y n8n — se genera como borrador de forma predeterminada como una instancia del Component de esa plataforma que lleva el flujo, y cada parte del flujo se conecta al primer socket, en el orden en que la entrada catalog de la plataforma enumera sus sockets, cuyo selector satisfacen las etiquetas del Component de la parte, tal como la vista lleva esas etiquetas. Solo se leen el selector y las etiquetas, y el selector se compara mediante una función que proporciona el importador, ya que el kit no lleva ninguna gramática de selectores propia; donde la vista no contiene ningún Component con el nombre de la plataforma, no se conecta ninguna parte. Importadores core describe el borrador que hacen de esta manera los importadores Langflow, Flowise y n8n del compilador, y el ajuste layout que, en cambio, genera cada nodo como borrador como un Component propio.

Estado actual: disponible — despachado por aggrega import y por la misma operación en la sesión del editor y en la herramienta orientada al asistente.

Criterio de ubicación: el socket de linter frente a los roles de veredicto de gobernanza

Dos de los sockets documentados comparten una superficie similar — ambos emiten resultados por regla — pero difieren en su ubicación en el pipeline y en su semántica de bloqueo. El criterio para decidir qué socket lleva una comprobación dada:

  • Los roles de veredicto de gobernanza (en banda, que detienen la compilación). Reservados para políticas que detienen la compilación: un veredicto halt detiene el pipeline de compilación y la compilación no produce artefactos. Los casos de uso son políticas cuya violación hace que la salida no sea segura de aplicar: puntos de control de cumplimiento (ubicación de los límites PCI / SOC2), invariantes de topología (ingress zero-trust, autenticación entre límites), forma del flujo de credenciales (ningún secreto en texto plano en la IR), etc. Una política razona sobre el grafo IR (ir-verdict, antes del renderizado) o sobre los artefactos renderizados (render-verdict, después del renderizado).
  • El socket de linter (fuera de banda, CI / IDE, consultivo). Reservado para comprobaciones de buenas prácticas y de descubribilidad: reglas cuya violación es sospechosa pero no peligrosa — secretos huérfanos, parámetros sin usar, vocabulario de etiquetas obsoleto, completitud de los tags para la atribución de costos, desviación de las convenciones de nomenclatura. Un fallo produce una salida consultiva; la compilación sigue produciendo artefactos.

El criterio de ubicación formulado como una sola regla: si la comprobación debe detener la compilación, corresponde a un rol de veredicto de gobernanza; si la comprobación debe advertir a un autor o a un revisor sin bloquear el pipeline, corresponde al socket de linter.

Ambos se pueden usar hoy. El socket de linter ejecuta el publishing-linter mediante aggrega lint; los roles de veredicto de gobernanza se invocan en banda durante aggrega build cuando un espacio de trabajo vincula un plugin con rol de veredicto. Ten en cuenta que un rol de veredicto tiene sus propias severidades — una política puede emitir ella misma veredictos warn e info que advierten sin detener — así que la línea entre detener y advertir trazada arriba es la orientación de ubicación para comprobaciones completas, no una afirmación de que una política solo pueda detener. Consulta la página del socket de gobernanza para el modelo de severidad.

Referencias cruzadas

  • policy-socket.md — el tratamiento completo del socket de gobernanza: los cuatro roles, las severidades de los veredictos, el canal de entrada del operador, cómo escribir una política para cualquiera de los dos motores que se incluyen en el compilador, cómo envolver un motor de políticas externo y los guests de referencia.
  • core-importers.md — los importadores propios del compilador, uno para cada formato que lee: qué lee cada uno, su configuración y su publicación con cada versión del compilador.
  • 10-status.md#compilation-pipeline-phases — clasificación del pipeline de plugins en la página de estado (preparación en tiempo de ejecución del pipeline de plugins Wasm).
  • architecture/04-entity-taxonomy.md §«Domain 3: Infrastructure Base (Dominio 3: base de infraestructura)» — principio del Plugin en dos partes para las FeatureRecipes de credenciales (patrón Fetcher + Injector).
  • architecture/13-catalog-and-registry.md — la taxonomía OCI que comienza con el segmento del proveedor.
  • entities/featurerecipe.md — la superficie de creación pipeline: de la FeatureRecipe.
  • when-to-use-a-pipeline-step.md — guía de decisión: un paso de pipeline frente a una FeatureRecipe con plantillas.
  • templates/expansion-matrix.md — las reglas de evaluación de plantillas del bloque pipeline: with: del pipeline de plugins y la semántica de acceso a .steps.
  • examples/04-secrets.md — la forma de pipeline Fetcher + Injector que puede adoptar una FeatureRecipe de credenciales.
  • errors/error-translation.md — la disciplina de traducción de errores en la que participan los guests de los plugins.