Esquema del socket Wasm de importador de Aggrega
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/wasm-import-v1beta1.schema.json
Las formas de transmisión que consume (ImportInput) y emite (ImportOutput) un socket de plugin de importador. Un importador convierte una descripción de infraestructura externa en entidades de Aggrega: lee los bytes de la fuente para un formato nombrado, asigna cada nodo de la fuente a una entidad del catálogo y devuelve las entidades que emitió, las decisiones de asignación que tomó, los diagnósticos que generó y los archivos de scaffold que produjo. Un importador declara los formatos que maneja como capacidades import:
Una de las siguientes formas
ImportInputImportOutput
Definiciones
ImportInput
El payload que recibe un guest importador: el formato de origen que selecciona cómo leer los bytes, los bytes de la fuente principal y el nombre del archivo del que se leyeron, las fuentes nombradas para una importación de varios archivos, un documento de opciones opaco opcional que el consumidor proporciona para un comportamiento específico del importador, una vista de los Components que contiene el catálogo del espacio de trabajo, y el destino para el que la importación redacta borradores.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
format | string | sí | El nombre del formato de origen que se va a importar, que coincide con una de las capacidades import: |
bytes | string | sí | Los bytes de la fuente principal que se van a importar, que el importador lee en el formato nombrado: el archivo completo donde la fuente de la importación es un archivo, y vacío donde es un directorio, cuyos archivos llegan en su lugar como fuentes nombradas. Cada kit los lleva en su propio tipo de campo — en bruto donde ese tipo es un tipo de bytes, codificados en base64 donde es una cadena que el importador decodifica para recuperarlos — y el codificador generado convierte entre el campo y la forma en que el formato de transmisión lleva los bytes. |
name | string | no | El nombre de la fuente de la importación, sin ningún directorio delante, para que un importador pueda nombrar la fuente en lo que informa y en lo que genera como borrador. Donde la fuente es un solo archivo, es el nombre base del archivo: los bytes principales no llegan como ninguna fuente nombrada, por lo que este es el único nombre que llevan. Donde la fuente es un directorio, es el nombre base del directorio, y los archivos del directorio siguen llegando como fuentes nombradas, cada uno con su propio nombre, con los bytes principales vacíos. Ausente donde la fuente no tiene ningún nombre que dar. |
sources | ImportSource[] | no | Fuentes nombradas, cada una con sus propios bytes, en una única lista ordenada por nombre. Donde la fuente de la importación es un directorio, hay una por cada archivo de este que seleccionan los patrones de archivo declarados por el importador, nombrada por su ruta separada por barras dentro del directorio. Los archivos que la vinculación que configura el importador declara bajo with.sources también se llevan aquí, cada uno con su nombre base, y el host rechaza una importación en la que un archivo leído del directorio y uno de estos llevan el mismo nombre. Ausente donde ninguno de los dos proporciona ninguna. |
settings | any | no | Un documento opaco de opciones de importación que el consumidor proporciona para un comportamiento específico del importador. El host lo transmite sin interpretarlo; el importador lee la forma que documente, sea cual sea. Ausente cuando el consumidor no proporciona opciones. |
catalog | CatalogProjection | no | 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 — para que el importador pueda sopesarlos como candidatos cuando asigna un nodo de la fuente a una entidad del catálogo. El host la construye solo a partir de ese catálogo local, y lleva únicamente nombres, versiones, etiquetas y estructura declarada: nunca un valor, un valor predeterminado ni un secreto. Su orden es fijo, de modo que un catálogo produce una única secuencia de bytes. Ausente cuando el catálogo no contiene ningún Component. |
target | string | no | La capacidad de proveedor para la que la importación redacta borradores, como compose o helm: el destino que se dio a la importación o, para una importación que actualiza una anterior y no nombra ninguno, el destino que registró esa importación anterior. Un importador escribe en los borradores, como declaraciones, lo que solo necesita ese destino, y omite lo que solo necesita otro destino. El host lo transmite tal como se proporciona, una vez que ha comprobado que una Recipe del catálogo del espacio de trabajo se vincula a él. Ausente cuando la importación no nombra ningún destino. |
No se permiten propiedades adicionales.
CatalogProjection
El catálogo del espacio de trabajo tal como lo ve un importador: una entrada por cada Component que contiene el catálogo, cada una con los metadatos que un importador sopesa cuando puntúa un candidato.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
components | CatalogComponent[] | sí | Una entrada por cada nombre de Component que contiene el catálogo, ordenada por nombre. Donde el catálogo contiene varias versiones de un Component, su entrada describe la versión a la que se resuelve una referencia que nombra el Component sin versión. |
No se permiten propiedades adicionales.
CatalogComponent
Un Component del catálogo del espacio de trabajo: su nombre y su versión, sus etiquetas, los nombres de clave que declaran sus values y provides, y los sockets que declara para sus dependencias. Un Component que extiende otro lleva lo que hereda además de lo que declara él mismo.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | El nombre del Component, tal como lo declara su metadata.name — el nombre con el que un Aggregate hace referencia a él. |
version | string | sí | La versión del Component, tal como la declara su metadata.version. |
labels | mapa de string | no | Las etiquetas del Component, como un mapa de cadena a cadena. Ausente cuando no lleva ninguna. |
values | string[] | no | Los nombres de clave de primer nivel que declaran los values del Component, ordenados. Solo una lista de nombres: nunca lleva un valor ni un valor predeterminado. Ausente cuando sus values no declaran ninguna clave. |
provides | string[] | no | Los nombres de clave de primer nivel que declaran los provides del Component, ordenados. Solo una lista de nombres: nunca lleva un valor. Ausente cuando sus provides no declaran ninguna clave. |
sockets | CatalogSocket[] | no | Los sockets que el Component declara para sus dependencias, en orden de declaración: para un Component que extiende otro, primero vienen los sockets que hereda, en el orden en que los declara el Component extendido, seguidos de los que añade. Ausente cuando no declara ninguno. |
No se permiten propiedades adicionales.
CatalogSocket
Un socket que un Component del catálogo declara para sus dependencias: el nombre del socket y el selector de etiquetas que debe satisfacer una dependencia cableada a través de él.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | El nombre del socket, tal como lo declara el usesSchema del Component. |
selector | string | sí | El selector de etiquetas del socket, textualmente, en la gramática de estilo Kubernetes en la que lo escribe el Component: las etiquetas que debe llevar una dependencia cableada a través de este socket. |
No se permiten propiedades adicionales.
ImportSource
Una fuente nombrada dentro de una importación de varios archivos o de un directorio: un nombre que ubica la fuente y sus propios bytes.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | El nombre de esta fuente dentro de la importación, como una ruta de archivo relativa. |
bytes | string | sí | Los bytes de esta fuente. Cada kit los lleva en su propio tipo de campo — en bruto donde ese tipo es un tipo de bytes, codificados en base64 donde es una cadena que el importador decodifica para recuperarlos — y el codificador generado convierte entre el campo y la forma en que el formato de transmisión lleva los bytes. |
No se permiten propiedades adicionales.
ImportOutput
El payload que devuelve un guest importador: las entidades que produjo la importación, las decisiones de asignación que hay detrás de ellas, los diagnósticos que generó la importación y los archivos de scaffold que produjo. Todos los campos son opcionales, de modo que una importación que no resolvió nada puede devolver solo diagnósticos.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
entities | EmittedEntity[] | no | Las entidades que produjo la importación, cada una una referencia a una entidad existente del catálogo o un cuerpo de entidad redactado. Ausente cuando la importación no emitió entidades. |
decisions | ImportDecision[] | no | Las decisiones de asignación que tomó la importación, una por cada nodo de la fuente que resolvió, que registran los candidatos que sopesó y la elección que hizo. Ausente cuando la importación no registró decisiones. |
diagnostics | Diagnostic[] | no | Diagnósticos que generó la importación — por ejemplo, un nodo de la fuente sin resolver o una asignación ambigua. Ausente cuando la importación no produjo ninguno. |
files | ScaffoldFile[] | no | Archivos de scaffold que produjo la importación junto a las entidades, como un agregado inicial o un readme. Ausente cuando la importación no produjo archivos. |
error | string | no | Un mensaje de error que se establece cuando el guest se ejecutó pero no pudo completar la operación; ausente en caso de éxito. Es distinto de cualquier diagnóstico que lleve la salida: los diagnósticos informan de problemas encontrados durante una ejecución que aun así produjo un resultado, mientras que error informa de que la propia operación no se completó. El host presenta un error presente como una invocación de plugin fallida. |
No se permiten propiedades adicionales.
EmittedEntity
Una entidad que produjo la importación: su tipo, su nombre y cómo se emite — una referencia a una entidad existente del catálogo o un cuerpo de entidad recién redactado.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
kind | string | sí | El tipo de entidad emitida. Los importadores del núcleo emiten Component, Aggregate y Release; un lector tolera cualquier otro tipo. |
name | string | sí | El nombre de la entidad emitida. |
mode | string (enum) | sí | Cómo se emite la entidad: reference apunta a una entidad existente del catálogo por su nombre, y draft lleva un cuerpo de entidad recién redactado. Valores permitidos: "reference", "draft" |
body | string | no | El cuerpo YAML en bruto de una entidad redactada. Vacío para una referencia pura, que nombra una entidad existente en lugar de redactar una. |
labels | mapa de string | no | Etiquetas que se adjuntan a la entidad emitida, como un mapa de cadena a cadena. Los importadores del núcleo lo dejan vacío. |
annotations | mapa de string | no | Anotaciones que se adjuntan a la entidad emitida, como un mapa de cadena a cadena. Los importadores del núcleo lo dejan vacío. |
sourceRef | string | no | Una referencia al nodo de la fuente desde el que se emitió esta entidad, para que un lector pueda rastrear la entidad hasta su origen en la fuente importada. |
decisionRef | string | no | Una referencia a la decisión de asignación que produjo esta entidad, que la vincula con los candidatos sopesados y la elección hecha. |
No se permiten propiedades adicionales.
ImportDecision
Una decisión de asignación: el nodo de la fuente que resolvió el importador, las entidades candidatas del catálogo que sopesó, el candidato que eligió y el razonamiento detrás de la elección.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
sourceNode | DecisionSourceNode | sí | El nodo de la fuente que resolvió esta decisión: el nodo que el importador leyó de la fuente y asignó a una entidad del catálogo. |
candidates | ImportCandidate[] | no | Las entidades candidatas del catálogo que el importador sopesó para este nodo de la fuente, cada una con su puntuación y el desglose por señal detrás de esa puntuación. Ausente cuando el importador no sopesó candidatos. |
chosen | DecisionChoice | no | El candidato que eligió el importador para este nodo de la fuente, y cómo lo emitió. Ausente cuando el importador no hizo ninguna elección. |
rationale | string | no | Una explicación legible por personas de por qué el importador hizo esta elección. |
swapHint | string | no | Una sugerencia que describe cómo sustituir la asignación elegida por una alternativa, para que un lector pueda revisar la decisión. |
No se permiten propiedades adicionales.
DecisionSourceNode
El nodo de la fuente que resolvió una decisión de asignación: un identificador, el tipo con el que lo nombra la fuente y un resumen legible por personas de sus parámetros.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
id | string | sí | El identificador del nodo de la fuente dentro de la fuente importada. |
type | string | sí | El tipo del nodo de la fuente tal como lo nombra la fuente. |
paramsSummary | string | sí | Un resumen legible por personas de los parámetros del nodo de la fuente, para mostrarlo junto a la decisión. |
No se permiten propiedades adicionales.
ImportCandidate
Una entidad candidata del catálogo que el importador sopesó para un nodo de la fuente: el componente candidato, su puntuación global, el nivel de coincidencia en el que cae la puntuación y el desglose por señal detrás de la puntuación.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
componentName | string | sí | El nombre del componente candidato del catálogo. |
score | number | sí | La puntuación de coincidencia global del candidato, agregada a partir del desglose por señal. |
tier | string | sí | El nivel de coincidencia en el que cae el candidato, una franja aproximada sobre la puntuación. |
signals | CandidateSignals | sí | El desglose por señal detrás de la puntuación del candidato. |
No se permiten propiedades adicionales.
CandidateSignals
El desglose por señal detrás de la puntuación de un candidato: una contribución por cada señal coincidente. Un objeto de campos fijos, de modo que el conjunto de señales es estable y el formato de transmisión es determinista.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
table | number | sí | La contribución a la puntuación de la señal de la tabla de asignación. |
category | number | sí | La contribución a la puntuación de la señal de categoría. |
domainLabels | number | sí | La contribución a la puntuación de la señal de etiquetas de dominio. |
shape | number | sí | La contribución a la puntuación de la señal de forma. |
name | number | sí | La contribución a la puntuación de la señal de nombre. |
No se permiten propiedades adicionales.
DecisionChoice
El candidato que eligió una decisión de asignación: la entidad de destino del catálogo, cómo se emite y el nivel de coincidencia de la elección.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
target | string | sí | El nombre de la entidad de destino del catálogo elegida. |
mode | string | sí | Cómo se emite el destino elegido, reflejando el modo de una entidad emitida: una referencia a una entidad existente o un cuerpo recién redactado. |
tier | string | sí | El nivel de coincidencia del destino elegido. |
No se permiten propiedades adicionales.
ScaffoldFile
Un archivo de scaffold que produjo la importación: una ruta relativa a la raíz de salida de la importación y el contenido del archivo.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
path | string | sí | La ruta del archivo de scaffold, relativa a la raíz de salida de la importación. |
content | string | sí | El contenido del archivo de scaffold. |
No se permiten propiedades adicionales.