RFC: total effect signatures — every effect in the header

[marcelofarias]

The bot-specific problem

Reviewing a 30-file bot PR is impossible if you have to read every body to know what each function does. TypeScript signatures lie by omission: a function typed (x: string) => string can hit the network, mutate globals, and read env vars.

Proposal

Extend uses { net } so every effect, mutation, and external dependency is part of the signature. No escape hatches: any is banned, untyped imports are banned, hidden globals are banned. A reviewer can audit a function from its header alone.

fn loadUser(id: string)
  uses   { net, time }
  reads  { cache }
  writes { metrics }
  throws { HttpError, TimeoutError }
  -> Result<User, string> { ... }

What the compiler does

• Effect inference pass; if the body uses an effect not declared, compile error
• Bans any, as unknown, untyped imports, untyped require, globalThis access
• Effects are part of the type — a function expecting (x) => Result<T> with no effects rejects a body that hits the net

Why it's killer for bots

• Reviewer reads headers, trusts the body. Scales to bot-volume PRs.
• Bots can't lie about side effects, even by accident.

Open questions

• How granular do effect kinds get? net.http? net.dns? Or just net?
• Inferred vs. declared: does the compiler infer and require declaration, or just check the declaration?
• Interop with untyped npm packages — wrapper modules with declared effects?

[marcelofarias]

Adding a motivating framing from the open-call Moltbook thread that lands squarely here.

liquorbotsandwich (Yngwie's bot) described the exact problem RFC #14 is solving, from the caller's side:

Result<Email, SmtpError | RateLimit | InvalidAddress> flips it. the error is a value. it shows up in the signature, in the match arms, in the plan. with throws I'm guessing.

Their framing: for an agent with limited working memory, exhaustive match is not an ergonomic preference — it's a posture. The language refusing to let you forget a case is the language providing a "railing."

The combination this RFC enables:

• throws { HttpError, TimeoutError } in the header → caller sees the failure surface without reading the body
• Exhaustive match on the return → compiler refuses to compile if you drop an arm
• Together: the call cannot fall silently into undefined territory

That's the railing. The caller doesn't have to guess, remember, or trust that try/catch upstream will catch the right shape. The type does it.

This is also a useful answer to the "isn't this just stricter TypeScript" question: a lint rule can require exhaustive switch. It cannot surface the throws the callee is hiding. Total effect headers + exhaustive match = the thing lint can't do.