From e414144d48ef2b5f68f43898aeac51b4f89bf0ec Mon Sep 17 00:00:00 2001
From: Brummel <mould@mycelium.de>
Date: Sun, 10 May 2026 02:30:34 +0200
Subject: [PATCH] iter env-unify: journal entry, milestone close

---
 docs/JOURNAL.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md
index cadfa71..bcbdbea 100644
--- a/docs/JOURNAL.md
+++ b/docs/JOURNAL.md
@@ -12050,3 +12050,70 @@ post-22 Prelude / operator-routing / primitive-name-set
 consolidation. It is not gating any user-facing feature, but it is
 where the next "mysterious mono failure" will come from if not
 addressed.
+
+## 2026-05-10 — Iteration env-construction unify
+
+Single-iteration milestone retiring the structural drift between
+`check_in_workspace` and `mono::build_workspace_env`. Three
+consecutive bug fixes (`5c5180f` env.types/ctor_index, `13b36cc`
+env.globals, `a9c685d` env.imports) had been patches at three
+different fields of the same drift class. The unify replaces both
+construction paths with a single source-of-truth helper
+`build_check_env(ws) -> Env` covering the workspace-flat fields
+(builtins, module_globals + class_methods, module_types,
+module_imports, class_superclasses, workspace_registry, plus
+workspace-flat types/ctor_index for the mono pass). Per-call
+overlay (`current_module`, `globals`, `imports`, `rigid_vars`, plus
+per-module `types`/`ctor_index` for `Pattern::Ctor`'s local-first
+resolution) stays at the call sites where it semantically belongs.
+
+After this iteration, when `synth` learns to read a new
+workspace-flat `Env` field, exactly one construction site needs
+the seeding edit. A new `crates/ailang-check/tests/env_construction_pin.rs`
+integration test serves as the tripwire: any future divergence
+between the helper and a frozen reproduction of the inline seeding
+fails the test before the bug ships.
+
+Design corrections during execution (recorded for the audit
+artifact):
+
+- The pin test originally asserted `env.globals.is_empty()` on the
+  helper output, treating `globals` as pure overlay. `builtins::install`
+  populates BOTH `globals` (with operator entries `+`, `-`, `==`,
+  `not`, `__unreachable__`) AND `effect_ops` from one call, so
+  `globals` is partially workspace-flat (operators) and partially
+  overlay (per-module fns). Pin test fixed to key-set equality.
+- The original spec listed `types` and `ctor_index` as workspace-flat
+  fields. That was true for `mono::build_workspace_env` (since
+  `5c5180f`) but NOT for the pre-refactor `check_in_workspace`,
+  which seeded them per-module — `Pattern::Ctor`'s
+  local-first / imports-fallback logic depends on the per-module
+  shape to surface the qualified `module.Type` name on cross-module
+  pattern matches. Resolution: `build_check_env` keeps the
+  workspace-flat seed (mono needs it), and `check_in_workspace`'s
+  per-module overlay clears and rebuilds these two fields per-module
+  with the original in-band fail-fast `DuplicateType` /
+  `DuplicateCtor` diagnostics.
+
+Tasks (commit subjects):
+
+- `test: red for env-construction drift-shape pin` (Task 1)
+- `test: clean red signal for env-construction pin (inline module_types)` (Task 1 fixup)
+- `test: fix env-pin globals assertion (builtins seed operators workspace-flat)` (mid-Task-2 correction)
+- `iter env-unify.1: extract build_check_env, mono uses it` (Task 2)
+- `iter env-unify.1: rustdoc fixup (re-anchor check_in_workspace doc, drop transient task tag)` (Task 2 fixup)
+- `iter env-unify.2: check_in_workspace consumes build_check_env` (Task 3)
+- `iter env-unify.2: drop redundant overlay comments` (Task 3 fixup)
+
+Spec: `docs/specs/2026-05-10-env-construction-unify.md`. Plan:
+`docs/plans/2026-05-10-env-construction-unify.md`. Tests: pin test
+green; the three RED tests (`typeclass_22c`, `mono_recursive_fn`,
+`mono_xmod_qualified_ref`) remain green; `cargo test --workspace`
+green at 345 tests; bench gates 0/0/0 (`bench/check.py` 0 regressed +
+4 improved beyond tolerance, `bench/compile_check.py` 0 regressed,
+`bench/cross_lang.py` 0 regressed).
+
+Known debt: none introduced. Out-of-scope items from the spec
+(pipeline-topology changes, per-module overlay refactor,
+primitive-name-set consolidation, new env fields) remain queued
+for separate milestones.