Errors & exit codes

Press Run to see a caught error; edit it (remove the try/recover) to see an uncaught Runtime error: ….

-- 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)

Raising & catching

raise("message")            -- fail deliberately (or re-propagate inside recover)

try
    risky()
recover err
    log "failed: " + err    -- err is the message (text)
    raise(err)              -- RE-PROPAGATE; without it, recover swallows the error

give and stop are not errors — they pass through try/recover. (fail(...) builds an HTTP response, it does not raise.) Test that something raises with assert_error(task).

Exit codes

Plain run prints a stable one-liner: Runtime error: <file>:<line>:<col>: <msg>. Measuring it in a shell? Redirect (… >/dev/null; echo $?) — don't pipe before echo $?, or you read the pipe's code.

Rich diagnostics (--explain)

synsema run --explain program.syn                # human-readable, on stderr
synsema run --explain --format json program.syn  # structured, for tools/agents

The report adds: source context, call stack, visible variables, the program intent, a classification (data / io / logic / capability / type), whether it's recoverable, and fix suggestions. The exit code is unchanged either way.

Common error shapes

• Capability: Capability not granted: net("…") — add the matching require (or widen the scope).
• Type: an operation got the wrong type (e.g. as_secret(123) → "expects text or bytes").
• Data: a missing map key, an out-of-range index, invalid JSON in json_decode.