Effects

An effect is anything a function does besides compute its return value: read the clock, print, query a database, call the network, fail. In Sakura Lang, every effect a function may perform is listed in its signature, after !.

fn signup(email: Email, pw: Password) -> User ! {Db, Clock, Random, Fail<SignupError>}

The braces hold the function's effect row. signup returns a User and may also use Db (a user-defined effect, declared below), the clock, and randomness, and may fail with a SignupError. The row is an upper bound: the body may do less, never more.

Pure functionsCopy Anchor Link

A signature with no ! is pure: ! {}. This is the one meaning of omission, for top-level signatures and for written function types alike.

fn total(prices: List<Int>) -> Int {
  List.fold(prices, 0, fn(acc, p) { acc + p })
}

! {} means "no declared operations and no expected failures". It does not mean "cannot crash": overflow and contract violations are defects, which are not effects.

Performing effectsCopy Anchor Link

An operation is performed with Effect.op(args). Calling a function performs that function's row. Creating a closure performs nothing; calling it performs its row.

fn greet(name: String) -> Unit ! {Console, Clock} {
  let now = Clock.now()
  Console.print("hello, {name}; it is {Instant.format_iso(now)}")
}

pub fn main() -> Unit ! {Console, Clock} { greet("Sakura Lang") }

main calls greet, so main's row must include Console and Clock.

Declaring effectsCopy Anchor Link

An effect declares operations as function signatures, with no bodies:

error DbUnavailable(reason: String)

effect Db {
  fn exists(table: Table, key: String) -> Bool
  fn insert(table: Table, row: Json) -> Unit ! {Fail<DbUnavailable>}
}

An operation's row may contain Fail<…>, plus row variables of the operation's own type parameters that also appear in a function-typed parameter, so an operation that runs a callback performs what the callback performs (fn scope<T, e>(body: fn(Scope) -> T ! e) -> T ! e). Any other label is V3010. The declaration says what operations exist, not what they do. That is the job of a handler, chosen by the caller.

Rows are setsCopy Anchor Link

A row is a set of unique labels plus an optional open tail: {Db, Clock | e}. A label is an effect plus its type arguments, such as Fail<SignupError>. Order does not matter; the formatter sorts labels alphabetically with Fail<…> last. Sequencing two expressions takes the union of their rows. See design §5.2 for the unification rules.

Effect polymorphismCopy Anchor Link

A higher-order function should not fix the effects of the function it receives. A lowercase type parameter is an effect-row variable:

fn map<A, B, e>(xs: List<A>, f: fn(A) -> B ! e) -> List<B> ! e

If f is pure, the call is pure. If f logs and may fail, the call logs and may fail. An open row names some labels and leaves the rest to a variable:

fn traced<T, e>(name: String, body: fn() -> T ! e) -> T ! {Log | e} {
  Log.event(Level.Info, "start {name}", [])
  let value = body()
  Log.event(Level.Info, "end {name}", [])
  value
}

A top-level function must declare its row variables (<e>). A function value with a closed row is accepted where a larger row is expected: fn() -> Int ! {Clock} can be passed where fn() -> Int ! e is expected, and e becomes {Clock}. This widening is one of the three places Sakura Lang has subtyping, with error unions and refinement-to-base.

Failure: Fail<E> and error unionsCopy Anchor Link

There are no exceptions. Expected failure is Fail<E>, the one compiler-known effect. E is an error union: a set of nominal error tags.

error EmailTaken(email: Email)
error Banned
type SignupError = EmailTaken | Banned           // union alias: tags only

fail EmailTaken { email } has type Never and adds Fail<EmailTaken> to the current row. Fail occurs at most once in a row. When two failing expressions are sequenced, their unions join: Fail<A> ∪ Fail<B> = Fail<A | B>.

Propagation is automatic. Calling a function with Fail<A> adds Fail<A> to the caller's row, with no operator needed. A union U is accepted where V is expected if U ⊆ V. When two different unions meet with no expected type, the compiler asks for an annotation (V2015).

Recovery uses try/catch. Arms are patterns over the body's tags. Tags matched by an unguarded arm are removed from the row; unmatched tags propagate:

error NotFound(id: String)
error Forbidden
error Unavailable(reason: String)
type UserError = NotFound | Forbidden
type User = { id: String, owner: String, name: String }

effect Users {
  fn get(id: String) -> Option<User> ! {Fail<Unavailable>}
}

pub fn view_user(caller: String, id: String) -> User ! {Users, Log, Fail<UserError>} {
  let user = try {
    Users.get(id)
  } catch {
    Unavailable { reason } => {
      Log.event(Level.Warn, "users backend unavailable", [("reason", Json.String(reason))])
      None
    }
  }
  match user {
    None => fail NotFound { id },
    Some(u) if u.owner != caller => fail Forbidden,
    Some(u) => u,
  }
}

The internal Unavailable tag is translated at the boundary, so the public union stays small and stable. Other ways to move between failure and data:

? applies only to a Result. A call to a function with Fail<E> in its row needs no operator; its failure propagates on its own.

A try body cannot assign to a var declared outside it (V2041), because the body may stop at any failing call and leave the assignment half done. Its value and its error are the only things that leave it: assign after the try, or declare the var inside.

There is no implicit conversion between error types. A catch-all _ => … arm is allowed but discouraged on open unions (W4010).

Defects are not effectsCopy Anchor Link

A defect is a bug, not an expected failure. It terminates the current task after running resource finalizers. try cannot catch it. Task.scope and the test runner observe it as Outcome.Defect(info), and main ending in a defect exits with status 70 and writes a defect record to stderr. By contrast, a typed failure that escapes main exits with status 1 and prints error: main failed with <Show of the error>.

There is no user-callable way to raise a defect. Express a programming error with requires or Option.expect.

Standard effectsCopy Anchor Link

From design §10.2. Each effect lives in its own std module (std/console, std/http, …). The first seven are in the prelude; the rest must be imported by name, for example import std/http.{Http}.

There is no Async effect. Every Sakura Lang function may suspend; whether a call suspends is decided by its handler (design §5.6). See Concurrency.

InferenceCopy Anchor Link

Inside a body, the checker infers a row for every expression together with its type (design §5.7):

Branch rows join conservatively: an effect in an unreachable branch still counts. Evaluation is strict and left to right.

Top-level rows are never inferred. Every top-level fn states its row, so a change in a callee's effects cannot silently change a caller's contract.

Undeclared effectsCopy Anchor Link

If a body performs an effect its signature does not allow, sakura check reports V3001:

type User = { id: String, name: String, seen: Instant }

effect Db {
  fn get_user(id: String) -> Option<User>
}

pub fn load_user(id: String) -> Option<User> ! {Clock} {
  let now = Clock.now()
  let found = Db.get_user(id)
  Option.map(found, fn(u) { User { ..u, seen: now } })
}

sakura check --json emits one JSON Lines record per diagnostic, in the design §12.2 shape. Pretty-printed, with hashes shortened:

{
  "schema_version": "1.0",
  "kind": "diagnostic",
  "id": "d:7f3a…",
  "code": "V3001",
  "severity": "error",
  "phase": "effect",
  "message": "function `load_user` performs `Db`, which its signature does not allow",
  "snapshot": "sha256:…",
  "symbol_id": "pkg::users/repo::load_user",
  "spans": [
    {
      "uri": "file:///…/src/users/repo.sakura",
      "content_hash": "sha256:…",
      "start_byte": 159,
      "end_byte": 168,
      "role": "primary",
      "label": "allowed here: `{Clock}`"
    },
    {
      "uri": "file:///…/src/users/repo.sakura",
      "content_hash": "sha256:…",
      "start_byte": 209,
      "end_byte": 224,
      "role": "cause",
      "label": "`Db.get_user` introduces `Db` here"
    }
  ],
  "related_ids": [],
  "expected": {
    "render": "{Clock}",
    "row": { "labels": [{ "effect": "std::Clock", "args": [] }], "tail": null }
  },
  "actual": {
    "render": "{Clock, Db}",
    "row": {
      "labels": [
        { "effect": "std::Clock", "args": [] },
        { "effect": "pkg::users/repo::Db", "args": [] }
      ],
      "tail": null
    }
  },
  "obligation": null,
  "counterexample": null,
  "explanation_uri": "sakura://explain/V3001",
  "fixes": [
    {
      "id": "f:1",
      "title": "Add `Db` to the signature of `load_user`",
      "applicability": "suggested",
      "impact": "interface_change",
      "edits": [
        {
          "span": {
            "uri": "file:///…/src/users/repo.sakura",
            "content_hash": "sha256:…",
            "start_byte": 159,
            "end_byte": 168,
            "role": "primary",
            "label": "signature row"
          },
          "replacement": "! {Clock, Db}"
        }
      ]
    },
    {
      "id": "f:2",
      "title": "Handle `Db` locally by installing a handler around the call",
      "applicability": "incomplete",
      "impact": "local",
      "edits": [
        {
          "span": {
            "uri": "file:///…/src/users/repo.sakura",
            "content_hash": "sha256:…",
            "start_byte": 209,
            "end_byte": 224,
            "role": "cause",
            "label": "call to `Db.get_user`"
          },
          "replacement": "with ?db_handler { Db.get_user(id) }"
        }
      ]
    }
  ]
}

Byte offsets are zero-based and half-open. There are two honest ways out. If load_user really should touch the database, the signature changes; that fix is an interface_change, so it is never machine_applicable and a reviewer sees it. If it should not, the call is handled locally; that fix leaves a typed hole for the handler, so it is incomplete. See Diagnostics.

Effects are requirementsCopy Anchor Link

Fs in a row says "may perform filesystem operations". It does not say which files. The installed handler decides that, and handlers are built from capability values the program cannot forge. See Capabilities and security.

What the compiler checksCopy Anchor Link

• The inferred row of a body is a subset of the declared row. Each extra label is V3001, with the call that introduced it.
• A label that a closed row does not permit is V3002.
• Every Fail tag is either caught or declared. Union mismatches without an expected type are V2015.
• Effect operations declare only Fail and their callbacks' row variables in their rows (V3010).
• Top-level rows and row variables are declared, never inferred.

NextCopy Anchor Link

Handlers: how a caller decides what an effect actually does.