AILang/docs/plans/mq.3.md

# Iter mq.3 — Retire MethodNameCollision + multi-class E2E + DESIGN.md sync — Implementation Plan

> **Parent spec:** `docs/specs/2026-05-13-module-qualified-class-names.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` to run
> this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Retire the workspace-global `MethodNameCollision` workaround
that mq.1 + mq.2 made redundant; exercise the type-driven dispatch
end-to-end via three new multi-class fixtures; sync DESIGN.md and
the roadmap to reflect the post-retirement architecture.

**Architecture:** Three out-of-band corrections precede the retirement.
(1) `ModuleGlobals.class_methods` + `Env.class_methods` re-key to
`BTreeMap<(QualifiedClassName, MethodName), ClassMethodEntry>` so the
post-retirement multi-candidate world has O(1) `(class, method)`
lookup. (2) `Env.active_declared_constraints: Vec<Constraint>` field
plumbed through `check_fn` pre-synth so `resolve_method_dispatch`'s
constraint-driven filter can fire at synth time for the rigid-var
fallback. (3) `synth(...)` signature extended with `warnings: &mut
Vec<Diagnostic>` out-parameter mirroring `residuals` /
`free_fn_calls`; new structured warning `class-method-shadowed-by-fn`
fires when both a fn and a class-method candidate exist for the same
name. With those in place: delete `MethodNameCollision` variant +
pre-pass + Origin enum + Display arm; relocate the two pin tests
to `crates/ailang-check/tests/method_collision_pin.rs` (cross-crate
for Env access) and invert their assertions; ship three new positive
E2E fixtures exercising the multi-candidate dispatch path (ambiguous,
explicit-qualifier, class-vs-fn-shadow); sync DESIGN.md (strike
`MethodNameCollision`, add `AmbiguousMethodResolution` +
class-fn-shadow paragraph, new §"Method dispatch" subsection);
update `docs/roadmap.md` P2 entry to `[x]` and clear milestone 24's
`depends on:` line.

**Tech Stack:** `ailang-core` (`workspace.rs`, `DESIGN.md`),
`ailang-check` (`lib.rs`, `mono.rs`, `diagnostic.rs`,
`tests/method_collision_pin.rs` — new), `ail` CLI (`main.rs` Display
arm strike), `docs/roadmap.md`.

**Pre-flight notes (Boss decisions from recon):**
- `class_methods` re-key: **Option (a) tuple key** `(QualifiedClassName,
  MethodName)`, NOT `Vec<ClassMethodEntry>` per method — O(1) post-
  dispatch lookup wins over linear scan; mono's existing presence
  check switches to `method_to_candidate_classes.contains_key(name)`
  which has the right shape natively.
- Warning channel: **Option (a) `synth(...) -> warnings out-parameter`** —
  symmetric to `residuals` / `free_fn_calls`; alternative (b) at
  check_fn boundary has no call-site context.
- `Env.active_declared_constraints` field: stores POST-superclass-expansion
  constraints (sounder for the filter; expansion already runs in check_fn
  per mq.2 journal). Cleared at workspace entry, re-populated per fn body.
- Repurposed pin tests: **relocate to `crates/ailang-check/tests/method_collision_pin.rs`** — cross-crate access to `Env.method_to_candidate_classes` is required.
- §"Diagnostic categories" `AmbiguousInstance` paragraph: REWORD, don't delete (per-class coherence stays — `DuplicateInstance` still fires; cross-class method ambiguity is the new diagnostic).
- Operator-=/`<` corner case: out of scope; prelude `ne`/`lt`/etc. are
  free fns not class methods, so the new warning does not fire on them
  even if a user adds a `class` declaring same-named methods.

---

## Task 1: Plumb `Env.active_declared_constraints` field

**Files:**
- Modify: `crates/ailang-check/src/lib.rs:3311-3391` (Env struct — add field)
- Modify: `crates/ailang-check/src/lib.rs:1622-1716` (check_fn — populate field pre-synth)

- [ ] **Step 1: Write a RED test for the new field**

Append in `crates/ailang-check/src/lib.rs` `mod tests`:

```rust
/// mq.3.1: `Env` carries an `active_declared_constraints` field
/// holding the active fn's POST-superclass-expansion declared
/// constraints. Empty at workspace entry; populated by `check_fn`
/// before invoking `synth` on the fn body. Consumed by `synth`'s
/// Var-arm class-method branch when calling `resolve_method_dispatch`
/// (constraint-driven filter path).
#[test]
fn mq3_env_active_declared_constraints_field_exists() {
    let env = Env::default();
    assert_eq!(env.active_declared_constraints.len(), 0,
        "active_declared_constraints empty at default-construction");
}
```

- [ ] **Step 2: Run test to confirm RED**

Run: `cargo test --workspace -p ailang-check mq3_env_active_declared_constraints_field_exists`

Expected: compile error — `active_declared_constraints` field does not exist on `Env`.

- [ ] **Step 3: Add the field to `Env`**

At `crates/ailang-check/src/lib.rs:3311-3391`, find the `Env` struct.
Add a field immediately after `class_methods` (Env field at lib.rs:3366):

```rust
/// mq.3: post-superclass-expansion declared constraints of the
/// active fn body being checked. Populated by `check_fn` before
/// invoking `synth` on the body; cleared at workspace entry.
/// Consumed by `synth`'s Var-arm class-method branch when calling
/// `resolve_method_dispatch` — the constraint-driven filter
/// disambiguates multi-candidate residuals at the rigid-var
/// fallback (e.g. inside a polymorphic fn body where the arg
/// type is still a rigid type variable).
pub active_declared_constraints: Vec<Constraint>,
```

Update `Default` impl if applicable (the field defaults to empty
`Vec` via `#[derive(Default)]` if `Constraint: Default`; otherwise
add explicit init in the Default impl).

- [ ] **Step 4: Populate the field in `check_fn` pre-synth**

In `crates/ailang-check/src/lib.rs:1622-1716` (`check_fn`), find the
existing `let expanded = expand_declared_constraints(...)` call (per
mq.2 journal: post-superclass-expansion happens here). The expansion
result is what we stash on Env.

Locate the env-clone-and-shadow pattern at lib.rs:1654 (mirror of
`env.rigid_vars.insert(...)`). Add:

```rust
let mut env = env.clone();
env.rigid_vars.insert(/* existing insert call */);
// mq.3: stash declared constraints for synth-time access by the
// class-method dispatch resolver's constraint-driven filter.
env.active_declared_constraints = expanded.clone();
```

(The exact placement is after the existing `expanded` computation and
before the `synth(...)` call at lib.rs:1680. Implementer adjusts the
insertion line.)

- [ ] **Step 5: Update `resolve_method_dispatch` call site in synth Var-arm to use `env.active_declared_constraints`**

At `crates/ailang-check/src/lib.rs:2462-2469` (per recon, the existing
`resolve_method_dispatch` call site passes `&[]` for
`declared_constraints`). Replace `&[]` with
`&env.active_declared_constraints`:

```rust
let outcome = resolve_method_dispatch(
    method_name,
    qualifier_prefix.as_deref(),
    candidates,
    /*concrete_arg_type*/ None,
    /*declared_constraints*/ &env.active_declared_constraints,
    /*registry*/ &registry_unit,
);
```

- [ ] **Step 6: Run the mq.3.1 test to confirm GREEN**

Run: `cargo test --workspace -p ailang-check mq3_env_active_declared_constraints_field_exists`

Expected: PASS.

- [ ] **Step 7: Run full ailang-check test suite**

Run: `cargo test --workspace -p ailang-check`

Expected: green. With `MethodNameCollision` still active, the
constraint-driven filter is unreachable (singleton candidate set short-
circuits before reaching the filter); existing tests carry the same
behaviour.

---

## Task 2: Re-key `class_methods` to `(QualifiedClassName, MethodName)`

**Files:**
- Modify: `crates/ailang-check/src/lib.rs:1129` (ModuleGlobals.class_methods type)
- Modify: `crates/ailang-check/src/lib.rs:1184-1240` (build_module_globals insert site)
- Modify: `crates/ailang-check/src/lib.rs:1086-1102` (ModuleGlobals accessor methods)
- Modify: `crates/ailang-check/src/lib.rs:3366` (Env.class_methods type)
- Modify: `crates/ailang-check/src/lib.rs:1343-1354` (build_check_env merge loop)
- Modify: `crates/ailang-check/src/lib.rs:2497-2500` (synth Var-arm class_methods lookup)
- Modify: `crates/ailang-check/src/mono.rs:967-998, 1268-1284` (mono presence-check sites switch to method_to_candidate_classes)

- [ ] **Step 1: Write a RED test for the new key shape**

Append in `crates/ailang-check/src/lib.rs` `mod tests`:

```rust
/// mq.3.2: `Env.class_methods` is keyed by `(QualifiedClassName,
/// MethodName)` tuple — post-mq.3 the workspace can carry multiple
/// classes sharing a method name, so the key must disambiguate.
/// O(1) lookup post-dispatch via `(resolved_class, method)`.
#[test]
fn mq3_env_class_methods_tuple_keyed() {
    let mut modules = BTreeMap::new();
    modules.insert(
        "m".to_string(),
        Module {
            name: "m".to_string(),
            imports: vec![],
            defs: vec![Def::Class(ClassDef {
                name: "MyCls".to_string(),
                param: "a".to_string(),
                superclass: None,
                methods: vec![ClassMethod {
                    name: "mymethod".to_string(),
                    ty: Type::Fn {
                        params: vec![Type::Var { name: "a".to_string() }],
                        param_modes: vec![ParamMode::Borrow],
                        ret: Box::new(Type::Con { name: "Str".to_string(), args: vec![] }),
                        effects: vec![],
                    },
                    default: None,
                }],
                doc: None,
            })],
        },
    );
    let ws = build_workspace_for_test(modules);
    let env = build_check_env(&ws);
    let key = ("m.MyCls".to_string(), "mymethod".to_string());
    assert!(env.class_methods.contains_key(&key),
            "env.class_methods must contain {key:?}");
}
```

- [ ] **Step 2: Run test to confirm RED**

Run: `cargo test --workspace -p ailang-check mq3_env_class_methods_tuple_keyed`

Expected: compile error or runtime panic — today's key is `String`,
not `(String, String)`.

- [ ] **Step 3: Re-key `ModuleGlobals.class_methods`**

At `crates/ailang-check/src/lib.rs:1129`, find the field:

```rust
pub class_methods: IndexMap<String, ClassMethodEntry>,
```

Replace with:

```rust
/// mq.3: re-keyed by `(qualified-class-name, method-name)` tuple —
/// post-retirement of `MethodNameCollision`, two classes can declare
/// same-named methods within the same workspace. The tuple key
/// disambiguates without losing the per-module ordering guarantee
/// (`IndexMap` preserves insertion order). Lookups by method-name-
/// only consult `method_to_candidate_classes` (Env-level) to get
/// the candidate-class set, then index into `class_methods` with
/// `(resolved_class, method)`.
pub class_methods: IndexMap<(String, String), ClassMethodEntry>,
```

Update the accessor methods at lib.rs:1086-1102:

```rust
impl ModuleGlobals {
    pub fn has_class_method(&self, class: &str, name: &str) -> bool {
        self.class_methods.contains_key(&(class.to_string(), name.to_string()))
    }

    pub fn class_method_class(&self, class: &str, name: &str) -> Option<&str> {
        self.class_methods
            .get(&(class.to_string(), name.to_string()))
            .map(|e| e.class_name.as_str())
    }

    pub fn class_method(&self, class: &str, name: &str) -> Option<&ClassMethodEntry> {
        self.class_methods.get(&(class.to_string(), name.to_string()))
    }

    /// mq.3: enumerate all `(class, method) → entry` pairs whose
    /// method name matches `name`. Replaces the pre-mq.3 `get`
    /// signature for callers that want all candidates for a method
    /// name (today: zero or one entry; post-mq.3: zero or more).
    pub fn class_method_candidates<'a>(
        &'a self,
        name: &str,
    ) -> impl Iterator<Item = (&'a String, &'a ClassMethodEntry)> {
        self.class_methods
            .iter()
            .filter_map(move |((c, m), e)| if m == name { Some((c, e)) } else { None })
    }
}
```

Existing callers of `has_class_method(name)` / `class_method_class(name)` /
`class_method(name)` need updating to pass the class — recon notes the
two call sites in `crates/ail/tests/typeclass_22b2.rs:42` etc. Update
those to pass the qualified class explicitly (e.g.
`mod_globals.class_method_class("test_22b2_class_method_lookup.Show", "show")`).

- [ ] **Step 4: Update `build_module_globals` insert site**

At `crates/ailang-check/src/lib.rs:1184-1240`, find the insert
inside the per-method loop in the `Def::Class` arm. Today's shape (per
mq.1):

```rust
let qualified_class = format!("{mname}.{}", cd.name);
class_methods.insert(
    method.name.clone(),
    ClassMethodEntry {
        class_name: qualified_class.clone(),
        // ...
    },
);
```

Replace with:

```rust
let qualified_class = format!("{mname}.{}", cd.name);
class_methods.insert(
    (qualified_class.clone(), method.name.clone()),
    ClassMethodEntry {
        class_name: qualified_class,
        // ...
    },
);
```

- [ ] **Step 5: Re-key `Env.class_methods`**

At `crates/ailang-check/src/lib.rs:3366`, find the field:

```rust
pub class_methods: BTreeMap<String, ClassMethodEntry>,
```

Replace with:

```rust
/// mq.3: workspace-flat aggregate of every module's
/// `ModuleGlobals.class_methods`, re-keyed to
/// `(qualified-class-name, method-name)` so post-retirement of
/// `MethodNameCollision` two classes can share a method name.
/// Consumed by `synth`'s Var-arm via `resolve_method_dispatch`'s
/// resolved class plus the method name.
pub class_methods: BTreeMap<(String, String), ClassMethodEntry>,
```

- [ ] **Step 6: Update `build_check_env` merge loop**

At `crates/ailang-check/src/lib.rs:1343-1354`, the merge loop today
inserts via `env.class_methods.insert(n.clone(), e.clone())` per
method name. Update to use the tuple key:

```rust
for ((qualified_class, method_name), entry) in &mg.class_methods {
    env.class_methods.insert(
        (qualified_class.clone(), method_name.clone()),
        entry.clone(),
    );
}
```

(The exact iteration pattern matches the new `IndexMap<(String, String), ...>`
shape.)

- [ ] **Step 7: Update synth Var-arm consumer at lib.rs:2497-2500**

At the existing synth Var-arm class-method branch (per recon, the mq.2
rewrite at lib.rs:2497-2500 does
`env.class_methods.get(method_name).expect("...")`):

Replace with:

```rust
let cm = env
    .class_methods
    .get(&(residual_class.clone(), method_name.to_string()))
    .expect(
        "method_to_candidate_classes invariant: \
         (resolved class, method) present implies class_methods entry",
    );
```

(Where `residual_class` is the `MethodDispatchOutcome::Resolved` /
`MethodDispatchOutcome::Multi.candidates.first()` tentative class
already computed by the outer match — see the mq.2 plan Task 6 Step 4
code for context.)

- [ ] **Step 8: Update mono presence checks at mono.rs:972, 1314**

At `crates/ailang-check/src/mono.rs:972` and `mono.rs:1314`, today's
shape (per mq.2):

```rust
let is_class_method = class_methods.contains_key(name);
```

`class_methods` here is `&BTreeMap<String, ClassMethodEntry>` passed
in as a parameter. Post-T2 it's `&BTreeMap<(String, String), ClassMethodEntry>`,
so the bare `name`-keyed lookup no longer compiles.

Switch the presence check to `method_to_candidate_classes`, which is
method-keyed natively. The mono caller already has access to `env`;
plumb `method_to_candidate_classes` through `rewrite_mono_calls` and
`interleave_slots` (mirroring how `class_methods` is plumbed):

```rust
fn rewrite_mono_calls(
    body: &mut Term,
    class_methods: &BTreeMap<(String, String), ClassMethodEntry>,
    method_to_candidate_classes: &BTreeMap<String, BTreeSet<String>>,
    /* ...other existing params... */
) {
    // ...
    let is_class_method = method_to_candidate_classes.contains_key(name);
    // ...
}
```

Update the two call sites at `mono.rs:207, 218, 1283` to thread the
new parameter (existing `&env.class_methods` argument becomes a pair
`&env.class_methods, &env.method_to_candidate_classes`).

- [ ] **Step 9: Run the mq.3.2 test + full ailang-check tests**

Run: `cargo test --workspace -p ailang-check mq3_env_class_methods_tuple_keyed`
Run: `cargo test --workspace -p ailang-check`

Expected: both green. With `MethodNameCollision` still active, every
workspace produces singleton-per-method entries; the new tuple key
adds disambiguation capacity but no behavioural change.

- [ ] **Step 10: Run full cargo workspace test suite**

Run: `cargo test --workspace`

Expected: green. Downstream consumers (ail CLI, integration tests in
`crates/ail/tests/`) see qualified class names in residuals and mono
targets; tuple-keyed class_methods is internal to ailang-check.

Note: the test-assertion update at `crates/ail/tests/typeclass_22b2.rs:42`
follows the accessor-signature change in Step 3. If that test breaks
on Step 9 with a "wrong number of arguments to class_method_class",
update its call site to pass the qualified class explicitly.

---

## Task 3: `synth(...)` warnings channel + class-method-shadowed-by-fn warning

**Files:**
- Modify: `crates/ailang-check/src/lib.rs:2351-2361` (synth signature)
- Modify: `crates/ailang-check/src/lib.rs:2402-2587` (synth Var-arm — reorder + emit warning)
- Modify: `crates/ailang-check/src/diagnostic.rs:64-79` (new diagnostic code)
- Modify: `crates/ailang-check/src/lib.rs:1622-1716` (check_fn — thread Vec<Diagnostic> + collect)
- Modify: `crates/ailang-check/src/lib.rs:840-967` (check_workspace — surface warnings)

- [ ] **Step 1: Write a RED test for the new warning**

Append in `crates/ailang-check/src/lib.rs` `mod tests`:

```rust
/// mq.3.3: when synth's Var-arm sees a name that matches BOTH a
/// free fn (per lookup precedence: locals → caller-module-fn →
/// imported-fn) AND a class method (via `method_to_candidate_classes`),
/// the fn wins per spec §"Class-fn collisions" + a structured
/// warning `class-method-shadowed-by-fn` is emitted via the
/// warnings out-parameter.
#[test]
fn mq3_class_method_shadowed_by_fn_warning_fires() {
    // Synthesise: a workspace with `class C { foo }` in module A
    // and `fn foo : (Int) -> Int` in module B; a call site in
    // module C imports both A and B and writes `foo 3`. Expected:
    // typecheck passes (resolves to B.foo) with one warning carrying
    // the structured code `class-method-shadowed-by-fn`.
    let ws = build_class_vs_fn_workspace_for_test(); // helper builds the three-module workspace
    let env = build_check_env(&ws);
    let mut residuals = Vec::new();
    let mut free_fn_calls = Vec::new();
    let mut warnings: Vec<Diagnostic> = Vec::new();
    let mut counter: u64 = 0;
    let mut locals = BTreeMap::new();
    let _ty = synth_term_for_test(
        &Term::Var { name: "foo".to_string() },
        &env,
        &mut residuals,
        &mut free_fn_calls,
        &mut warnings,
        &mut counter,
        &mut locals,
    );
    assert!(
        warnings.iter().any(|d| d.code == "class-method-shadowed-by-fn"),
        "expected at least one class-method-shadowed-by-fn warning, got: {warnings:?}",
    );
}
```

(`build_class_vs_fn_workspace_for_test` is a test-only helper the
implementer adds inline; `synth_term_for_test` likewise. Pattern:
mirror existing helpers used by the mq.2 in-test synth invocations.)

- [ ] **Step 2: Run test to confirm RED**

Run: `cargo test --workspace -p ailang-check mq3_class_method_shadowed_by_fn_warning_fires`

Expected: compile error — `synth`'s signature does not yet carry
`warnings: &mut Vec<Diagnostic>`.

- [ ] **Step 3: Extend `synth(...)` signature with warnings out-parameter**

At `crates/ailang-check/src/lib.rs:2351-2361`, find the synth function
signature. Add the new out-parameter (symmetric to the existing
`residuals` and `free_fn_calls`):

```rust
fn synth(
    term: &Term,
    env: &Env,
    residuals: &mut Vec<ResidualConstraint>,
    free_fn_calls: &mut Vec<FreeFnCall>,
    warnings: &mut Vec<Diagnostic>,  // mq.3: out-parameter for synth-time warnings
    counter: &mut u64,
    locals: &mut BTreeMap<String, Type>,
) -> Result<Type, CheckError> {
    // ...existing body...
}
```

Update every recursive call site of `synth(...)` inside the function body
to pass `warnings` through unchanged.

- [ ] **Step 4: Update the two existing `synth` callers**

`check_fn` at `crates/ailang-check/src/lib.rs:1680` and the in-test
synth-invocation helper at lib.rs:5919 (per recon) both call `synth`.
Add a `warnings: &mut Vec<Diagnostic>` local at each caller and pass
through. In `check_fn`, the warnings vector lives at fn-body-scope and
gets returned alongside the existing `Result<...>`.

In `check_fn`:

```rust
let mut warnings: Vec<Diagnostic> = Vec::new();
let body_ty = synth(
    &f.body,
    &env,
    &mut residuals,
    &mut free_fn_calls,
    &mut warnings,
    &mut counter,
    &mut locals,
)?;
// ...after synth returns, the warnings are surfaced via the
// check_fn signature extension below.
```

`check_fn`'s signature needs to return warnings. Existing signature:

```rust
fn check_fn(/* ... */) -> Result<CheckedFn, CheckError>
```

Extend (per recon `lib.rs:1622`):

```rust
fn check_fn(/* ... */) -> Result<(CheckedFn, Vec<Diagnostic>), CheckError>
```

Update every caller of `check_fn` (recon names `check_workspace` at
`lib.rs:840-967`) to destructure the new tuple.

- [ ] **Step 5: Surface warnings in `check_workspace`**

At `crates/ailang-check/src/lib.rs:840-967`, `check_workspace` already
returns a `Vec<Diagnostic>` per the existing linearity-pass pattern
(`linearity.rs:194-208`). Append per-fn warnings into that collection.

```rust
let mut all_warnings: Vec<Diagnostic> = Vec::new();
for fn_def in /* ... */ {
    let (checked, fn_warnings) = check_fn(/* ... */)?;
    all_warnings.extend(fn_warnings);
    // ...existing checked-fn handling...
}
// Return all_warnings alongside the existing check_workspace return.
```

(Existing diagnostic surface in `check_workspace` — implementer reads
the lines and threads the new warnings list into the existing return
shape verbatim.)

- [ ] **Step 6: Reorder the synth Var-arm class-method branch (fn wins)**

At `crates/ailang-check/src/lib.rs:2402-2587` (the resolution ladder
per recon), today's order is:

```
2402 locals
2404 same-module globals (fn / builtin)
2415-2518 class-method via method_to_candidate_classes
2519-2549 implicit-import free fn
2550-2584 dot-qualified explicit cross-module
2586 UnknownIdent
```

Move the implicit-import free-fn branch BEFORE the class-method branch.
The new order:

```
2402 locals
2404 same-module globals (fn / builtin)
2519-2549 implicit-import free fn   ← moved up
2415-2518 class-method via method_to_candidate_classes   ← moved down
2550-2584 dot-qualified explicit cross-module
2586 UnknownIdent
```

This implements "fn wins" per spec §"Class-fn collisions".

- [ ] **Step 7: Emit the warning at the class-method branch when an upstream-fn match shadows**

When the class-method branch is reached, check if the same `name`
ALSO had a match in the upstream fn branches (locals, same-module
fn, implicit-import fn). If yes, the class method has been
shadowed — but the upstream `return Ok(...)` already fired, so the
class-method branch never executes for shadowed-by-fn names.

Reformulate: the warning should fire ABOVE the early-return in the
implicit-import-fn branch, conditional on `method_to_candidate_classes`
containing `parse_method_qualifier(name).0`. Concretely, at the
implicit-import-fn branch (post-Step-6 reorder, now upstream of the
class-method branch):

```rust
} else if let Some((owner_module, raw_ty)) = /* implicit-import-fn match */ {
    // ...existing qualification logic...

    // mq.3: if this name ALSO has class-method candidates, the fn is
    // shadowing them. Emit a structured warning so the LLM-author can
    // disambiguate if the shadow was unintentional.
    let (method_name, _) = parse_method_qualifier(name);
    if env.method_to_candidate_classes.contains_key(method_name) {
        let candidates = env.method_to_candidate_classes.get(method_name).unwrap();
        let mut candidate_list: Vec<String> = candidates.iter().cloned().collect();
        candidate_list.sort();
        warnings.push(Diagnostic::warning(
            "class-method-shadowed-by-fn",
            format!(
                "free fn `{name}` in module `{owner_module}` shadows class method `{method_name}` \
                 declared in classes {candidate_list:?}. \
                 To call the class method instead, write `<ClassQualifier>.{method_name} ...`.",
            ),
        ));
    }

    return Ok(qualified);
}
```

(The exact `Diagnostic::warning` API is per `diagnostic.rs:186`; the
implementer matches the signature.)

Symmetric warning placements at the locals branch + same-module-fn
branch (where the fn-wins precedence is already in place pre-mq.3):
the implementer adds the same shadow-check at those branches' early-
return sites.

- [ ] **Step 8: Document the new diagnostic code in `diagnostic.rs`**

In `crates/ailang-check/src/diagnostic.rs:64-79`, append:

```rust
//! - `class-method-shadowed-by-fn` — mq.3: a `Term::Var.name`
//!   resolved to a free fn (locals / caller-module-fn /
//!   imported-fn), but the same method name has class-method
//!   candidates in the workspace. Warning, not error — the fn
//!   resolution proceeds; the warning surfaces the shadow so the
//!   LLM-author can disambiguate.
```

- [ ] **Step 9: Run the mq.3.3 test to confirm GREEN**

Run: `cargo test --workspace -p ailang-check mq3_class_method_shadowed_by_fn_warning_fires`

Expected: PASS.

- [ ] **Step 10: Run full ailang-check test suite**

Run: `cargo test --workspace -p ailang-check`

Expected: green. With `MethodNameCollision` still gating real
workspaces in `MethodNameCollision { kind: "class-fn" }` mode, no
real workspace currently has both a class method and a free fn of
the same name. The warning only fires post-Task-4 retirement.

- [ ] **Step 11: Run full cargo workspace test suite**

Run: `cargo test --workspace`

Expected: green.

---

## Task 4: Delete `MethodNameCollision`

**Files:**
- Modify: `crates/ailang-core/src/workspace.rs:297-308` (delete variant)
- Modify: `crates/ailang-core/src/workspace.rs:609-694` (delete pre-pass + Origin enum)
- Modify: `crates/ail/src/main.rs:1201-1219` (delete Display arm)
- Modify: `crates/ailang-core/src/workspace.rs:2130-2200` (delete in-workspace.rs pin tests; relocation happens in Task 5)

- [ ] **Step 1: Delete the `MethodNameCollision` variant**

At `crates/ailang-core/src/workspace.rs:297-308`, remove the entire
variant:

```rust
/// Iter 22b.2: a class-method name collides with another
/// class-method or with a top-level fn. `kind` is
/// `"class-class"` or `"class-fn"`.
#[error(
    "method name `{method}` collides ({kind}): defined in `{first_origin}` and `{second_origin}`"
)]
MethodNameCollision {
    method: String,
    kind: &'static str,
    first_origin: String,
    second_origin: String,
},
```

- [ ] **Step 2: Delete the pre-pass + `Origin` enum**

At `crates/ailang-core/src/workspace.rs:609-694`, remove the entire
method-name-collision pre-pass — from the iter-22b.2 comment block at
609 down through the close of the per-def iteration loop at 694
inclusive. This includes the `Origin` enum + `Origin::format` impl
defined inside.

The pass-1 class scan (587-607) and pass-2 instance registry build
(696+) stay; they are independent.

- [ ] **Step 3: Delete the Display arm in `main.rs`**

At `crates/ail/src/main.rs:1201-1219`, remove the
`W::MethodNameCollision { ... } => ...` arm in
`workspace_error_to_diagnostic`.

After the delete, verify the match expression compiles (no missing
arms — `WorkspaceLoadError` post-deletion no longer carries the
`MethodNameCollision` variant, so the match is complete without it).

- [ ] **Step 4: Delete the in-workspace.rs pin tests**

At `crates/ailang-core/src/workspace.rs:2130-2200`, remove the two
pin tests `class_class_method_name_collision_fires` and
`class_fn_method_name_collision_fires`. The relocated + inverted
versions land in Task 5; in this task they go out (and the on-disk
fixtures stay — they will be exercised by the relocated tests).

- [ ] **Step 5: Run full cargo workspace test suite**

Run: `cargo test --workspace`

Expected: green. The two on-disk fixtures
`examples/test_22b2_method_name_collision_class_class.ail.json` and
`examples/test_22b2_method_name_collision_class_fn.ail.json` now load
cleanly (no diagnostic). No test asserts on them at this point —
Task 5 adds the new repurposed tests.

If `cargo test` reports failures, they are tests that depended on the
`MethodNameCollision` shape; reading the failure output identifies the
exact stale assertion. Common case: a test asserts
`WorkspaceLoadError::MethodNameCollision { ... }` matches the load
result; post-deletion the test panics with "expected Err but got Ok".

---

## Task 5: Relocate + invert the pin tests to `crates/ailang-check/tests/method_collision_pin.rs`

**Files:**
- Create: `crates/ailang-check/tests/method_collision_pin.rs`

- [ ] **Step 1: Create the new test file with the two repurposed pin tests**

Create `crates/ailang-check/tests/method_collision_pin.rs`:

```rust
//! mq.3.5: repurposed pin tests for the post-retirement workspace
//! load path. The two on-disk fixtures that fired
//! `MethodNameCollision` pre-mq.3 now load cleanly; the assertion
//! migrates from "expect collision diagnostic" to "load
//! successful + `method_to_candidate_classes` contains the
//! expected multi-entry set".

use ailang_check::build_check_env;
use ailang_core::workspace::load_workspace_from_paths;
use std::path::Path;

/// mq.3.5: `examples/test_22b2_method_name_collision_class_class.ail.json`
/// declares two classes in the same module each declaring a same-
/// named method (the pre-mq.3 invariant violation). Post-mq.3 the
/// workspace loads cleanly and `env.method_to_candidate_classes`
/// carries both classes as candidates for the method name.
#[test]
fn mq3_class_class_collision_loads_clean_and_populates_candidates() {
    let ws = load_workspace_from_paths(&[
        Path::new("examples/test_22b2_method_name_collision_class_class.ail.json"),
    ])
    .expect("post-mq.3: workspace loads without collision diagnostic");

    let env = build_check_env(&ws);
    // The fixture's method name is determined by reading the file —
    // implementer substitutes the actual method name here. From the
    // fixture: classes `A` and `B` each declare method `foo`.
    let candidates = env
        .method_to_candidate_classes
        .get("foo")
        .expect("foo must be in method_to_candidate_classes");
    let module_name = ws
        .modules
        .keys()
        .find(|n| *n != "prelude")
        .expect("non-prelude module")
        .clone();
    assert!(candidates.contains(&format!("{module_name}.A")),
            "candidates: {candidates:?}");
    assert!(candidates.contains(&format!("{module_name}.B")),
            "candidates: {candidates:?}");
    assert_eq!(candidates.len(), 2);
}

/// mq.3.5: `examples/test_22b2_method_name_collision_class_fn.ail.json`
/// declares `class Greet { greet }` and `fn greet`. Post-mq.3 the
/// workspace loads cleanly; the method-vs-fn coexistence is now
/// legal (warning fires at call sites, not at load time).
#[test]
fn mq3_class_fn_collision_loads_clean() {
    load_workspace_from_paths(&[
        Path::new("examples/test_22b2_method_name_collision_class_fn.ail.json"),
    ])
    .expect("post-mq.3: workspace loads — class-vs-fn name overlap is no longer a load error");
}
```

(`load_workspace_from_paths` is the existing loader entry — implementer
matches the actual API name if it differs in `ailang-core`.)

- [ ] **Step 2: Run the new tests**

Run: `cargo test --workspace --test method_collision_pin`

Expected: both PASS.

- [ ] **Step 3: Run full cargo workspace test suite**

Run: `cargo test --workspace`

Expected: green.

---

## Task 6: Three new positive E2E fixtures + integration tests

**Files:**
- Create: `examples/mq3_two_show_ambiguous_a.ail.json`
- Create: `examples/mq3_two_show_ambiguous_b.ail.json`
- Create: `examples/mq3_two_show_ambiguous.ail.json` (entry; bare `show 42` → AmbiguousMethodResolution)
- Create: `examples/mq3_two_show_qualified.ail.json` (entry; `modA.Show.show 42` → resolves cleanly)
- Create: `examples/mq3_class_eq_vs_fn_eq_classmod.ail.json`
- Create: `examples/mq3_class_eq_vs_fn_eq_fnmod.ail.json`
- Create: `examples/mq3_class_eq_vs_fn_eq.ail.json` (entry; `eq x y` → fn wins + warning)
- Create: `crates/ail/tests/mq3_multi_class_e2e.rs`

- [ ] **Step 1: Create fixture (a) — two Show classes + Show Int each**

Create `examples/mq3_two_show_ambiguous_a.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "mq3_two_show_ambiguous_a",
  "imports": [],
  "defs": [
    { "kind": "class",
      "name": "Show",
      "param": "a",
      "methods": [
        { "name": "show",
          "type": {
            "k": "fn",
            "params": [{ "k": "var", "name": "a" }],
            "param_modes": ["borrow"],
            "ret": { "k": "con", "name": "Str" },
            "effects": []
          }
        }
      ]
    },
    { "kind": "instance",
      "class": "Show",
      "type": { "k": "con", "name": "Int" },
      "methods": [
        { "name": "show",
          "body": { "t": "app", "fn": { "t": "var", "name": "int_to_str" },
                    "args": [{ "t": "var", "name": "x" }] }
        }
      ]
    }
  ]
}
```

Create `examples/mq3_two_show_ambiguous_b.ail.json` (identical
structure, different module name):

```json
{
  "schema": "ailang/v0",
  "name": "mq3_two_show_ambiguous_b",
  "imports": [],
  "defs": [
    { "kind": "class",
      "name": "Show",
      "param": "a",
      "methods": [
        { "name": "show",
          "type": {
            "k": "fn",
            "params": [{ "k": "var", "name": "a" }],
            "param_modes": ["borrow"],
            "ret": { "k": "con", "name": "Str" },
            "effects": []
          }
        }
      ]
    },
    { "kind": "instance",
      "class": "Show",
      "type": { "k": "con", "name": "Int" },
      "methods": [
        { "name": "show",
          "body": { "t": "app", "fn": { "t": "var", "name": "int_to_str" },
                    "args": [{ "t": "var", "name": "x" }] }
        }
      ]
    }
  ]
}
```

(The `body` shape for the instance methods follows the pattern from
existing `examples/mq1_xmod_constraint_class_dep.ail.json`; implementer
matches the actual instance-method-body schema if it differs. Schema:
each instance method has a `body` field carrying a `Term`; the body
for `show` is `\x -> int_to_str x` — but JSON-side it's emitted as
just the `Term::App` without the outer lambda because the instance-
method body's lambda is implicit. Implementer adjusts to match the
exact shape used by `examples/prelude.ail.json`'s Eq/Ord instances.)

- [ ] **Step 2: Create fixture (a) entry module — bare `show 42`**

Create `examples/mq3_two_show_ambiguous.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "mq3_two_show_ambiguous",
  "imports": ["mq3_two_show_ambiguous_a", "mq3_two_show_ambiguous_b"],
  "defs": [
    { "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "param_modes": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "body": {
        "t": "do",
        "op": "io/print_str",
        "args": [{ "t": "app",
                   "fn": { "t": "var", "name": "show" },
                   "args": [{ "t": "lit", "k": "int", "v": 42 }] }]
      }
    }
  ]
}
```

- [ ] **Step 3: Create fixture (b) entry module — explicit qualifier**

Create `examples/mq3_two_show_qualified.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "mq3_two_show_qualified",
  "imports": ["mq3_two_show_ambiguous_a", "mq3_two_show_ambiguous_b"],
  "defs": [
    { "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "param_modes": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "body": {
        "t": "do",
        "op": "io/print_str",
        "args": [{ "t": "app",
                   "fn": { "t": "var", "name": "mq3_two_show_ambiguous_a.Show.show" },
                   "args": [{ "t": "lit", "k": "int", "v": 42 }] }]
      }
    }
  ]
}
```

- [ ] **Step 4: Create fixture (c) — class Eq + fn eq + entry**

Create `examples/mq3_class_eq_vs_fn_eq_classmod.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "mq3_class_eq_vs_fn_eq_classmod",
  "imports": [],
  "defs": [
    { "kind": "class",
      "name": "MyEq",
      "param": "a",
      "methods": [
        { "name": "myeq",
          "type": {
            "k": "fn",
            "params": [{ "k": "var", "name": "a" }, { "k": "var", "name": "a" }],
            "param_modes": ["borrow", "borrow"],
            "ret": { "k": "con", "name": "Bool" },
            "effects": []
          }
        }
      ]
    },
    { "kind": "instance",
      "class": "MyEq",
      "type": { "k": "con", "name": "Int" },
      "methods": [
        { "name": "myeq",
          "body": { "t": "var", "name": "true" }
        }
      ]
    }
  ]
}
```

Create `examples/mq3_class_eq_vs_fn_eq_fnmod.ail.json`:

```json
{
  "schema": "ailang/v0",
  "name": "mq3_class_eq_vs_fn_eq_fnmod",
  "imports": [],
  "defs": [
    { "kind": "fn",
      "name": "myeq",
      "type": {
        "k": "fn",
        "params": [{ "k": "con", "name": "Int" }, { "k": "con", "name": "Int" }],
        "param_modes": ["borrow", "borrow"],
        "ret": { "k": "con", "name": "Bool" },
        "effects": []
      },
      "params": ["x", "y"],
      "body": { "t": "var", "name": "false" }
    }
  ]
}
```

Create `examples/mq3_class_eq_vs_fn_eq.ail.json` (entry):

```json
{
  "schema": "ailang/v0",
  "name": "mq3_class_eq_vs_fn_eq",
  "imports": ["mq3_class_eq_vs_fn_eq_classmod", "mq3_class_eq_vs_fn_eq_fnmod"],
  "defs": [
    { "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "param_modes": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "body": {
        "t": "do",
        "op": "io/print_bool",
        "args": [{ "t": "app",
                   "fn": { "t": "var", "name": "myeq" },
                   "args": [{ "t": "lit", "k": "int", "v": 1 },
                            { "t": "lit", "k": "int", "v": 2 }] }]
      }
    }
  ]
}
```

(Naming choice: `MyEq`/`myeq` rather than reusing the prelude's
`Eq`/`eq` to avoid an additional prelude-vs-fn shadow that would
confuse the warning assertion. Implementer adjusts the
`io/print_bool` op call if the prelude builtin's exact name differs.)

- [ ] **Step 5: Create the integration-test file**

Create `crates/ail/tests/mq3_multi_class_e2e.rs`:

```rust
//! mq.3.6: end-to-end coverage of the post-mq.3 multi-candidate
//! dispatch path. Three positive fixtures exercise the three
//! trajectories from spec §"Data flow":
//! - ambiguous (Trajectory C): `AmbiguousMethodResolution`.
//! - explicit qualifier (Trajectory E): clean resolve.
//! - class-fn shadow: fn wins + warning.

use std::path::Path;
use std::process::Command;

fn run_ail_check(entry: &str, deps: &[&str]) -> std::process::Output {
    let mut cmd = Command::new(env!("CARGO_BIN_EXE_ail"));
    cmd.arg("check").arg("--json").arg(entry);
    for dep in deps {
        cmd.arg(dep);
    }
    cmd.output().expect("ail check must run")
}

/// mq.3.6: bare `show 42` in a workspace with two Show classes both
/// shipping Show Int fires `AmbiguousMethodResolution` with both
/// candidate classes named.
#[test]
fn mq3_two_show_ambiguous_fires_ambiguous_method_resolution() {
    let out = run_ail_check(
        "examples/mq3_two_show_ambiguous.ail.json",
        &[
            "examples/mq3_two_show_ambiguous_a.ail.json",
            "examples/mq3_two_show_ambiguous_b.ail.json",
        ],
    );
    assert!(!out.status.success(),
            "expected check to reject ambiguous dispatch");
    let stdout = String::from_utf8_lossy(&out.stdout);
    assert!(stdout.contains("ambiguous-method-resolution"),
            "expected ambiguous-method-resolution diagnostic, got: {stdout}");
    assert!(stdout.contains("mq3_two_show_ambiguous_a.Show"),
            "expected candidate A named, got: {stdout}");
    assert!(stdout.contains("mq3_two_show_ambiguous_b.Show"),
            "expected candidate B named, got: {stdout}");
}

/// mq.3.6: explicit qualifier `modA.Show.show 42` resolves to
/// modA's class cleanly.
#[test]
fn mq3_two_show_qualified_resolves_clean() {
    let out = run_ail_check(
        "examples/mq3_two_show_qualified.ail.json",
        &[
            "examples/mq3_two_show_ambiguous_a.ail.json",
            "examples/mq3_two_show_ambiguous_b.ail.json",
        ],
    );
    assert!(out.status.success(),
            "expected check to succeed with explicit qualifier, got: {}",
            String::from_utf8_lossy(&out.stdout));
}

/// mq.3.6: `eq x y` in a workspace with `class MyEq` + `fn myeq`
/// resolves to the fn per lookup precedence; structured warning
/// `class-method-shadowed-by-fn` fires.
#[test]
fn mq3_class_eq_vs_fn_eq_fn_wins_with_warning() {
    let out = run_ail_check(
        "examples/mq3_class_eq_vs_fn_eq.ail.json",
        &[
            "examples/mq3_class_eq_vs_fn_eq_classmod.ail.json",
            "examples/mq3_class_eq_vs_fn_eq_fnmod.ail.json",
        ],
    );
    assert!(out.status.success(),
            "expected check to succeed (fn wins): {}",
            String::from_utf8_lossy(&out.stdout));
    let stdout = String::from_utf8_lossy(&out.stdout);
    assert!(stdout.contains("class-method-shadowed-by-fn"),
            "expected shadow warning, got: {stdout}");
}
```

(The `run_ail_check` helper builds an `ail check` invocation. The exact
CLI flag for emitting structured-JSON diagnostics is `--json` per the
existing CLI convention; implementer verifies the flag name from the
existing CLI test files at `crates/ail/tests/ct1_check_cli.rs`.)

- [ ] **Step 6: Run the new E2E tests**

Run: `cargo test --workspace --test mq3_multi_class_e2e`

Expected: all three PASS.

- [ ] **Step 7: Run full cargo workspace test suite**

Run: `cargo test --workspace`

Expected: green.

---

## Task 7: DESIGN.md sync

**Files:**
- Modify: `docs/DESIGN.md:1156-1160` (rewrite class-names-bare paragraph)
- Modify: `docs/DESIGN.md:1717-1755` (Diagnostic categories — strike MethodNameCollision, add new diagnostics, reword AmbiguousInstance paragraph)
- Modify: `docs/DESIGN.md` (new subsection "Method dispatch")

- [ ] **Step 1: Rewrite the `class names stay bare` paragraph**

At `docs/DESIGN.md:1156-1160`, replace the paragraph that today
references `MethodNameCollision`:

```markdown
Class names follow the canonical-form rule (mq.1): bare for same-
module references, `<module>.<Class>` for cross-module references —
symmetric to `Type::Con.name`'s rule from ct.1. Three schema fields
carry class references in this form: `InstanceDef.class`,
`Constraint.class`, and `SuperclassRef.class`. `ClassDef.name`
itself stays bare (defining-site context, like `TypeDef.name`).

Method dispatch is type-driven post-mq.3 (see §"Method dispatch"):
synth resolves a `Term::Var { name: "show" }` by consulting the
workspace's method-to-candidate-class index, filtering by argument
type (concrete) or by declared constraint (rigid-var), and routing
the residual through the registry at fn-body-end discharge.
Method-name collisions across classes are now structurally legal —
they resolve at the call site via type-driven dispatch with explicit
qualifier (`<module>.<Class>.<method>`) as the LLM-author's
disambiguation tool.
```

- [ ] **Step 2: Strike `MethodNameCollision` from Diagnostic categories**

At `docs/DESIGN.md:1730-1731` (per recon, under "Workspace-load
(registry-build) diagnostics"), remove the `MethodNameCollision`
bullet entirely.

- [ ] **Step 3: Add new typecheck diagnostics**

At `docs/DESIGN.md:1747-1755` (per recon, under "Typecheck
diagnostics"), append:

```markdown
- `AmbiguousMethodResolution` — a monomorphic `Term::Var` call site
  has multiple candidate classes after type-driven and constraint-
  driven filters. LLM-author writes the explicit qualifier form
  `<module>.<Class>.<method>` to disambiguate.
- `UnknownClass` — an explicit class qualifier in `Term::Var.name`
  names a qualified class that is not in the workspace registry.
- `class-method-shadowed-by-fn` (warning) — a `Term::Var` resolved
  via fn lookup precedence (locals → caller-module-fn →
  imported-fn) while a class method of the same name also exists
  in the workspace. Fn resolution proceeds; the warning surfaces
  the shadow so the LLM-author can disambiguate via explicit
  class-qualified call if the shadow was unintentional.
- `NoInstance.candidate_classes` — when the bare-method dispatch
  path fails because none of the candidate classes have an instance
  for the concrete argument type, the diagnostic surfaces the
  candidate list so the LLM-author knows which class needs an
  instance.
```

- [ ] **Step 4: Reword the `AmbiguousInstance` paragraph**

At `docs/DESIGN.md:1753-1755`, replace the existing wording with:

```markdown
There is no `AmbiguousInstance` diagnostic at the registry level —
coherence (`DuplicateInstance` at registry build) makes per-`(class,
type)` ambiguity structurally impossible. Cross-class method
ambiguity is a separate concern resolved at the call site via
`AmbiguousMethodResolution` (see §"Method dispatch").
```

- [ ] **Step 5: Add the `## Method dispatch` subsection**

Append a new top-level subsection at the end of the diagnostic-
categories block (after `docs/DESIGN.md:1755`). Implementer adjusts
the heading depth to match surrounding structure (`##` if the
diagnostic block is `##`, `###` otherwise).

```markdown
## Method dispatch

Post-mq.3, dispatch is two-mode:

**Polymorphic call sites** (inside a fn body with `forall` +
constraint set): the constraint names the class via the qualified
`Constraint.class` field (canonical-form per mq.1). Synth's
residual carries the class name directly; constraint-discharge at
fn-body-end matches against the workspace registry by
`(class, type_hash)` key.

**Monomorphic call sites**: synth consults the workspace-flat
`Env.method_to_candidate_classes: BTreeMap<MethodName,
BTreeSet<QualifiedClassName>>` index, then runs the 5-step
dispatch rule:

1. Parse the `Term::Var.name` for an optional class qualifier
   (last-dot-segment is the method name; everything before is the
   qualified class).
2. If `method_to_candidate_classes` has no entry for the method
   name, fall through to the existing Var-arm branches (free fn
   lookup, dot-qualified cross-module).
3. Qualifier present: filter candidates to the named class.
   Empty result fires `UnknownClass`. Singleton survivor proceeds.
4. Qualifier empty (bare-method form): singleton candidate proceeds
   directly; multiple candidates yield a multi-candidate residual
   for discharge-time refinement.
5. At discharge, refinement runs: concrete `type_` filters
   candidates via the workspace registry; rigid-var `type_` filters
   via the active fn's declared constraints. Single survivor
   discharges; multiple survivors fire `AmbiguousMethodResolution`
   (concrete) or `MissingConstraint` (rigid-var); zero survivors
   fire `NoInstance` (concrete) or `MissingConstraint` (rigid-var).

The `method_to_candidate_classes` index is the load-bearing data
structure for this routing — its construction in `build_check_env`
inverts the per-module `class_methods` maps to a workspace-flat
method-name-to-class-set map.

Class-fn collisions resolve at the call site, not at workspace load
time: the fn lookup precedence (locals → caller-module-fn →
imported-fn) runs ahead of the class-method branch. When both
sides have a match, the fn wins and a `class-method-shadowed-by-fn`
warning surfaces the shadow.
```

- [ ] **Step 6: Run the DESIGN.md drift test**

Run: `cargo test --workspace -p ailang-check design_schema_drift`

(If the test exists with that exact name; otherwise check
`crates/ailang-check/src/lib.rs` `mod tests` for the test that scans
DESIGN.md for required anchors.)

Expected: green. If the test fails on the modified DESIGN.md
sections, update the test's anchor list to match the new wording.

- [ ] **Step 7: Run full cargo workspace test suite**

Run: `cargo test --workspace`

Expected: green.

---

## Task 8: Roadmap update

**Files:**
- Modify: `docs/roadmap.md:126-143` (P2 entry — mark `[x]`)
- Modify: `docs/roadmap.md:64-86` (P1 entry — strike `depends on:` line + annotate)

- [ ] **Step 1: Mark the P2 milestone as done**

At `docs/roadmap.md:126`, find the entry `- [ ] **[milestone]**
Module-qualified class names + type-driven method dispatch — ...`.
Flip the checkbox to `[x]`:

```markdown
- [x] **[milestone]** Module-qualified class names + type-driven method dispatch — retire the `MethodNameCollision` workaround [...]
```

(Optionally trim the body once closed; convention is to leave the
description in place until the entry is purged on the next roadmap
sweep.)

- [ ] **Step 2: Clear milestone 24's `depends on:` line + annotate**

At `docs/roadmap.md:64-86`, the P1 entry "Post-22 Prelude — Show +
print rewire" carries (per recon) a `depends on:` line at 83-85:

```markdown
  - depends on: P2 milestone "Module-qualified class names +
    type-driven method dispatch" (retires the `MethodNameCollision`
    workaround that drives the collision).
```

Strike that line. Then add an annotation under the entry:

```markdown
  - ready for re-brainstorm — the `MethodNameCollision` workaround
    that blocked the original spec retired in mq.3 (2026-05-13).
    Fresh brainstorm re-derives the spec against the post-retirement
    architecture (type-driven dispatch, class-ref canonical form).
```

- [ ] **Step 3: Run `cargo test --workspace`**

Run: `cargo test --workspace`

Expected: green. Roadmap edits are doc-only.

---

## Task 9: Integration verification — full cargo + bench + roundtrip

**Files:** none modified; verification only.

- [ ] **Step 1: Full `cargo test --workspace`**

Run: `cargo test --workspace`

Expected: green. The new and repurposed tests pass; existing tests
unchanged.

- [ ] **Step 2: Spot-check the three new E2E fixtures via `ail check`**

Run:
```
cargo run -p ail -- check examples/mq3_two_show_ambiguous.ail.json
```
Expected: exit non-zero with `ambiguous-method-resolution` diagnostic.

Run:
```
cargo run -p ail -- check examples/mq3_two_show_qualified.ail.json
```
Expected: exit 0.

Run:
```
cargo run -p ail -- check examples/mq3_class_eq_vs_fn_eq.ail.json
```
Expected: exit 0 with `class-method-shadowed-by-fn` warning surfaced.

- [ ] **Step 3: Verify zero diff on prelude**

Run: `git diff -- examples/prelude.ail.json`

Expected: no output (prelude unchanged).

- [ ] **Step 4: Bench scripts**

Run: `python3 bench/check.py`
Expected: exit 0 OR audit-ratified.

Run: `python3 bench/compile_check.py`
Expected: exit 0 OR audit-ratified.

Run: `python3 bench/cross_lang.py`
Expected: exit 0 OR audit-ratified.

- [ ] **Step 5: Confirm the per-iter journal placeholder is staged**

The implementer leaves `docs/journals/2026-05-13-iter-mq.3.md` (or the
date the iter actually finishes) in the working tree with a draft
entry covering: tasks ran, deviations from plan (if any), the
`class_methods` re-key consumer-rewrite scope, the synth warnings-
channel plumbing, the three E2E fixtures, DESIGN.md sync, roadmap
update, test counts, and bench outcomes. Append a pointer line to
`docs/journals/INDEX.md`. The Boss commits.

Note for milestone-close: WhatsNew.md is shipped at milestone-close-
audit (separate iter), NOT in mq.3 itself.