AILang/docs/plans/0007-env-construction-unify.md

Env-construction unify — Implementation Plan

Parent spec: docs/specs/0003-env-construction-unify.md

For agentic workers: REQUIRED SUB-SKILL: use skills/implement to run this plan. Steps use - [ ] checkboxes for tracking.

Goal: Eliminate structural drift between check_in_workspace and mono::build_workspace_env by extracting a single shared build_check_env(ws) -> Env helper that both paths consume.

Architecture: Introduce pub fn build_check_env(ws: &Workspace) -> Env in crates/ailang-check/src/lib.rs covering every workspace-flat seeding step (effect_ops, types, ctor_index, module_globals, module_types, module_imports, class_methods, class_superclasses, workspace_registry). Both call sites (check_in_workspace and mono::build_workspace_env) become thin consumers; per-module overlay fields (current_module, globals, imports, rigid_vars) stay at the call sites because they depend on call context.

Tech Stack: crates/ailang-check (lib.rs, mono.rs, tests/), indexmap, BTreeMap / BTreeSet, the existing Workspace / Module / Def types from ailang-core.

Files this plan creates or modifies:

• Create: crates/ailang-check/tests/env_construction_pin.rs — drift-shape integration test that asserts build_check_env(&ws) agrees with the pre-refactor inline seeding on every workspace-flat field.
• Modify: crates/ailang-check/src/lib.rs — add pub fn build_check_env(ws: &Workspace) -> Env (workspace-flat source-of-truth); refactor check_in_workspace (lines 1088-1202) to call it and drop the duplicated inline seeding while keeping per-module overlay logic.
• Modify: crates/ailang-check/src/mono.rs — reduce build_workspace_env (lines 367-446) to a one-line wrapper around build_check_env; delete the drift-risk comment (lines 368-370).
• Modify: docs/JOURNAL.md — append milestone-close entry.

---

Task 1: RED — drift-shape pin test

The pin test is the tripwire that protects the unify against future drift. Per the plan-skill TDD discipline (and ailang-implementer's independent TDD layer), it lands RED first: it fails to compile because ailang_check::build_check_env does not yet exist.

Files:

• Create: crates/ailang-check/tests/env_construction_pin.rs

• Step 1: Write the integration test

Write the file crates/ailang-check/tests/env_construction_pin.rs:

//! Drift-shape pin for env construction (env-construction unify
//! milestone). Asserts that `build_check_env(&ws)` agrees with an
//! in-test reproduction of the pre-refactor inline seeding on every
//! workspace-flat field. Future-you adds a new workspace-flat env
//! field without updating `build_check_env` -> this test fails before
//! the bug ships.
//!
//! Fixture: a two-module workspace covering one `Def::Class`, one
//! `Def::Instance`, one user ADT, and one cross-module import (the
//! same shape that `test_mono_imports_*` use).

use ailang_check::{build_check_env, build_module_globals, build_module_types, Env};
use ailang_core::ast::Def;
use ailang_core::load_workspace;
use std::collections::BTreeMap;
use std::path::Path;

fn examples_dir() -> std::path::PathBuf {
    let manifest = env!("CARGO_MANIFEST_DIR");
    Path::new(manifest).parent().unwrap().parent().unwrap().join("examples")
}

/// In-test reproduction of the pre-refactor `check_in_workspace`
/// workspace-flat seeding (lib.rs as of commit a9c685d). Kept as a
/// frozen reference: any future divergence between this body and
/// `build_check_env` makes the assertion below fail.
fn build_env_inline_pre_refactor(ws: &ailang_core::workspace::Workspace) -> Env {
    let mut env = Env::default();
    ailang_check::builtins::install(&mut env);

    // env.types + env.ctor_index — workspace-flat from every Def::Type.
    for m in ws.modules.values() {
        for d in &m.defs {
            if let Def::Type(td) = d {
                for c in &td.ctors {
                    env.ctor_index.insert(
                        c.name.clone(),
                        ailang_check::CtorRef { type_name: td.name.clone() },
                    );
                }
                env.types.insert(td.name.clone(), td.clone());
            }
        }
    }

    // env.module_globals — per-module .fns projection.
    let mg = build_module_globals(ws).expect("build_module_globals");
    env.module_globals = mg
        .iter()
        .map(|(k, v)| (k.clone(), v.fns.clone()))
        .collect();

    // env.module_types — workspace-wide.
    env.module_types = build_module_types(ws);

    // env.module_imports — per-module alias map.
    for m in ws.modules.values() {
        let mut import_map: BTreeMap<String, String> = BTreeMap::new();
        for imp in &m.imports {
            let key = imp.alias.clone().unwrap_or_else(|| imp.module.clone());
            import_map.insert(key, imp.module.clone());
        }
        env.module_imports.insert(m.name.clone(), import_map);
    }

    // env.class_methods — workspace-merged from each module's
    // ModuleGlobals.class_methods.
    for g in mg.values() {
        for (n, e) in &g.class_methods {
            env.class_methods.insert(n.clone(), e.clone());
        }
    }

    // env.class_superclasses — walk every module's Def::Class.
    for m in ws.modules.values() {
        for d in &m.defs {
            if let Def::Class(cd) = d {
                if let Some(sc) = &cd.superclass {
                    env.class_superclasses.insert(cd.name.clone(), sc.class.clone());
                }
            }
        }
    }

    // env.workspace_registry — clone of ws.registry.
    env.workspace_registry = ws.registry.clone();

    env
}

#[test]
fn build_check_env_matches_inline_seeding() {
    let entry = examples_dir().join("test_mono_imports_main.ail.json");
    let ws = load_workspace(&entry).expect("load test_mono_imports_main");

    let env_helper = build_check_env(&ws);
    let env_inline = build_env_inline_pre_refactor(&ws);

    // env.types — IndexMap<String, TypeDef>: compare key-set + name.
    assert_eq!(
        env_helper.types.keys().collect::<Vec<_>>(),
        env_inline.types.keys().collect::<Vec<_>>(),
        "env.types key-set differs"
    );
    for k in env_helper.types.keys() {
        assert_eq!(
            env_helper.types[k].name,
            env_inline.types[k].name,
            "env.types[{k}] type-def name differs"
        );
    }

    // env.ctor_index — IndexMap<String, CtorRef>: compare key-set +
    // type_name.
    assert_eq!(
        env_helper.ctor_index.keys().collect::<Vec<_>>(),
        env_inline.ctor_index.keys().collect::<Vec<_>>(),
        "env.ctor_index key-set differs"
    );
    for k in env_helper.ctor_index.keys() {
        assert_eq!(
            env_helper.ctor_index[k].type_name,
            env_inline.ctor_index[k].type_name,
            "env.ctor_index[{k}].type_name differs"
        );
    }

    // env.module_globals — BTreeMap<String, IndexMap<String, Type>>.
    assert_eq!(
        env_helper.module_globals.keys().collect::<Vec<_>>(),
        env_inline.module_globals.keys().collect::<Vec<_>>(),
        "env.module_globals key-set differs"
    );
    for k in env_helper.module_globals.keys() {
        assert_eq!(
            env_helper.module_globals[k].keys().collect::<Vec<_>>(),
            env_inline.module_globals[k].keys().collect::<Vec<_>>(),
            "env.module_globals[{k}] inner key-set differs"
        );
    }

    // env.module_types — same shape as module_globals.
    assert_eq!(
        env_helper.module_types.keys().collect::<Vec<_>>(),
        env_inline.module_types.keys().collect::<Vec<_>>(),
        "env.module_types key-set differs"
    );
    for k in env_helper.module_types.keys() {
        assert_eq!(
            env_helper.module_types[k].keys().collect::<Vec<_>>(),
            env_inline.module_types[k].keys().collect::<Vec<_>>(),
            "env.module_types[{k}] inner key-set differs"
        );
    }

    // env.module_imports — BTreeMap<String, BTreeMap<String, String>>:
    // direct equality.
    assert_eq!(
        env_helper.module_imports, env_inline.module_imports,
        "env.module_imports differs"
    );

    // env.class_methods — BTreeMap<String, ClassMethodEntry>:
    // compare key-set (entry shape has no PartialEq).
    assert_eq!(
        env_helper.class_methods.keys().collect::<Vec<_>>(),
        env_inline.class_methods.keys().collect::<Vec<_>>(),
        "env.class_methods key-set differs"
    );

    // env.class_superclasses — direct equality.
    assert_eq!(
        env_helper.class_superclasses, env_inline.class_superclasses,
        "env.class_superclasses differs"
    );

    // env.effect_ops — IndexMap<String, EffectOpSig>: compare key-set.
    assert_eq!(
        env_helper.effect_ops.keys().collect::<Vec<_>>(),
        env_inline.effect_ops.keys().collect::<Vec<_>>(),
        "env.effect_ops key-set differs"
    );

    // env.workspace_registry — entries key-set must match.
    assert_eq!(
        env_helper.workspace_registry.entries.keys().collect::<Vec<_>>(),
        env_inline.workspace_registry.entries.keys().collect::<Vec<_>>(),
        "env.workspace_registry.entries key-set differs"
    );

    // Per-call overlay fields must NOT be seeded by the helper.
    assert_eq!(env_helper.current_module, "", "current_module is overlay");
    assert!(env_helper.globals.is_empty(), "globals is overlay");
    assert!(env_helper.imports.is_empty(), "imports is overlay");
    assert!(env_helper.rigid_vars.is_empty(), "rigid_vars is overlay");
}

• Step 2: Run test to verify it fails (compile error, RED)

Run: cargo test --workspace -p ailang-check --test env_construction_pin 2>&1 | head -40 Expected: FAIL with error[E0432]: unresolved import \ailang_check::build_check_env`(or equivalent —build_check_env` does not yet exist as a public symbol).

• Step 3: Commit RED

git add crates/ailang-check/tests/env_construction_pin.rs
git commit -m "test: red for env-construction drift-shape pin"

---

Task 2: GREEN — add build_check_env + reduce mono::build_workspace_env to wrapper

Introduces the workspace-flat source-of-truth. After this task, the pin test from Task 1 goes green; the mono pass uses the helper; the drift-risk comment is gone. check_in_workspace is not yet refactored — its inline seeding lives alongside the helper for one commit (intentional intermediate state — both produce equivalent envs, which is exactly the property the pin test verifies).

Files:

• Modify: crates/ailang-check/src/lib.rs — add pub fn build_check_env(ws: &Workspace) -> Env near build_module_globals / build_module_types (around line 985, before check_in_workspace).

• Modify: crates/ailang-check/src/mono.rs:367-446 — replace body of build_workspace_env.

• Step 1a: Elevate build_module_types from pub(crate) to pub

In crates/ailang-check/src/lib.rs line 885, change pub(crate) fn build_module_types( to pub fn build_module_types(. Reason: the new crates/ailang-check/tests/env_construction_pin.rs (another crate) needs to call this helper to reproduce the pre-refactor seeding. build_module_globals is already pub; this elevation makes the two sibling helpers symmetric.

• Step 1b: Add build_check_env to lib.rs

Insert immediately before fn check_in_workspace (around line 1088). Place in the same mod scope as the existing build_module_globals and build_module_types so it can call them without re-export.

/// Build the workspace-flat `Env` shared by `check_in_workspace`
/// and `mono::build_workspace_env`. Populates every field whose
/// contents are derivable from `Workspace` alone — no
/// `current_module` overlay applied. Both call sites are thin
/// consumers: each clones this env and applies the per-call
/// overlay (`current_module`, `globals`, `imports`, `rigid_vars`)
/// at the call site.
///
/// Pre-condition: typecheck has succeeded for the workspace
/// (otherwise `build_module_globals` panics — same caller-contract
/// as the pre-refactor `mono::build_workspace_env`).
pub fn build_check_env(ws: &Workspace) -> Env {
    let mut env = Env::default();
    builtins::install(&mut env);

    // env.types + env.ctor_index — workspace-flat from every
    // module's Def::Type. Safe to flatten because `check_workspace`
    // has already accepted the workspace, so duplicate names
    // cannot occur. Mirrors the per-module loop in the pre-refactor
    // `check_in_workspace` (which fail-fast aborted on duplicates,
    // unreachable here).
    for m in ws.modules.values() {
        for d in &m.defs {
            if let Def::Type(td) = d {
                for c in &td.ctors {
                    env.ctor_index.insert(
                        c.name.clone(),
                        CtorRef { type_name: td.name.clone() },
                    );
                }
                env.types.insert(td.name.clone(), td.clone());
            }
        }
    }

    // env.module_globals + env.class_methods — built from
    // `build_module_globals(ws)`. The .fns projection feeds
    // `module_globals`; the .class_methods entries are merged
    // workspace-wide into `class_methods` (uniqueness enforced
    // earlier by `workspace::build_registry`'s
    // method-name-collision check).
    let mg = build_module_globals(ws)
        .expect("build_module_globals: pre-condition (typecheck succeeded) violated");
    env.module_globals = mg
        .iter()
        .map(|(k, v)| (k.clone(), v.fns.clone()))
        .collect();
    for g in mg.values() {
        for (n, e) in &g.class_methods {
            env.class_methods.insert(n.clone(), e.clone());
        }
    }

    // env.module_types — per-module ADT index.
    env.module_types = build_module_types(ws);

    // env.module_imports — per-module alias-or-name -> module-name.
    // Per-module because aliases collide across modules; sibling
    // shape to `module_globals`.
    for m in ws.modules.values() {
        let mut import_map: BTreeMap<String, String> = BTreeMap::new();
        for imp in &m.imports {
            let key = imp.alias.clone().unwrap_or_else(|| imp.module.clone());
            import_map.insert(key, imp.module.clone());
        }
        env.module_imports.insert(m.name.clone(), import_map);
    }

    // env.class_superclasses — walk every module's Def::Class.
    for m in ws.modules.values() {
        for d in &m.defs {
            if let Def::Class(cd) = d {
                if let Some(sc) = &cd.superclass {
                    env.class_superclasses.insert(cd.name.clone(), sc.class.clone());
                }
            }
        }
    }

    // env.workspace_registry — clone of ws.registry. Used by
    // `check_fn`'s concrete-residual no-instance check.
    env.workspace_registry = ws.registry.clone();

    env
}

• Step 2: Verify lib.rs builds

Run: cargo build --workspace -p ailang-check 2>&1 | tail -10 Expected: builds clean (no warnings about unused fn — build_check_env is pub; build_module_types is now pub and already had a workspace consumer in mono::build_workspace_env).

• Step 3: Replace mono::build_workspace_env body

In crates/ailang-check/src/mono.rs, replace lines 367-446 with:

/// Iter 22b.3 / 2026-05-10 unify: thin wrapper over
/// [`crate::build_check_env`]. The mono pass needs the same
/// workspace-flat `Env` shape as `check_in_workspace`, so both
/// share one source of truth. Per-fn entry points
/// (`collect_mono_targets`, `collect_residuals_ordered`) clone the
/// env and apply per-fn overlay (current_module, globals from
/// module_globals, imports from module_imports, rigid_vars).
pub fn build_workspace_env(ws: &Workspace) -> crate::Env {
    crate::build_check_env(ws)
}

The drift-risk comment on lines 368-370 is removed by this replacement (the new body has no such comment).

• Step 4: Verify mono.rs builds and the pin test passes

Run: cargo build --workspace 2>&1 | tail -10 Expected: builds clean. Any unused-import warning (e.g. Def, BTreeMap if no longer referenced in mono.rs) is fixed in this step by removing the import.

Run: cargo test --workspace -p ailang-check --test env_construction_pin 2>&1 | tail -15 Expected: PASS — build_check_env_matches_inline_seeding ... ok.

• Step 5: Verify the three RED-test regression suite stays green

Run: cargo test --workspace --test typeclass_22c --test mono_recursive_fn --test mono_xmod_qualified_ref 2>&1 | tail -20 Expected: PASS for all three (they exercise the mono pass through ail build, which now goes via the helper).

• Step 6: Commit GREEN

git add crates/ailang-check/src/lib.rs crates/ailang-check/src/mono.rs
git commit -m "iter env-unify.1: extract build_check_env, mono uses it"

---

Task 3: Refactor check_in_workspace to consume build_check_env

Drops the duplicated inline seeding from check_in_workspace. After this task, every workspace-flat field has exactly one construction site (build_check_env); check_in_workspace only does per-module overlay (current_module, globals, imports).

Files:

• Modify: crates/ailang-check/src/lib.rs:1088-1202 — check_in_workspace body.

• Step 1: Replace check_in_workspace body

Replace the body of check_in_workspace (lines 1088-1202 — keep the doc comment and signature, replace the body) with:

fn check_in_workspace(
    m: &Module,
    ws: &Workspace,
    module_globals: &BTreeMap<String, ModuleGlobals>,
) -> Vec<CheckError> {
    let mut env = build_check_env(ws);
    let mut errors: Vec<CheckError> = Vec::new();

    // Type-def setup phase — the workspace-flat `env.types` /
    // `env.ctor_index` populated by `build_check_env` cover the
    // resolution path. Duplicate-type / duplicate-ctor diagnostics
    // for THIS module are still per-module and fail-fast: a
    // duplicate corrupts later body checks for this module, so we
    // abort this module on the first such error and let the outer
    // loop continue with siblings.
    let mut seen_types: BTreeSet<String> = BTreeSet::new();
    let mut seen_ctors: BTreeMap<String, String> = BTreeMap::new();
    for def in &m.defs {
        if let Def::Type(td) = def {
            if !seen_types.insert(td.name.clone()) {
                errors.push(CheckError::Def(
                    td.name.clone(),
                    Box::new(CheckError::DuplicateType(td.name.clone())),
                ));
                return errors;
            }
            for c in &td.ctors {
                if let Some(prev) = seen_ctors.get(&c.name) {
                    errors.push(CheckError::Def(
                        td.name.clone(),
                        Box::new(CheckError::DuplicateCtor {
                            ctor: c.name.clone(),
                            a: prev.clone(),
                            b: td.name.clone(),
                        }),
                    ));
                    return errors;
                }
                seen_ctors.insert(c.name.clone(), td.name.clone());
            }
        }
    }

    // Per-module overlay: seed `globals` from this module's fns,
    // build `imports` from this module's import list, set
    // `current_module`. These three fields are call-context-
    // dependent — they belong to the caller, not to
    // `build_check_env`.
    if let Some(g) = module_globals.get(&m.name) {
        for (n, t) in &g.fns {
            env.globals.insert(n.clone(), t.clone());
        }
    }
    let mut import_map: BTreeMap<String, String> = BTreeMap::new();
    for imp in &m.imports {
        let key = imp.alias.clone().unwrap_or_else(|| imp.module.clone());
        import_map.insert(key, imp.module.clone());
    }
    env.imports = import_map;
    env.current_module = m.name.clone();

    for def in &m.defs {
        if let Err(e) = check_def(def, &env) {
            errors.push(CheckError::Def(def.name().to_string(), Box::new(e)));
        }
    }
    errors
}

Note on duplicate-type/ctor handling: the pre-refactor body mutated env.types / env.ctor_index per-def to detect duplicates in-band. With the workspace-flat env already populated by build_check_env, we use a per-module seen_types / seen_ctors overlay to preserve the same fail-fast diagnostics without re-mutating the shared env.

• Step 2: Verify build is clean

Run: cargo build --workspace 2>&1 | tail -10 Expected: builds clean. Any now-unused import in lib.rs gets removed.

• Step 3: Verify the drift-shape pin test still passes

Run: cargo test --workspace -p ailang-check --test env_construction_pin 2>&1 | tail -10 Expected: PASS.

• Step 4: Verify the three RED-test regression suite still green

Run: cargo test --workspace --test typeclass_22c --test mono_recursive_fn --test mono_xmod_qualified_ref 2>&1 | tail -20 Expected: PASS for all three.

• Step 5: Verify the workspace check tests still green

Run: cargo test --workspace -p ailang-check 2>&1 | tail -15 Expected: PASS — including happy_path_resolves_qualified_import, unknown_import_is_reported, and the rest of tests/workspace.rs.

• Step 6: Commit

git add crates/ailang-check/src/lib.rs
git commit -m "iter env-unify.2: check_in_workspace consumes build_check_env"

---

Task 4: Verify workspace + bench gates + JOURNAL entry

Final verification across the full test suite and the three bench gates, then close the milestone with a JOURNAL entry.

Files:

• Modify: docs/JOURNAL.md — append milestone-close entry.

• Step 1: Run full workspace test suite

Run: cargo test --workspace 2>&1 | tail -20 Expected: PASS — every test green (~344 tests pre-milestone; the new pin test brings it to ~345).

• Step 2: Run bench/check.py

Run: python3 bench/check.py 2>&1 | tail -10 Expected: exit 0; report ends with "0 regressed" (performance must be neutral — the helper is logically the same work as the pre-refactor inline).

• Step 3: Run bench/compile_check.py

Run: python3 bench/compile_check.py 2>&1 | tail -10 Expected: exit 0; report ends with "0 regressed".

• Step 4: Run bench/cross_lang.py

Run: python3 bench/cross_lang.py 2>&1 | tail -10 Expected: exit 0; report ends with "0 regressed".

• Step 5: Append JOURNAL entry

Append to docs/JOURNAL.md:

## 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) were 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 every workspace-flat field;
per-module overlay (`current_module`, `globals`, `imports`,
`rigid_vars`) stays at the call sites where it semantically
belongs.

After this iteration, when `synth` learns to read a new `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 pre-refactor reproduction of the inline
seeding fails the test before the bug ships.

Tasks:
- env-unify.1: extract `build_check_env`; `mono::build_workspace_env`
  becomes a one-line wrapper; drift-risk comment deleted.
- env-unify.2: `check_in_workspace` consumes `build_check_env`;
  per-module overlay logic retained; in-band duplicate-type /
  duplicate-ctor diagnostics moved to a per-module overlay set
  (preserves pre-refactor fail-fast behaviour without re-mutating
  the shared env).

Spec: `docs/specs/0003-env-construction-unify.md`. Plan:
`docs/plans/0007-env-construction-unify.md`. Tests: pin test
green, the three RED tests
(`typeclass_22c`, `mono_recursive_fn`, `mono_xmod_qualified_ref`)
remain green, full workspace test suite green, bench gates 0/0/0.

Known debt: none. 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.

• Step 6: Commit JOURNAL

git add docs/JOURNAL.md
git commit -m "iter env-unify: journal entry, milestone close"