Hazel reports · ^report(24) · architecture · 2026-10-21

Hazel's Architecture Around #2651

How is Hazel built around #2651 (Statics: a module binding analyzes its definition once, not twice), and what does the PR change in that architecture? Matthew Hammer and Alexander Bandukwala, who owns Modules II, reviewed #2651 together on 2026-10-21, aiming to merge it that day. Matthew had tested its behaviour, and asked how Hazel is built around it: the subsystems an edit passes through, the representations they share, the protocols between them, and the PR drawn in those terms. Read, and six module programs run with the command-line tool (the runs), at dev 962a7cb009 and at 29c08fd8fa, the PR's head until fa3eef62ce and b5a3e1d90a, pushed during the review, which change only comments and one test's name.

The subsystems, and what flows between them

Hazel is a structure editor: the program is always a tree of tiles, and every edit leaves a program that can be typed and run. An edit passes through five subsystems in a fixed order, all on the page's main thread except evaluation (Figure 1).

• The editor. The program is a segment: a list of pieces (tiles, grout, whitespace, projectors), where each tile has an id and child segments (Base.re:3-28). The zipper is the caret's place in that tree (ZipperBase.re:13-20). A key press becomes an Action, wrapped as Perform (CodeEditable.re:343), and Perform.go edits the zipper, consulting the previous statics as it does (Editor.re:146-184).
• MakeTerm. Turns tiles into a term, Exp.t, and gives each term node the ids of the tiles that make it up (MakeTerm.re:290-306). For statics it first fills in the pieces missing from the visible segment, its canonical completion (MakeTerm.re:1997-2013).
• Statics. One recursive walk over the whole term, from an empty map (Statics.re:4350-4381), that types and elaborates at once. It returns the info map, one record per expression id, and the elaborated program. It runs on the main thread, 225 ms after typing stops, or at once after a projector's commit (CodeWithStatics.re:93-141).
• Evaluation. The elaborated program goes to the eval worker by postMessage, with a slice of the info map (EvalInfo) and the previous run's cache (EvalResult.re:250-293). The worker evaluates in slices; for a program of at least 2,500 EvalInfo entries it also reuses earlier results, keyed by expression id, and below that it evaluates from scratch (WorkerServer.re:300-304).
• Results back. The worker's messages come back as actions: values, probe samples and test results. The page updates its model, recalculates without running statics again, and redraws, error marks included.

Every reader looks a record up by id. So whichever analysis writes a node's record last decides what the cursor inspector, the error marks, completion, projectors, probes and the worker's reuse check all see (StaticsBase.re:10-11: add_info is a plain Id.Map.add). That is what gives #2651 its architectural side: it changes which analysis writes last inside a module's definition (the PR).

On dev statics is one walk of the whole program per refresh. Andrew Blinn's #2469 (Modular editors), not yet on dev, adds DefStatics: statics per top-level definition, with the context passed from one to the next, so that an edit re-analyzes the edited definition and those that read a name it changed (DefStatics.re:3-10^{2469 head}). Inside one definition the walk is the same, so #2651 applies under both.

The representations they share

The subsystems pass five things along: the segment, the term, the info map, the elaborated program and EvalInfo. What ties them together is the id. MakeTerm gives a term node its tile's id, statics files the node's record under that id, EvalInfo keeps the node's elaboration under it, and the worker keys its probe samples and cached results by it (Figure 2). A term made inside statics can carry an id it borrows: the ModuleExp case builds its let with the ModuleExp's own id (IdTagged.re:175-183, used at Statics.re:2737-2741), so that let's record lands where the binding's would.

Each row's links point to dev at 962a7cb009, except the read-back, which is at #2651's head (marked PR). User terms and elaborated terms share one type, so an elaboration is an ordinary Exp.t whose ids mostly match the source.

An edit's round trip, and the worker's messages

Figure 3 follows one key press. Every action goes through an update phase and then a calculate phase (Main.re:73-110):

1. The key becomes an action, Perform(Insert(c)) (CodeEditable.re:343), and Editor.Update.update runs Perform.go on the zipper with the statics of the previous refresh (Editor.re:146-184).
2. The calculate phase asks the debounce whether to run statics. While typing it says Defer and starts a 225 ms timer; when the timer fires it dispatches a refresh that says Force (CodeWithStatics.re:104-140). Statics runs on Force, on an edit that is not deferred, or when the set of probes changed (CodeWithStatics.re:200-204).
3. CachedStatics.init parses the zipper for statics, runs Statics.mk over the whole term, and derives the error ids, warning ids and probe targets (CachedStatics.re:188-226, CachedStatics.re:99-135). The time it takes shows in the debug sidebar's Statics timer (CodeWithStatics.re:188).
4. Editor.Update.calculate refreshes the completion buffer from the record at the caret, the syntax cache and the probes (Editor.re:186-230).
5. EvalResult.calculate projects the info map to EvalInfo every time it runs (EvalResult.re:270-275). It queues a request for the worker only when the elaborated program (compared ignoring ids), the settings or the probe targets changed (EvalResult.re:251-261, EvalResult.re:279-293).
6. The worker answers with messages, Figure 4; each comes back as an action, which updates the result and recalculates without running statics again.

The worker's protocol is in WorkerServer.re:7-89. A request carries, for each editor, the elaborated program, the EvalInfo slice and the previous run's incremental cache, Marshal-encoded. The worker posts an Ack at once; then a ReusePlan, its prediction of what it can reuse, for every batch it plans (WorkerServer.re:495-506, WorkerServer.re:431-439); then a Stream message after each slice of 5,000 steps (WorkerServer.re:271); and last a Result. Below 2,500 EvalInfo entries the prediction is empty and the worker evaluates from scratch, without the previous run's cache (WorkerServer.re:300-304, WorkerServer.re:315-319, WorkerServer.re:366). The page restarts a worker that has not acked in 5 s (15 s from a cold start), up to three times, and gives up on a request after 20 s (WorkerClient.re:5-11). Its callbacks become result actions (EvalRequest.re:6-41).

Reuse is where statics and the worker meet, for a program of at least 2,500 EvalInfo entries; a smaller one is evaluated from scratch, with no reuse check (WorkerServer.re:300-304, WorkerServer.re:366). At each expression, the worker's reuse check compares the elaboration EvalInfo recorded at that id with the one the cached result was computed from, then the provenance of the free variables in the record's co-context, then the probe targets (IncrEval.re:313-353). So what statics writes at an id matters to the worker as much as to the editor: the same last write is what both see.

Inside statics

The walk

Statics is one function, uexp_to_info_map, called on every expression (Statics.re:191-201). It takes the context (what is in scope), the expected type, the term and the map, and returns the term's record, its elaboration and the new map. Each case analyzes the children it needs, passing context and expected type down and getting records and elaborations back, and ends by calling add (Statics.re:204-269). add works out the error marks, the inspector's message and the fixed type, builds the record, writes it at every id of the term, and returns the same elaboration it wrote (Statics.re:268). So the walk has two outputs at once: the map, and the root's elaboration, which Statics.mk returns for the evaluator (Statics.re:4350-4381).

Two more facts about the map matter for #2651. Some passes throw their map away: probes such as the let's recursion probe (Statics.re:2070) analyze a whole subterm and keep only its type. And statics already reads its own map back in the middle of the walk: the let's fixpoint patch (Statics.re:2216-2228), the ModuleExp case's class override (Statics.re:2743-2756), and a module's type, built from the records of its exported patterns (ModuleHelpers.re:413-439). #2651 adds one more read of the same kind.

One record: mode and self, context in, co-context out

Hazel's statics has long been described in terms of a mode (analyze against a type, or synthesize one) and a self (what a term gives, errors included), and both used to be types of their own; Matt Keenan removed them (d22a778d64, Mode, 2025; ae3f3edde3, Self, 2026). Today the mode is just the expected type, ana: Unknown(SynSwitch) means synthesize (StaticsBase.re:263). The self is the synthesized type, elab_syn_ty, with the marks and message add computes, and ty is their meet with the expected type (StaticsBase.re:268-277).

The context goes down: a list of entries, newest first (Ctx.re:37-57). A variable looks itself up there and reports itself unbound if it is missing (Statics.re:691-705). The co-context goes up: each free variable with the ids of its uses (CoCtx.re:30-53). A binder takes its own names out (CoCtx.re:43-53), which is how unused variables are found, how a let decides it needs a fixpoint, and how a probe knows which bindings to capture (StaticsBase.re:46-53).

Elaboration inside statics

There is no separate elaborator. Matt Keenan's cc620bbbdc ("delete elaborator", committed 2026-04-17) folded it into statics: each case builds its node's elaboration from its children's, and add records it. One detail of that port is the subject of #2651. The old elaborator elaborated a module binding's definition by reading the info map, with no second analysis (Elaborator.re:518-524^a81e3188fd); the port turned that into a second call to the walk, def_elab_direct (Statics.re:2757-2762). #2651 returns to reading the map.

How a let is analyzed

A let analyzes its definition more than once (Statics.re:2023-2248). It first types its pattern, then runs a recursion probe: a full analysis of the definition in the pattern's context, map thrown away (Statics.re:2070). Whether the let is recursive is decided by shape alone: one bound variable and one function of arrow-like type (Statics.re:2024-2039, Statics.re:2076). If not, one real pass analyzes the definition in the outer context (Statics.re:2079). If so, two more passes are thrown away and a final one runs with the name in scope (Statics.re:2090-2122). The body follows, then the pattern again with the body's co-context, for unused-variable warnings (Statics.re:2152-2155). Last, the let builds its elaboration: the definition aligned to the pattern's labels and given the function's name, or, when the definition uses its own name, wrapped in a fixpoint, FixF (Statics.re:2172-2230).

So on dev every let analyzes a definition that is not a function twice, and a function four times, and these multiply with nesting. #2603 (a let is analyzed once unless it refers to itself), open, skips the probe for a definition that is not a function, and keeps the probe as the final analysis for a function that neither uses nor shadows its own name (Statics.re:2070-2089^{2603 head}, Statics.re:2113-2162^{2603 head}).

Modules: a module binding is a let

On dev a module is "a syntactic gloss over labeled tuples" (modules.md:5). A module literal { … } is lowered to a chain of lets and type aliases ending in a labeled tuple of its exported names (ModuleHelpers.re:286-337, ModuleHelpers.re:162-171) and analyzed as that (Statics.re:2693-2724). A signature is a type that desugar_sig turns into a labeled product, dropping its type items (Typ.re:615-657). Andrew Blinn built this module system and the module keyword in February 2026 (b0735de6d6 to 131f508825).

module M = def in body, step by step

module M = def in body is a ModuleExp, and it has no typing rule of its own. Its case on dev (Statics.re:2725-2772) does seven things, Figure 8:

1. Records the name's cursor info, an InfoMPat (Statics.re:2728-2735).
2. Turns the name pattern into an ordinary pattern, desugaring a signature annotation to a labeled product (ModuleHelpers.re:51-60).
3. Builds Let(pat, def, body) and gives it the ModuleExp's own id (Statics.re:2736-2741).
4. Analyzes that let (Statics.re:2742): the probe and real pass over def, the body, and the pattern, whose record overwrites the name's InfoMPat.
5. Changes the class in the let's record to ModuleExp (Statics.re:2743-2756), which step 7 overwrites anyway.
6. Analyzes def again, directly, against the signature or nothing, to get def_elab_direct (Statics.re:2757-2762). This pass's records overwrite the let's for every node inside def.
7. Builds the binding's elaboration with moduleexp_elab and adds the ModuleExp's record (Statics.re:2763-2772).

What moduleexp_elab builds, and what it drops

moduleexp_elab takes the let's elaboration and swaps its definition for def_elab_direct, and strips the signature from the pattern (ModuleHelpers.re:447-456, ModuleHelpers.re:364-371). That drops everything the let put around the definition: the label alignment, the function's name (Exp.re:544-551) and a fixpoint. The alignment is the one that matters on dev. Against a one-member signature, alignment would wrap a module's let-chain as (x = whole module) (LabeledTupleHelpers.re:49-75), and dev's test module M : { let x : Int } = { let x = 42 } in M.x gives 42 only because of the swap (Test_Evaluator_Modules.re:123-129). Stripping the signature means a module is not sealed at run time on dev: its value keeps every member.

How members enter the context

The name enters the body's context twice (Figure 10). As a value, the pattern binds a variable whose type is the module's labeled product (Statics.re:3164-3193). As a type, the let adds an alias under the module's name for its type members (Statics.re:2124-2151). A capitalized M parses as a constructor, and the Constructor case turns it into the variable when a variable is its newest binding (Statics.re:1561-1597). M.x is then a labeled-tuple projection (Statics.re:1278-1420; at run time Transition.re:1024-1058), and M.T a type projection through the alias (Typ.re:481-500).

Modules II

Alexander Bandukwala's Modules II stack replaces "modules are labeled tuples" with modules of their own: #2493 (part 1: first-class signature types and module values), #2494 (part 2: sealing at explicit coercion sites) and #2495 (part 3: abstract type members, sealing, path types), then parts 4 to 9, #2498, #2500, #2501, #2503, #2508 and #2510, the last of them the standard library as modules. A signature stays a signature type, a module literal elaborates to a module value, and a binder's signature seals the value at run time. Two things on his stack touch #2651's code. Parts 2 to 9 keep the direct pass, now with ~coercible=true (Statics.re:2833-2834^{part 2}, Statics.re:2973-2974^{part 9}), and their moduleexp_elab keeps the signature, because it is what seals (ModuleHelpers.re:617-627^{part 2}). His docs already say a module binding "elaborates to that Let" (modules.md:496-497^{part 9}). Questions 2 and 4 ask what that means for #2651.

The pull request, drawn

#2651 is four commits by Matthew Hammer, +54 and −5 lines in three files: e3013b0360 reads the definition's elaboration back, and 29c08fd8fa brings back the error for a definition that names its own module and adds two tests. Two more, pushed during the review at Matthew's word in answer to Alexander's comments (on the code comments, on the test's name), change only comments and a test's name: fa3eef62ce rewrites the comments, one per binding, and b5a3e1d90a renames the evaluator test. This report reads the code at 29c08fd8fa; at fa3eef62ce the same code sits at names_itself (Statics.re:2762-2766^fa3eef62ce), the read-back (Statics.re:2773-2778^fa3eef62ce), the fallback (Statics.re:2779-2786^fa3eef62ce) and the call to moduleexp_elab (Statics.re:2788-2789^fa3eef62ce). It is part of #2609 (Performance Challenges (Fall 2026)), finding 7, statics re-analyzing whole subterms, the same kind of problem as #2603.

The idea in one sentence: the let already recorded the definition's elaboration at the definition's id, before wrapping it, so the ModuleExp case can look it up instead of analyzing the whole definition again (Figure 11). The lookup is safe because the map is passed along explicitly and started empty for this run (Statics.re:4354-4362), and because passes that throw their map away never reach it: the record found is the one the let's real pass wrote in this very call.

The code, before and after

(* Statics.re:2757-2762 at dev *)
let def_ana =
  switch (pat.term) {
  | Asc(_, typ) => typ
  | _ => syn
  };
let (_, def_elab_direct, m) = go(~ana=def_ana, def, m);

(* Statics.re:2770-2789 at 29c08fd8fa, comments cut *)
let names_itself =
  switch (expanded_elab.term) {
  | Let(_, {term: FixF(_), _}, _) => true
  | _ => false
  };
let (def_elab_direct, m) =
  switch (Id.Map.find_opt(Exp.rep_id(def), m)) {
  | Some(Info.InfoExp({elab_term, _})) when !names_itself =>
    (elab_term, m)
  | _ =>
    let def_ana = ... ;                (* as on dev *)
    let (_, elab, m) = go(~ana=def_ana, def, m);
    (elab, m);
  };

Both feed the same call, ModuleHelpers.moduleexp_elab(~def_elab_direct, expanded_elab) (Statics.re:2763-2764; Statics.re:2790-2791^PR). At 29c08fd8fa the PR's comment said the read-back works because "add records exactly the elab_term it returns" (Statics.re:2757-2763^PR). That is true of add (Statics.re:268) but not of one path of the walk, the one-member-signature lift (below). Alexander pointed this out on the PR (his comment), and fa3eef62ce corrected the comment: it now says that under singleton-label lifting (autolabel_singleton_tuple) the info holds the inner elaboration, not the lifted term (Statics.re:2767-2772^fa3eef62ce). He also asked for one comment per binding, saying what its value is rather than the PR's history, and the same for the tests' comments; fa3eef62ce does both (Matthew's reply).

The second commit: a definition that names its own module

The first commit lost an error. module F = fun x -> F(x) in 1 is one variable bound to one function, so the let takes its recursive path and analyzes the definition with F in scope: no error. On dev the direct pass then analyzed it again in the outer context, where F is not a variable, and marked it a free constructor (Statics.re:1598-1606, ConstructorStaticsHelpers.re:61-64), overwriting the let's records. With the read-back, nothing overwrote them, so the error was gone; the correctness review in ^report(21) found it by running both commits.

29c08fd8fa adds names_itself: if the let's elaboration is Let(_, FixF(_), _), the let saw the definition use its own name, and the direct pass runs as before (Statics.re:2764-2774^PR). The fixpoint is the signal because the let removes the name from the co-context of the definition's record (Statics.re:2216-2228), so the record itself cannot show the self-reference. A test pins the error (Test_Statics_Modules.re:406-413^PR).

Run with the command-line tool, the program reports "Constructor is not defined" at the inner F (1:21) and runs to 1, at dev and at 29c08fd8fa alike; so does the same definition under a signature, module F : Int -> Int = fun x -> F(x) in 1 (at 1:34), which takes the fallback's other arm (the runs).

Found in review: the guard also matches a fixpoint the user wrote. Alexander found on #2651 (his comment) that module m = fix f -> fun x -> … f(x - 1) in m(3) elaborates to Let(_, FixF(…), _) too, because fix itself elaborates to a FixF. So the read-back is skipped and the definition is analyzed a third time, after the let's recursion probe and its own pass. On Modules II part 1 with #2651 merged, a temporary print in that match fired for every module … = fix … he tried (four programs), and not for a fix inside a module body. The results match dev, and only the speed-up is lost, but the check does not test what names_itself claims to. Telling the two apart by shape is hard: skipping whenever the definition is a fix would also skip module m = fix g -> fun x -> … m(x - 1), which, as he read it, gets its unbound-m error from the fallback. (Building the follow-up found that on #2651 the let's own analysis already reports that m as unbound: a FixF has no function count, since Exp.get_num_of_functions returns None for it, so the let is not recursive there, and the fallback then reports the same mark again, at the same id. With names_itself made to skip a fix, the error is still reported; what the skip keeps is the recursion probe, two analyses per module instead of one.) So, he concludes, the signal belongs in the let analysis itself: an argument that makes a module binding non-recursive (his suggestion in question 3), with no shape check and no fallback, and fix still the way a module binds a recursive function. It can be a follow-up, to keep #2651 small. It also depends on the answer to the question he asked on the PR (his comment; For Cyrus): if binding a module to a function becomes a static error, neither a self-naming function nor a module … = fix … can reach this code, and names_itself could go. Matthew agreed (his reply) and chose a follow-up: the draft #2717 (Statics: a module binding is a non-recursive let), opened on 2026-10-21 at 20:31Z against dev, on #2651's head b5a3e1d90a. It does not wait on that question: with it a module's definition is analyzed once whatever the definition is, apart from the one exception below.

The follow-up, #2717. In Statics.re, uexp_to_info_map takes a new argument, ~check_rec, true by default. It applies only to the term it is called on, so a let inside the definition or in the body is still recursive as usual. With it false, the let runs no recursion probe and has no recursive branch: it analyzes the definition once, in the outer context, where the bound name is not in scope, so the let itself reports a self-reference, and it never wraps the definition in a FixF. The ModuleExp case passes it false to the let it expands to, and the singleton-label pre-pass passes it along. That removes names_itself and its fallback; the definition's elaboration is still read back from the let's record, as on #2651. Counted from the let rule, #2651 analyzes a module's definition four times when it is a function that does not name the module, five when it does, three for a fix and two for anything else; #2717 analyzes it once. The one exception is not new: a module binding checked against a one-label product type such as (a = Int) costs three analyses, through the pre-pass. One statics result changes, for a definition that uses the name it shadows: in module F = fun (x : Int) -> x > 0 in module F = fun x -> F(x) in F(1) + 1 the inner F is now the outer module, so F(1) is a Bool and + 1 is an error, which agrees with the evaluator (both builds run it to true + 1). A module item inside braces is still lowered to a recursive let, as on dev. Its tests, and what it was measured to cost, are in What next.

What it costs, by shape and by nesting

So on today's dev #2651 takes a module literal's definition from three analyses to two; the third is the let's recursion probe, which #2603 removes. The PR's title, "once, not twice", counts only the ModuleExp case's own extra pass; it is exact for the whole binding once both PRs are in. Inside the definition, every member is itself a let and pays the let's own count again.

Nesting multiplies, but only one kind of nesting goes through this case. A module … in inside another module binding's definition pays the binding's factor at every level: 3^depth analyses of the innermost definition on dev, 2^depth with #2651, one with #2603 as well. A module Inner = { … } item inside braces is lowered to a plain let (ModuleHelpers.re:300-304), so it pays only the let's factor, 2 per level on dev, which #2603 removes and #2651 does not touch. Dev's only module program, hazel-programs/docs/reference/modules.hz, nests by items: module Outer = { module Inner = { … } } in (modules.hz:64-69).

Measured, by the PR (not in this report). On dev the effect is within the noise: on an 800-function module made up for timing, statics was about 0.13 s of 6 s, and whole-command times overlapped (6.06 and 6.74 s before, 5.26 and 6.05 s after, two runs each). On the livelits branch #2635 (livelits × modular editors), where a module holds the livelit definitions, a profile of the Shirt and Pants slide put 1.79 s of its 4.2 s of statics in the second pass, and the command line's statics went from 6.7 s to 4.3 s, against 4.1 s for the same slide with the module flattened into top-level lets (two runs each, within 0.3 s; #2609, finding 7). That branch also carries #2603's change (as b9e7561323) and per-definition statics, so these are not dev's numbers. ^report(17) and ^report(1) list these numbers too.

What a reviewer checks

Matthew has tested #2651's behaviour; what a review adds is the argument for why the result is the same, and where it is not. The table gives each check, what reading the code found, and where. The earlier reviews of this PR are ^report(17) (merge plan: wave 1, small and independent) and ^report(21) (a draft, not yet published; correctness, which found and confirmed by running both corners the second commit settles).

Six programs, run with the command-line tool

To check the corners by running them, not only by reading, the command-line tool was built at dev 962a7cb009 and at #2651's 29c08fd8fa, and each program below was run and analyzed with it (./hazel run and ./hazel analyze). The PR's later commits, fa3eef62ce and b5a3e1d90a, change only comments and a test's name. The first row was found by reading the code, while checking question 1, and this run confirms it (Matthew's comment on #2651 gave the same). Only the first two rows differ between the commits, both through the one-member lift (below), and Alexander accepted both results.

The one corner where the result changes

A one-member signature desugars to a one-field labeled product. When a definition's own type is something else, the walk lifts it into that product: autolabel_singleton_tuple analyzes a fresh copy against the field's type, records that bare analysis at the definition's ids, and returns (x = …) around the raw, unelaborated source (Statics.re:310-358; it runs from Statics.re:2778-2791). Dev's direct pass handed what it returns to moduleexp_elab; #2651 reads what it records. For the extra-member module that turns M.x from the module's raw source into 1, which ^report(21) confirmed by running both commits. Alexander's answer: dev's result is a bug from the auto-labelling of one-member tuples, and 1 (or stuck) is right; the PR's test pins the fix.

The same path with a plain value is the one result found where dev gives a value and #2651 does not: module M : { let x : Int } = 5 in M.x has no static error on dev and gives 5; with #2651, M is bound to 5 and M.x projects a label out of an Int, which is indeterminate (Unboxing.re:184-217, Transition.re:1024-1087). Written with let instead of module, the same program still gives 5, because the let keeps the lift (Statics.re:2182-2187). Run with the command-line tool at dev and at 29c08fd8fa, it gives 5 on dev and 5 .x, stuck, with #2651, and no static errors either way (the runs; Matthew's comment on #2651). Alexander accepted the stuck result (his comment, option 2 of question 1): a bare value under a module signature should be stuck and a static error. Modules II part 1 already does both, with or without #2651: signatures are Typ.Sig there, so the lift never runs, and the program reports "Expecting type { let x:Int } but got inconsistent type Int" and evaluates to (5:({ let x:Int })).x. On dev the missing error is temporary, so #2651 needs no special case. Matthew decided that the test for this program goes on part 1, not in #2651 (his reply). Whether binding a module to a non-module, a function for instance, should be a static error is a question for Cyrus (below). It does not hold up the merge; what is left is to name it in the PR's description (What next).

Where #2651 sits

Of the open #2609 PRs, #2651 is the smallest that touches statics, and it touches only the ModuleExp case. #2603 (a let analyzed once) merges cleanly with it, and together they bring a module binding to one analysis; #2689 (statics analyzes each expression within a budget), a draft, pins that count, but merged #2651's first commit, e3013b0360, without the guard. #2675 (reuse around a recursive let) changes the let's co-context under a fixpoint, which names_itself does not read (question 3's co-context option does). #2661 (types get a hash) and #2681 (a value known to have a type is not walked again for it) touch other parts of statics and are independent. The livelits branches #2635 and #2597 (user-defined livelits) carry the read-back without the guard. Modules II keeps the direct pass with ~coercible=true, hence the one-line conflict.

Questions for Alexander

Alexander, this section stands on its own. #2651 (Statics: a module binding analyzes its definition once, not twice) stops the ModuleExp case in statics from analyzing a module's definition a second time: module M = def in body is checked as let M = def in body, and the case now reads the definition's elaboration back from the record that let wrote, keeping the second analysis only as a fallback (the picture is The pull request, drawn). You and Matthew reviewed it on 2026-10-21, and your answers are below, paraphrased: from that review and in conversation (relayed by Matthew), and since then from your comments on #2651, each linked. All five are answered, question 3 for now, and none holds up the merge.

From here on, please answer on #2651 itself, as comments there, rather than here. Where they stand: 1 (the one-member signature lift): answered, its bare-value half on the PR (option 2); 2 (the merge order against Modules II): answered; 3 (whether module bindings are recursive): answered for now, for Cyrus, with your let-analysis argument now the draft follow-up #2717 (Statics: a module binding is a non-recursive let); 4 (whether Modules II still needs def_elab_direct): answered; 5 (which module behaviours to pin as tests): answered on the PR. None holds up the merge.

For Cyrus

Three design questions came out of the review that are Cyrus's to decide; Alexander raised the second and third, and has asked a form of the second on #2651 itself. None holds up #2651.

1. Should module bindings be recursive? Today module F = … as an expression is not (a self-reference is an error, and #2651 keeps it one), while a module F = … item inside { … } is lowered to a plain let and, by our reading, is. Alexander: for now it is fine for modules not to be recursive by default, since recursion has a number of known correctness problems (question 3).
2. Should binding a module to something that is not a module be a static error? module F = fun x -> 1 in F(3) is accepted today. With a signature the case is settled: module M : { let x : Int } = 5 in M.x, accepted on dev, is already a static error, and stuck, on Modules II part 1, which Alexander accepted as the intended behaviour, dev's missing error being temporary (question 1). If a module bound to a function becomes an error too, neither a self-naming function nor a module … = fix … can reach #2651's guard, and names_itself could go (the guard). Alexander asked a form of this on #2651 on 2026-10-21 at 18:25Z, in a review comment on its self-naming test (Test_Statics_Modules.re:411): "should this be an error defining a module to be a function?" (his comment). He addressed it to @disconcision, Andrew Blinn, who wrote the module keyword (b0735de6d6 to 131f508825 are by disconcision, the account Andrew opened #2469 (Modular editors) from), so it can be answered there, by Andrew or Cyrus.
3. What should the module keyword add over let? Alexander had favoured plain let for module definitions; Cyrus wanted the keyword to do more. Today a module binding is checked as a let that is not recursive (Modules). By Alexander's reading (his agent's, in conversation, relayed by Matthew), which matches ours, the keyword makes the binding non-recursive and allows a capitalized name, and is otherwise a let; #2651 keeps both.

What next

1. Merge #2651: CI is green at its head. Every question for Alexander is answered, and none holds up the merge; on question 2 he sees no conflict with Modules II. CI passed at fa3eef62ce (run 39655086864, Fast checks and Full tests, 18:59Z); at b5a3e1d90a, which only renames a test, they passed too (run 39657741479, Full tests at 19:26Z). Merge into dev now, and add ~coercible=true to the fallback when Alexander's stack next rebases (parts 2 to 9).
2. Name module M : { let x : Int } = 5 in M.x in #2651's description as a known change, and pin it on Modules II part 1. 5 on dev, a stuck 5 .x with #2651, no static errors either way (the runs). Alexander accepted the stuck result (his comment): stuck and a static error is right, and part 1 already gives both. Matthew decided its test goes on part 1, not in #2651 (his reply), where it can assert both the stuck term and the error.
3. Tighten the tests: #2717 has them. The follow-up (below) adds module F = fun x -> x + 1 in F(2), expecting 3 (as it gives when run), and the self-naming module under a signature, and pins both self-naming tests to the FreeConstructor mark on F's use. On #2651 alone they would cover the read-back after the let's recursive path and the fallback's other arm (it reports its error when run).
4. Finish the comment fix: fa3eef62ce already took out "add records exactly the elab_term it returns", which holds for add but not for the one-member lift, and the new comment names the lift (Statics.re:2767-2772^fa3eef62ce). It still presents the no-info arm as a real case ("or when no info was recorded") rather than calling it defensive.
5. Review the let-analysis argument, now the draft follow-up #2717 (Statics: a module binding is a non-recursive let). Alexander's suggestion, agreed on #2651 (his comment; Matthew's reply), and opened as a draft on 2026-10-21 at 20:31Z, against dev. It depends on #2651: its branch, module-let-nonrec, is three commits on #2651's head b5a3e1d90a (a0a781effe, e3dc50cc0b and ea23dd4930), so until #2651 merges its diff shows #2651's commits too. It does not wait on Cyrus: if binding a module to a function becomes an error, a module's definition is still analyzed once.
   • What it does: a module binding is a non-recursive let, by an argument to the let; names_itself and its fallback are gone, and a module's definition is analyzed once, where #2651 analyzes it two to five times by its shape (the guard).
   • Tests, passing locally at ea23dd4930: Statics.Modules 86, which is 75 on #2651 plus 11 new, the self-naming test now pinned to its one mark; Evaluator.Modules 24, 18 plus 6 new; Statics.Fixpoint (1), Evaluator.Fixpoints (10), Statics.Let (2), Evaluator.Let (5), Elaboration tests (39) and Evaluator.Incremental (41). The full suite was not run locally; CI was running at its head when this page was finished (run 39671006602).
   • Alexander's two fix programs are tests. module m = fix f -> fun n -> if n == 0 then 1 else n * f(n - 1) in m(3) runs to 6 with no errors, and its definition is analyzed once. module m = fix g -> fun n -> if n == 0 then 0 else m(n - 1) in m(3) reports "Variable m is not bound" at the inner m (1:52), exactly one mark, Free("m"), and stops at the free m (m(2):Int). Both statics tests pass on #2651 too, which already gives both answers (the guard); what tells the two builds apart is the cost.
   • The cost, measured on the tests' chains of nested modules, module F0 = fun x : Int -> module F1 = … in F1(x) in F0(1) and the same with each definition a fix, where depth n is n + 1 modules: wall times of the command-line tool's analyze, startup included, two runs each; startup alone is 1.27 to 1.42 s on both builds. At depth 9 the function chain took 31.04 and 29.59 s on #2651 and 1.43 and 1.45 s with #2717; at depth 10 the fix chain took 16.58 and 15.71 s, and 1.31 and 1.46 s. From depth 7 on, above startup, #2651's function chain grows about 3.8 to 3.9 times per level, which fits four analyses per module, and its fix chain 2.6 to 3.3 times, which fits three. With #2717 both chains take 1.25 to 1.55 s at every depth measured, 4 to 12: within 0.15 s of startup's range, and not growing with depth. Two runs per point is not a benchmark, but the differences on #2651 are far above that spread. The tests also bound the cost, timed with Sys.time, on the same chains; their names give the depth, so "twelve nested" is thirteen modules: the fix chain at depth 12 must check in under 0.5 s, and took 0.0 s with #2717, 197.2 s with #2651's statics, and 1.7 s with names_itself made to skip a fix (the probe alone, which still fails the bound); the function chain at depth 9 must check in under 5 s, and took 0.0 s with #2717 and 44.4 s with the module's let made recursive again; the function chain at depth 7, at one-label types, must check in under 10 s, and took 0.7 to 0.8 s with #2717 and 50.1 s without the flag carried through the pre-pass.
   • Left open: whether a module item inside braces should be non-recursive too. It is still a recursive let, and tests pin that split as it is, for Alexander, Matthew and Cyrus to decide. Its merges with Modules II part 2 (#2494, two conflicts in Statics.re) and with #2603 (one) have resolutions recorded in e3dc50cc0b's message, which parse but have not been built.
6. Take the three design questions to Cyrus (For Cyrus): recursive modules (and the item form inside braces), modules bound to non-modules as a static error (asked on #2651 too, Alexander's comment), and what the module keyword should add over let. Alongside them: Alexander says there are a number of other issues with modules, unrelated to this PR's finding, and expects to clean some of them up on the Modules II stack after its first PR, part 1 (#2493), merges (in conversation, relayed by Matthew).
7. Port the guard (29c08fd8fa) to Matthew's livelits branches #2635 and #2597, and redo #2689's merge, which took e3013b0360.
8. File dev issues for the lift (Statics.re:329-334): it returns raw source, so any term that needs elaboration, analyzed against a one-member labeled product it does not match, reaches the evaluator unelaborated; and it records error infos at fresh ids with no source position, a dev issue of its own, Alexander notes, not for #2651 (his comment; the checks).

How this was put together

• What was read: dev at 962a7cb009 and #2651 at 29c08fd8fa (first commit e3013b0360, merge base 34f9605ddf), read on 2026-10-21 after fetching both; 29c08fd8fa was the PR's head until fa3eef62ce and b5a3e1d90a, pushed during the review, which change only comments and one test's name. For Modules II, the heads of parts 1, 2, 3 and 9 (c4bae23739, be90bf4b21, 111775a60c, b02ce6dab5); #2603 at 4aa493c05a; #2469 at b5eaa33031. Every file:line in this page links to GitHub at the full commit it names, and each range was checked to exist there.
• Six readers of the code, one subsystem each: the edit-to-statics pipeline, the statics core, modules, elaboration to evaluation, the PR itself, and its performance context. They read only. Their notes are in 024/data/research-notes.json.
• Six programs, run: afterwards the command-line tool was built at dev 962a7cb009 and at #2651's 29c08fd8fa, and each program in the runs was run and analyzed with it (./hazel run and ./hazel analyze). The first was found by reading the code, while checking question 1, and the run confirmed it. Nothing was timed for this report.
• The questions were drafted from two lenses, what a reviewer of #2651 needs and what only the Modules II owner can say, and each was checked for its premise (does the code say what it assumes, line by line at the named commits) and its need (does anything on record already answer it: the PR's conversation, the Modules II descriptions, the docs, the tests). Their checks are in 024/data/questions.json. None was found already answered when they were drafted; Alexander then answered four in the review and in conversation, questions 2 and 4 as recorded on this report's interim page, published during the review, and the fifth was settled on #2651.
• Alexander's answers are from his review with Matthew on 2026-10-21 and from conversation that day, relayed by Matthew and paraphrased here; from then on he answered on #2651, and those answers are paraphrased with a link to each comment. The PR's comments, reviews and checks were read from GitHub at 19:34Z that day, and #2651's again at 20:34Z, with nothing new but #2717's cross-reference.
• The follow-up, #2717: what it does, its tests and their results, and its timings are from its description and from the notes of the run that built it, at ea23dd4930. Its new test files were read; its code was not read for this report, and its tests were not run again here.
• Finished on 2026-10-21 at 14:41 MDT, once the follow-up #2717 was open. Later changes come as dated updates.
• A fact-check re-derived each line number at the commit its link names; dev had moved since some notes were written. The figures were rendered to images with ffmpeg's SVG reader, in the light and dark colours, and looked at; the page was not opened in a browser.
• Not confirmed: the editor's context inside a function-valued module and the tuple-literal case were traced in the code, not run. The six programs in the runs are confirmed by running them at dev 962a7cb009 and at 29c08fd8fa, the bare-value program's stuck 5 .x among them (also in Matthew's comment on #2651). The analysis counts were counted from the code, not measured. The timings quoted are #2651's own and #2609's finding 7 (two runs each), and #2717's: the command-line tool's times on nested chains, two runs per depth, and its tests' own time bounds, timed with Sys.time at its head and in throwaway builds; this report timed nothing. The two corners ^report(21) found, the extra-member module and the self-naming definition, were confirmed there by running the command-line tool at e3013b0360 and at dev's 34f9605ddf.
• Credit: #2651 and #2603 are Matthew Hammer's, made with Claude. Dev's module system and the module keyword are Andrew Blinn's; Modules II is Alexander Bandukwala's; the statics without a separate elaborator, Mode or Self is Matt Keenan's; DefStatics is Andrew Blinn's, in #2469.
• The page was first made by 024/drivers/gen024.py (figures in figs.py, questions in questions.py); since then it has been edited directly as the review went on, so rerunning the generator would undo those edits.
• The numbers, for programs too: every table in this report, and what its numbers measure, is also in this page as JSON, in its <script type="application/json" id="report-data"> element, so a reader or an agent that fetches the page alone has the dataset. The same, with any raw files that survive, is in this report's data/ folder, next to the page: meta.json, questions.json, tables.json and research-notes.json.