restricted-global-mutable-state
Referencetoplevel mutable state in library code
restriction · warning · stable · since 1.0 · fix: never · off by default
A ref, Hashtbl.t, or mutable-record value bound at a library’s
toplevel lives for the whole process: every consumer shares it, tests
interfere through it, two domains race on it, and no caller can create
a second independent instance. Litany’s own law — pure core, state in
the driver — is this rule, self-applied.
(* bad *) let registry : (string, handler) Hashtbl.t = Hashtbl.create 16(* good *) a table created by the caller and passed down, or a `create`d value the API threads explicitlyWhy restrict this? Deliberate globals are legitimate — fmt’s style
store and cmdliner’s uid counter are designed — and the field count is
small (2 sightings in ~9,700 reviewed lines), so a ban is house
policy, not a defect claim: off even under --select all,
cherry-picked by a
workspace whose libraries keep state in the caller. The known
false-positive shapes are named up front: memo tables, interning
pools, and caches are deliberate state, and [@litany.allow] with a
reason is the designed outlet — a lazy cache (let table = lazy …)
is already the blessed initialize-once spelling and stays clean by
shape.
Fires once per variable bound by an item of the unit’s root structure —
a root include struct ... end’s items included: they land on the
unit’s export surface like any root item — whose type’s head is
Stdlib.ref, Stdlib.Hashtbl.t, or a record type declared at the
unit’s root with a mutable field, in units whose roster kind is
Library. Executables and tests own their
process and never fire; a unit whose roster carries no kind is
deliberately silent — a metadata-gated rule degrades to silence,
never to guessing. Local bindings inside functions and
let-expressions, lazy thunks, pure records, and functions that
merely return fresh state deliberately do not fire. Arrays are out of
scope in v1: the array type does not distinguish a buffer from state —
a lookup-table literal and a mutable accumulator spell the same type —
so an array ban would claim a structural proof the type cannot give.
Abbreviation heads are compared as inferred, never expanded
(type counter = int ref stays clean), a mutable-record head the
unit does not declare at its own root — a nested module’s, one
included from a named module, another unit’s — stays clean, and a
binding that binds no variable or destructures stays clean: each is a
recorded false negative in the safe direction. No fix: moving state
into the caller is an API redesign.

