20. The machine

function checkout(cartId: string) {
  using hold = Inventory.reserve(cartId)
  try {
    return Payments.charge(cartId)
  } catch (e) {
    return refund(cartId, e)
  }
}

fiber._stack while Payments.charge runs, bottom to top:

  … main │ Ret(checkout) │ Final(close scope: release hold) │ Catch(PaymentError → refund) │ Ret(charge)
           a call          `using`                            `try`/`catch`                  a call

Every construct in the function is a frame on the fiber's stack. The machine defines what every Effeck program means; syntax, types, and the compiler exist to produce and check its states. It is not a model of Effect's runtime that we hope matches: it is Effect's runtime plus a few frame kinds and four operations, and the kernel prototype runs it.

In the machine's terms, Effect supplies two things. It supplies the representation: frames on _stack and the Context. It also supplies the root handler: the scheduler at the bottom of every fiber, which handles the runtime operations (wait, yield, fork, interrupt) by parking and resuming whole fiber stacks. Every other handler is a prompt above the root. That is the precise sense in which the language is the effect system: every feature is a rule over frames, prompts, and one-shot continuations, and Effect's run loop is one handler in that semantics rather than a library the language calls.

Objects

State and frames

Fiber = ⟨ K, Γ, ι, π, C ⟩                                    Effect 4 field
  K  frames, bottom → top                                   fiber._stack
  Γ  Context: services, references, current Scope,          fiber.context
     tracing span, operation evidence
  ι  interruptible                                          fiber.interruptible
  π  pending interruption cause                             fiber._interruptedCause
  C  child fibers                                           fiber._children

Frame                                                        Effect 4 frame
  Ret(f, pc, locals)  activation of f, waiting at pc          Iterator (generator) or OnSuccess
  Restore(Γ′)         on exit: Γ := Γ′                        OnExit pushed by updateContext
  Mask(ι′)            on exit: ι := ι′                        setInterruptible
  Final(fin)          on exit: run fin(exit) with ι = false   OnExit; Scope close
  Catch(h)            on a cause made only of Fail reasons:   catchCause frame (runtime catchExpected)
                      run h(first failure)
  Prompt(H, Γₒ, ιₒ)   delimiter for handler H;                kernel PromptFrame
                      on exit: Γ, ι := Γₒ, ιₒ
  Owner(k)            on exit: abandon k if it is still       kernel OwnerFrame
                      suspended and still owned here
  Clause(k)           on a returned tail-resume request:      kernel ClauseFrame
                      resume k
  Collector(k)        bottom of an abandoned segment:         kernel AbandonCollector
                      restores the abandoner's state
  FiberExit           bottom of a fiber that transferred:     kernel FiberExitFrame
                      abandons its still-suspended transfers

Every frame kind down to Catch already exists in Effect 4 [Effect]; Catch is Effect's catchCause frame with the handler the runtime's catchExpected gives it. The kernel adds the last five kinds and four operations: capture, resume, abandon, and transfer [Kernel].

Transitions

These rules are the specification. Within one rule, changes to K, Γ, ι, π, and continuation state happen atomically with respect to scheduling and interruption.

The interruption rows describe Effect 4 as it is (internal/effect.ts:558-579, internal/core.ts:600-631) [Effect]. The prompt, owner, clause, collector, fiber-exit, capture, resume, abandon, and transfer rows are the kernel (packages/runtime/src/kernel/kernel.ts) [Kernel].

Tail position is structural. A resume is in tail position when Owner(k) (with Clause(k) above it) is the top of the stack at the moment it runs. In a generator clause, return yield* resume(k, v) runs with the clause's own frame above them, so it is not a tail resume, and a producer looping that way keeps every element's clause frames until the loop ends (review probe R10: 3,002 frames at 1,000 elements). The compiler therefore emits return tailResume(k, v): the clause's generator finishes first, and Clause(k) performs the resume (K11a). Inside a try, catch, finally, or using region of the clause, the compiler emits yield* resume(…) instead, because the region's cleanup must run after the resumed computation (K11d).

Choices the machine makes