Habilidad de Revisión de Compilación de WASM y TinyGo

Comprobaciones de triple de destino, tamaño de binario y mal uso de syscall/js para agentes: una Habilidad de Agente estilo cookbook para compilaciones Go 1.26 y TinyGo WASM.

Qué Hace Esta Habilidad

Produce una lista de verificación de revisión de compilación de WASM: GOOS/GOARCH correctos, syscall/js vs syscall/wasmimport, etiquetas de destino de TinyGo, presupuestos de tamaño, compatibilidad del tiempo de ejecución del host (wazero, wasmtime) e importaciones prohibidas, antes de la fusión.

Cuándo Invocar

• PR añade objetivos de compilación GOOS=wasip1 GOARCH=wasm
• Cambios en firmware TinyGo o módulos WASM restringidos
• El scaffold del agente WASM del navegador con syscall/js
• Regresión de tamaño de binario en despliegue de borde
• Integración de host con el tiempo de ejecución wazero

Entradas

Salidas

• Tabla de validación del triple de destino
• Hallazgos de mal uso de importación/syscall
• Comandos de informe de tamaño (wasm-objdump, twiggy, tinygo size)
• Fragmento de prueba de humo del host para wazero
• Comandos de compilación de verificación

Barreras

1. No syscall/js en módulos WASI - API solo para navegador.
2. No cgo en la compilación cruzada WASM estándar, a menos que haya una excepción documentada.
3. TinyGo - verificar la placa y el planificador; la biblioteca estándar completa de Go puede no aplicarse.
4. Presupuesto de tamaño - bloquear nuevas dependencias pesadas sin justificación.
5. No usar os/exec ni sockets crudos en WASM sin documentación de capacidad del host.
6. API de wazero - verificar en la compilación; fijar en la cabecera de la habilidad.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

# Módulo WASI (Go 1.26)
GOOS=wasip1 GOARCH=wasm go build -o app.wasm ./cmd/wasi/
 
# Inspeccionar exportaciones y tamaño
wasm-objdump -x app.wasm | head -40
ls -la app.wasm
 
# Compilación restringida de TinyGo (ejemplo - verificar placa)
tinygo build -target=wasi -o tiny.wasm ./cmd/edge/
 
# Prueba de humo de wazero (host)
go test ./internal/wasmhost/... -run TestLoadModule -count=1

Cuándo recurrir a esta habilidad:

• El equipo de borde envía artefactos WASM de tamaño KB
• El agente usó fmt.Println y net/http en un borrador de WASM para navegador
• CI añadió destino WASM sin puerta de tamaño

Ejemplo de Trabajo

Paso 0 - Clasificar destino

Ver Go en WebAssembly: Rutas de Navegador, WASI y Embebidas

Paso 1 - Auditoría de importación

# Patrones prohibidos en WASI
grep -rn 'syscall/js\|js\.Value' --include='*.go' ./cmd/wasi/
grep -rn 'cgo\|os/exec\|"net/http"' --include='*.go' ./cmd/wasi/

Paso 2 - Presupuesto de tamaño

ls -la app.wasm
# Opcional: twiggy top para hosts enlazados con Rust; wasm-objdump para wasm de Go

• Comparar con el presupuesto en el ticket (ej. 500 KB gzip)
• Ver Optimización de Tamaño de WASM: TinyGo vs GC WASM

Paso 3 - Prueba de humo del host (wazero)

func TestLoadWASIModule(t *testing.T) {
    ctx := context.Background()
    r := wazero.NewRuntime(ctx)
    defer r.Close(ctx)
    mod, err := r.InstantiateWithConfig(ctx, wasmBytes,
        wazero.NewModuleConfig().WithStartFunctions("_initialize"))
    if err != nil {
        t.Fatal(err)
    }
    defer mod.Close(ctx)
}

• Verificar la instanciación, _initialize y la exportación run/main según el contrato del módulo
• Ver Tiempos de Ejecución de Host WASI: Wasmtime, wazero y Spin

Paso 4 - Específico de TinyGo

tinygo flash -target=pico -size=short ./cmd/firmware/   # ejemplo - verificar placa

• Planificador: evitar bloqueos permanentes sin ceder al host
• Verificar etiquetas //go:build tinygo para rutas de código divergentes

Análisis Profundo

Las mejoras en el tiempo de ejecución WASM de Go 1.26 pueden cambiar el comportamiento de asignación: re-evaluar el tamaño después de la actualización de la cadena de herramientas.

Ver Tiempo de Ejecución WASM y Mejoras de Memoria de Go 1.26

syscall/js requiere callbacks DOM y limpieza de js.FuncOf - revisión de fugas en objetivos de navegador.

WASI preview vs wasip1: las etiquetas de compilación y la matriz de capacidades del host deben coincidir con el entorno de despliegue.

Trampas

• Un solo main para linux y wasm sin etiquetas de compilación extrae importaciones incorrectas.
• Variables globales inflan las secciones de inicialización de WASM - preferir constantes e inicialización perezosa.
• Reflexión y fmt cuestan tamaño en TinyGo - auditar cadenas de formato.
• Probar WASM en host macOS - asegurar que CI compile el mismo triple que producción.

Alternativas

Preguntas Frecuentes

Relacionados

• Fundamentos de Habilidades de Agente - estructura de SKILL.md
• Fundamentos de WebAssembly y TinyGo - introducción a WASM
• Compilación con GOOS=wasip1 GOARCH=wasm - compilación WASI
• syscall/js: Go en el Navegador - API del navegador
• TinyGo para Microcontroladores y WASM Restringido - TinyGo
• Tiempos de Ejecución de Host WASI: Wasmtime, wazero y Spin - hosts

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación) y golangci-lint (última - verificar conjunto de linters en la compilación).