Errores y exit codes

Tocá Run para ver un error capturado; editalo (quitá el try/recover) para ver un Runtime error: … sin capturar.

-- Doc example: how errors surface — raise, try/recover, and a clean message.
-- Edit this and press Run: remove the try/recover to see an uncaught
-- "Runtime error: x must be >= 0 …" instead.
intent: "doc example: errors"

task risky(x)
    when x < 0
        raise("x must be >= 0, got " + text(x))
    give x * 2

task fails()
    give risky(-1)

-- run shows the recovery in action:
try
    print("risky(5) = " + text(risky(5)))
    print("risky(-3) = " + text(risky(-3)))      -- this one raises
recover err
    print("caught → " + err)

test "raise fails; try/recover catches the message"
    assert_eq(risky(5), 10)
    let caught be ""
    try
        let bad be risky(-1)
    recover err
        set caught to err
    assert(contains(caught, "must be >= 0"))
    assert_error(fails)

Lanzar y capturar

raise("mensaje")            -- fallar a propósito (o re-propagar dentro de recover)

try
    risky()
recover err
    log "falló: " + err     -- err es el mensaje (text)
    raise(err)              -- RE-PROPAGA; sin esto, recover se traga el error

give y stop no son errores — pasan por try/recover. (fail(...) arma una respuesta HTTP, no lanza.) Testeá que algo lanza con assert_error(task). La forma sentencia raise "msg" / raise err (sin paréntesis) también funciona, y un raise solo es error de parseo con el fix en el mensaje. ⚠️ En el v0.5.1 publicado y anteriores, raise "msg" sin paréntesis eran dos expresiones inertes — no-op silencioso; en esos binarios siempre raise("msg").

Otro error que conviene reconocer a primera vista: 'decide' is a reserved word in Synsema; choose another name for the member after '.' (en v0.5.1 y anteriores: el críptico Expected IDENTIFIER, got DECIDE) significa que una palabra reservada dura se usó como nombre de export, parámetro o miembro — mod.decide(...), task wait(reason). Las palabras LLM reason/decide/analyze/generate están reservadas en todas partes; renombrá (resolve, why).

Exit codes

El run plano imprime una línea estable: Runtime error: <file>:<line>:<col>: <msg>. ¿Lo medís en una shell? Redirigí (… >/dev/null; echo $?) — no pipees antes de echo $?, o leés el code del pipe.

Diagnósticos ricos (--explain)

synsema run --explain program.syn                # legible, en stderr
synsema run --explain --format json program.syn  # estructurado, para tools/agentes

El reporte agrega: contexto de fuente, call stack, variables visibles, el intent del programa, una clasificación (data / io / logic / capability / type), si es recuperable, y sugerencias de fix. El exit code no cambia en ningún caso.

Formas comunes de error

• Capacidad: Capability not granted: net("…") — agregá el require correspondiente (o ampliá el scope).
• Tipo: una operación recibió el tipo equivocado (p. ej. as_secret(123) → "expects text or bytes").
• Datos: una key de map faltante, un índice fuera de rango, JSON inválido en json_decode.