Explicit global declarations

Status: accepted. Decision: Mark, 2026-11-01. Language: Mix 0.119.0.

Function assignment defaults to a local binding while reads fall through to the program-global frame. A helper doing $conns = delete($conns, $key) therefore reads the global map but stores a local copy. This has caused repeated connection leaks. Handler bodies and helpers previously behaved differently for the same assignment.

Decision

Add the reserved statement global $a, $b. Once executed, assignments to these names, including self-concat, compound assignments, in-place mutations and index/field/path writes, target the program-global frame through the same shared-global machinery used by serve handlers. Assignment creates a missing global; a missing read remains an undefined-variable error.

Declarations belong to the current function invocation, including recursive calls independently. They are not inherited by called functions or lambdas. Lambdas must declare too: one rule applies to all function invocations. Declaration inside control flow is allowed and idempotent; it takes effect only when reached. Lint checks textual order without evaluating conditions, and notes conditional declarations.

Reject a parameter (GLOBAL_PARAM), a name already in the current local frame, including captures and module injections (GLOBAL_AFTER_LOCAL), a declared global used as a loop/catch/parse binder (GLOBAL_BINDER), and the runtime-owned names $event, $rc, $result, $reply (GLOBAL_RUNTIME_NAME). Module-variable errors explain that module variables are not globals. A same-named local and declaration cannot coexist.

At ordinary program or module top level the declaration is a no-op by construction. In a handler it is honoured: in Class C, an otherwise new name can be created in the invocation's local root and disappear; declaring it routes creation to the shared program-global frame. Lint emits a note outside functions. A declaration inside a required module function targets the importer's program globals, never the module's captured state.

global cannot name a function. Map keys and fields remain valid: {global: 1}, $m.global, $m["global"].

Implementation constraints

Keep declaration sets in Scope alongside function floors. Exclude declarations from synchronous function eligibility and local-slot caching: a helper that creates a global must never rehash the global map while a top-level loop holds raw slot pointers into it. Shared globals retain their existing statement-sized borrow discipline; declaration adds no atomic transaction across yields.

Alternatives rejected

Write-through by default breaks helpers that deliberately reuse names such as $r and $m as locals: the existing fleet agent lint found 463 outer-name assignment hits. Keep local assignment as the default.

Lint alone protects against mistakes but leaves no direct way to express an intentional program-global update. Path writes into a shared map remain useful, but are not a substitute for an explicit declaration.

The earlier no-global-by-design rule is superseded by this decision.