Contrato WIT

El contrato entre orkan-server y un módulo está escrito en WIT y se llama orkan:module@1.0.0. Es la fuente de verdad: lo que hay aquí es un resumen.

Mundos

Mundo	Qué exporta	Quién lo usa
`node-module`	`node`	Módulos con pasos.
`trigger-module`	`node` y `trigger`	Módulos con pasos y pasos de inicio.
`core-module`	Lo anterior, más el import `host-flow`	Reservado a `orkan.core`. Un módulo de terceros no puede usarlo.

Lo que exporta un módulo

node

describe: devuelve un JSON versionado con los pasos, sus parámetros, puertos y tipos de cuenta.
execute: ejecuta un paso. Recibe el contexto de la ejecución, los parámetros ya resueltos (los datos de pasos anteriores, evaluados), los slots de cuentas y los elementos de entrada por puerto.
resolve-options: opciones dinámicas de un campo (las listas desplegables del editor).
test-credential: comprueba una cuenta contra el servicio.

trigger (pasos de inicio)

handle-webhook: verifica la firma del proveedor y normaliza la petición.
poll: una consulta periódica. Orkan programa la frecuencia y guarda el cursor.
listen: escucha cooperativa para conexiones largas (por ejemplo, IMAP IDLE): Orkan llama en bucle, con un plazo por llamada.

Lo que ofrece el host

Import	Para qué	Capacidad que exige
`host-log`, `types`	Escribir registros (Orkan oculta los secretos conocidos y limita el ritmo).	Ninguna
`wasi:http/outgoing-handler`	Peticiones HTTP a los servidores permitidos.	`network.http`
`wasi:sockets/*` y `host-net`	Conexiones TCP/UDP a los `host:puerto` permitidos.	`network.socket`
`host-state`	Guardar estado entre ejecuciones (ámbitos `node`, `workflow` y `module`).	`state`
`host-binary`	Leer archivos de los elementos de entrada y crear nuevos.	`binary`
`host-ai`	Llamar a modelos de IA de Orkan.	`ai`
`host-sql`	Consultas SQL parametrizadas con una cuenta.	`sql`
`host-credentials.read-secret`	Leer en claro un campo secreto. Alto riesgo.	`credentials.read-secret`
`host-flow`	Esperas, subautomatizaciones y respuestas a enlaces.	`flow` (solo `orkan.core`)
`wasi:io`, `clocks`, `random`, `cli/std*`	Lo básico de WASI.	Ninguna
`wasi:filesystem/*`, `wasi:cli/environment`	Tolerados, pero vacíos: sin directorios ni variables.	Ninguna

Al instalar un módulo, Orkan inspecciona los imports reales del componente y rechaza el módulo si falta alguna capacidad por declarar. orkan-module build hace la misma comprobación antes de empaquetar.

Reglas que fija el contrato

Los elementos y los parámetros viajan como JSON en texto; los puertos, por índice.
El módulo nunca elige qué cuenta usa: solo el nombre lógico que declaró. Orkan le pasa un slot y pone la autenticación real justo antes de que la petición salga, por lo que no ve la clave. Esto necesita además la capacidad credentials.inject.
Un error transient puede llevar retry-after-ms para respetar los límites de ritmo del servicio.
WASI 0.2 no deja que un componente mantenga tareas propias entre llamadas: por eso listen es cooperativo y el estado va por host-state.

Errores

Variantes de node-error y qué hace Orkan con cada una:

Variante	Se reintenta
`user`, `config`, `credential`, `denied`	No
`transient`	Sí, respetando `retry-after-ms`
`internal`	Sí; no la uses para fallos que se repetirán siempre

Siguiente: manifiesto y firma.