# prep.1 — Type-scoped namespacing — Implementation Plan

> **Parent spec:** `docs/specs/0052-kernel-extension-mechanics.md` (Iteration prep.1 section)
> **Gitea issue:** refs #31 (the implementer-side iter-completion commit closes via `closes #31`)
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Ship type-scoped member-access (`<TypeName>.<member>`) as the canonical resolution path for type-associated operations in `ailang-check`, narrow `BareCrossModuleTypeRef` / `BadCrossModuleTypeRef` to fire only when a bare type-name is not in scope by any path, and migrate the 12 `.ail` std-library example fixtures that use the old `std_X.Y` form.

**Architecture:** `ailang-check`'s `Term::Var` dot-qualified arm gains a TypeDef-first ladder (look up `prefix` as a known TypeDef across the workspace; if found, route to its home module; otherwise fall back to the legacy module-as-receiver path). `ailang-core::workspace::check_type_con_name` is widened: a bare cross-module `Type::Con.name` is accepted when the owning module's imports — explicit or implicit — provide it. Two new `CheckError` variants (`TypeScopedMemberNotFound`, `TypeScopedReceiverNotAType`) cover the new failure modes. The two existing `WorkspaceLoadError` messages drop the obsolete `ail migrate-canonical-types` hint and gain an import-or-type-scoped-form suggestion. The 12 fixture rewrites are atomic with the resolver change.

**Tech stack:** `crates/ailang-check` (resolver + new diagnostics), `crates/ailang-core/src/workspace.rs` (type-position validator + message strings), `crates/ail/src/main.rs` (CLI diagnostic translation), `crates/ail/tests/ct1_check_cli.rs` (CLI assertion update), `examples/*.ail` (12 fixtures), source-side doc-comments in `crates/ailang-{check,codegen,surface}/src/` + `crates/ail/tests/e2e.rs` (vocabulary cleanup).

**Out of scope (deferred to prep.2 / prep.3, per spec):**

- `Term::New` (prep.2).
- `kernel: true` flag + `param-in` (prep.3).
- Schema-drift pin additions (no new JSON tags in prep.1).
- Hash-pin refreshes (recon: no overlap with migrated fixtures).
- `.ail.json` fixture updates (recon: none of the 15 spec-named `.ail` files have a sibling `.ail.json` pin).

**Files this plan creates or modifies:**

- Modify: `crates/ailang-check/src/lib.rs:380-700` — `CheckError` enum: add `TypeScopedMemberNotFound` and `TypeScopedReceiverNotAType` variants.
- Modify: `crates/ailang-check/src/lib.rs:702-744` — `CheckError::code()` match: add two arms.
- Modify: `crates/ailang-check/src/lib.rs:749-845` (approx.) — `CheckError::ctx()` and downstream message-format matches: add two arms each.
- Modify: `crates/ailang-check/src/lib.rs:3163-3200` — `Term::Var` dot-qualified resolution arm: TypeDef-first ladder.
- Modify: `crates/ailang-core/src/workspace.rs:320-342` — narrow `#[error(...)]` messages on `BareCrossModuleTypeRef` and `BadCrossModuleTypeRef`.
- Modify: `crates/ailang-core/src/workspace.rs:1077-1142` — `check_type_con_name`: bare in-scope acceptance path.
- Modify: `crates/ailang-core/src/workspace.rs:1820-1983` — in-source mod tests: one test flips (bare-with-import-candidate now accepted); narrowed-message assertions land here.
- Modify: `crates/ail/src/main.rs:1249-1278` — `workspace_error_to_diagnostic` arms for the two narrowed errors.
- Modify: `crates/ail/tests/ct1_check_cli.rs:154-157` — assertion on `ail migrate-canonical-types` → new wording.
- Migrate: `examples/ct_2_bare_cross_module.ail`, `examples/ct_3b_bad_qualified_known_module.ail`, `examples/nested_pat.ail`, `examples/std_either_demo.ail`, `examples/std_either_list.ail`, `examples/std_either_list_demo.ail`, `examples/std_list.ail`, `examples/std_list_demo.ail`, `examples/std_list_more_demo.ail`, `examples/std_list_stress.ail`, `examples/std_maybe_demo.ail`, `examples/std_pair_demo.ail` — 12 files; rewrite `std_X.Y` → type-scoped form atomically.
- Modify: `crates/ail/tests/e2e.rs` — vocabulary cleanup in test-fn doc-comments; fixture filenames (`build_and_run("std_<X>_demo.ail")`) unchanged.
- Modify: `crates/ailang-check/src/lift.rs:71`, `crates/ailang-check/src/mono.rs:1034`, `crates/ailang-codegen/src/lib.rs:3444`, `crates/ailang-codegen/src/subst.rs:157` — doc-comment vocabulary cleanup.
- Test: `crates/ailang-check/src/lib.rs` in-source `#[cfg(test)]` module — three new tests: `type_scoped_member_resolves`, `type_scoped_member_not_found`, `type_scoped_receiver_not_a_type`.
- Test: `crates/ailang-core/src/workspace.rs` in-source `#[cfg(test)]` module — one new test: `ct1_validator_accepts_bare_with_explicit_import`; one existing flip: `ct1_validator_rejects_bare_xmod_with_import_candidate` → `ct1_validator_accepts_bare_xmod_with_import_candidate`.

---

### Task 1: New `CheckError` variants + `Term::Var` type-scoped resolution

**Files:**

- Modify: `crates/ailang-check/src/lib.rs:380-700` (`CheckError` enum)
- Modify: `crates/ailang-check/src/lib.rs:702-744` (`code()` match)
- Modify: `crates/ailang-check/src/lib.rs:749-845` (`ctx()` match + downstream message arms)
- Modify: `crates/ailang-check/src/lib.rs:3163-3200` (`Term::Var` dot-qualified arm)
- Test: `crates/ailang-check/src/lib.rs` in-source `#[cfg(test)] mod tests`

- [ ] **Step 1: Write the three failing tests**

Append to the in-source `#[cfg(test)] mod tests` block in `crates/ailang-check/src/lib.rs`:

```rust
#[test]
fn type_scoped_member_resolves() {
    // `Maybe.from_maybe` resolves to `std_maybe.from_maybe` because
    // `Maybe` is a known TypeDef whose home module is `std_maybe`.
    let std_maybe = serde_json::from_value::<ailang_core::ast::Module>(serde_json::json!({
        "schema": ailang_core::SCHEMA,
        "name": "std_maybe",
        "imports": [],
        "defs": [
            {"kind": "data", "name": "Maybe", "vars": ["a"], "ctors": [
                {"name": "Nothing", "args": []},
                {"name": "Just", "args": [{"k": "var", "name": "a"}]}
            ]},
            {"kind": "fn", "name": "from_maybe",
             "type": {"k": "forall", "vars": ["a"], "constraints": [], "body":
                 {"k": "fn", "params": [{"k": "var", "name": "a"},
                                        {"k": "con", "name": "Maybe", "args": [{"k": "var", "name": "a"}]}],
                  "ret": {"k": "var", "name": "a"}, "effects": []}},
             "params": ["d", "m"], "body": {"t": "var", "name": "d"}}
        ]
    })).unwrap();
    let consumer = serde_json::from_value::<ailang_core::ast::Module>(serde_json::json!({
        "schema": ailang_core::SCHEMA,
        "name": "consumer",
        "imports": [{"module": "std_maybe"}],
        "defs": [
            {"kind": "fn", "name": "f",
             "type": {"k": "fn", "params": [{"k": "con", "name": "Int"}],
                      "ret": {"k": "con", "name": "Int"}, "effects": []},
             "params": ["x"],
             "body": {"t": "app", "callee": {"t": "var", "name": "Maybe.from_maybe"},
                      "args": [{"t": "var", "name": "x"},
                               {"t": "term-ctor", "type": "Maybe", "ctor": "Nothing", "args": []}]}}
        ]
    })).unwrap();
    let mut modules = std::collections::BTreeMap::new();
    modules.insert("std_maybe".to_string(), std_maybe);
    modules.insert("consumer".to_string(), consumer);
    let workspace = ailang_core::workspace::build_workspace(&modules, &["prelude"])
        .expect("workspace builds");
    let res = check_workspace(&workspace);
    assert!(res.is_ok(), "type-scoped Maybe.from_maybe must resolve cleanly, got {res:?}");
}

#[test]
fn type_scoped_member_not_found() {
    // `Maybe.bogus` fires `TypeScopedMemberNotFound`: Maybe is a known
    // TypeDef but `bogus` is not in its home module's defs.
    let std_maybe = /* same as above */ ;
    let consumer = /* like above but body uses `Maybe.bogus` */ ;
    let workspace = ailang_core::workspace::build_workspace(&modules, &["prelude"]).unwrap();
    let err = check_workspace(&workspace).expect_err("Maybe.bogus must error");
    let inner = match err {
        CheckError::Def(_, inner) => *inner,
        other => other,
    };
    assert!(matches!(inner, CheckError::TypeScopedMemberNotFound { ref type_name, ref member, .. }
                     if type_name == "Maybe" && member == "bogus"),
            "expected TypeScopedMemberNotFound, got {inner:?}");
}

#[test]
fn type_scoped_receiver_not_a_type() {
    // `SomethingRandom.x` fires `TypeScopedReceiverNotAType`:
    // `SomethingRandom` is neither a TypeDef nor an imported module.
    let consumer = /* module with body `SomethingRandom.x` */ ;
    let workspace = ailang_core::workspace::build_workspace(&modules, &["prelude"]).unwrap();
    let err = check_workspace(&workspace).expect_err("must error on unknown receiver");
    let inner = match err {
        CheckError::Def(_, inner) => *inner,
        other => other,
    };
    assert!(matches!(inner, CheckError::TypeScopedReceiverNotAType { ref name }
                     if name == "SomethingRandom"),
            "expected TypeScopedReceiverNotAType, got {inner:?}");
}
```

(The implementer fills in the omitted module-builder boilerplate by analogy to existing in-source tests above the new ones; e.g. `crates/ailang-check/src/lib.rs` `#[cfg(test)]` already has helpers like `parse_module_from_value` for similar wiring. If no such helper exists, write inline.)

- [ ] **Step 2: Run tests to verify they fail**

Run: `cargo test --workspace -p ailang-check type_scoped_`
Expected: 3 tests fail. The failures are `error[E0599]: no variant ... TypeScopedMemberNotFound` (variants don't exist yet) — that is the expected pre-state. If the test bodies fail to compile because the helper module-builders don't exist, that is *also* the RED state and must be fixed by adding the variants (Step 3) AND wiring the resolution path (Step 4).

- [ ] **Step 3: Add the two `CheckError` variants**

Append to the `CheckError` enum body in `crates/ailang-check/src/lib.rs` (after the last existing variant `Internal(String)` at line ~693):

```rust
    /// prep.1 (kernel-extension-mechanics): a dot-qualified
    /// `Term::Var` whose receiver is a known TypeDef but the suffix
    /// does not name a def in that type's home module. Code:
    /// `type-scoped-member-not-found`.
    #[error("type `{type_name}` (home module `{home_module}`) has no member `{member}`")]
    TypeScopedMemberNotFound {
        type_name: String,
        member: String,
        home_module: String,
    },

    /// prep.1 (kernel-extension-mechanics): a dot-qualified
    /// `Term::Var` whose receiver is neither a known TypeDef nor an
    /// imported module. Code: `type-scoped-receiver-not-a-type`.
    #[error("`{name}` is neither a known type nor an imported module")]
    TypeScopedReceiverNotAType {
        name: String,
    },
```

Add the two new arms to `CheckError::code()` (the match at `lib.rs:702-744`), between `RecurNotInTailPosition` and `Internal`:

```rust
            CheckError::TypeScopedMemberNotFound { .. } => "type-scoped-member-not-found",
            CheckError::TypeScopedReceiverNotAType { .. } => "type-scoped-receiver-not-a-type",
```

Walk `CheckError::ctx()` (immediately below `code()`): if the implementer's chosen ctx-shape requires arms for the new variants, add minimal ones (`serde_json::json!({"type": type_name, "member": member, "home_module": home_module})` and `serde_json::json!({"name": name})` respectively). If `ctx()` has a catch-all returning `json!({})`, no edit needed.

Run: `cargo check -p ailang-check`
Expected: 0 errors. The variants compile; the resolver does not yet emit them.

- [ ] **Step 4: Modify the `Term::Var` dot-qualified arm**

Replace the body of the `else if name.matches('.').count() == 1 { ... }` branch at `crates/ailang-check/src/lib.rs:3163-3197` with the TypeDef-first ladder:

```rust
            } else if name.matches('.').count() == 1 {
                let (prefix, suffix) = name.split_once('.').expect("checked");
                // TypeDef-first: is `prefix` a known type anywhere in
                // the workspace? If yes, that type's home module is the
                // resolution target. Otherwise: fall back to the legacy
                // module-as-receiver path.
                let type_home: Option<String> = env
                    .module_types
                    .iter()
                    .find_map(|(mod_name, types)| {
                        if types.contains(prefix) {
                            Some(mod_name.clone())
                        } else {
                            None
                        }
                    });
                let target_module: String = if let Some(home) = type_home.clone() {
                    home
                } else if let Some(m) = env.imports.get(prefix) {
                    m.clone()
                } else {
                    return Err(CheckError::TypeScopedReceiverNotAType {
                        name: prefix.to_string(),
                    });
                };
                let g = env.module_globals.get(&target_module).ok_or_else(|| {
                    CheckError::UnknownModule {
                        module: target_module.clone(),
                    }
                })?;
                let raw_ty = g.get(suffix).cloned().ok_or_else(|| {
                    // If receiver was a TypeDef but suffix missing,
                    // emit the type-scoped diagnostic. Otherwise the
                    // legacy `UnknownImport`.
                    if type_home.is_some() {
                        CheckError::TypeScopedMemberNotFound {
                            type_name: prefix.to_string(),
                            member: suffix.to_string(),
                            home_module: target_module.clone(),
                        }
                    } else {
                        CheckError::UnknownImport {
                            module: target_module.clone(),
                            name: suffix.to_string(),
                        }
                    }
                })?;
                let owner_types = env
                    .module_types
                    .get(&target_module)
                    .cloned()
                    .unwrap_or_default();
                let qualified = qualify_local_types(&raw_ty, &target_module, &owner_types);
                (qualified, Some((target_module, suffix.to_string())))
            } else {
                return Err(CheckError::UnknownIdent(name.clone()));
            };
```

- [ ] **Step 5: Run the three new tests to verify they pass**

Run: `cargo test --workspace -p ailang-check type_scoped_`
Expected: PASS, all three.

- [ ] **Step 6: Run the full `ailang-check` test suite for regressions**

Run: `cargo test --workspace -p ailang-check 2>&1 | tail -25`
Expected: zero new failures. Existing `parse_method_qualifier`-anchored tests (the class-qualifier ladder is structurally above the new branch at `lib.rs:3163`) must remain green; the dot-qualified module-as-receiver fallback path is preserved verbatim, just gated behind a TypeDef-first lookup.

---

### Task 2: Type-position bare-name resolution + narrowed diagnostic messages

**Files:**

- Modify: `crates/ailang-core/src/workspace.rs:320-342` (`#[error(...)]` strings on `BareCrossModuleTypeRef` and `BadCrossModuleTypeRef`)
- Modify: `crates/ailang-core/src/workspace.rs:1077-1142` (`check_type_con_name` body)
- Modify: `crates/ailang-core/src/workspace.rs:1820-1983` (in-source mod tests)

- [ ] **Step 1: Write the failing test for bare-with-explicit-import acceptance**

Add to the in-source `#[cfg(test)] mod tests` block in `crates/ailang-core/src/workspace.rs` (next to the existing `ct1_validator_rejects_bare_xmod_with_import_candidate` at line 1862-1876):

```rust
/// prep.1: a bare `Type::Con` whose `name` matches a TypeDef in an
/// EXPLICITLY imported module must be ACCEPTED (formerly rejected
/// as `BareCrossModuleTypeRef`). Type-scoped form is canonical;
/// importing the module brings the bare type-name into scope.
#[test]
fn ct1_validator_accepts_bare_with_explicit_import() {
    let mut modules = BTreeMap::new();
    modules.insert("other".to_string(), module_with_type_def("other", "Ordering"));
    modules.insert("m".to_string(), module_with_import_and_type_con("m", "other", "Ordering"));
    validate_canonical_type_names(&modules, &["prelude"])
        .expect("bare `Ordering` must be accepted when `other` is imported and declares it");
}
```

- [ ] **Step 2: Run the new test to verify it fails**

Run: `cargo test --workspace -p ailang-core ct1_validator_accepts_bare_with_explicit_import`
Expected: FAIL with `BareCrossModuleTypeRef { module: "m", name: "Ordering", candidates: ["other.Ordering"] }`.

- [ ] **Step 3: Modify `check_type_con_name` to accept in-scope bare names**

Replace the bare-cross-module section at `crates/ailang-core/src/workspace.rs:1112-1141` (the comment "Bare cross-module — collect candidates ..." block through the final `Err(...)`) with:

```rust
    // prep.1: a bare cross-module type-name is ACCEPTED if it's in
    // scope via an explicit import or an implicit (prelude / kernel-
    // tier) auto-import. Candidates from those paths drive both
    // acceptance and (on miss) the error message's suggested fix.
    let mut in_scope = false;
    let mut candidates: Vec<String> = Vec::new();
    for imp in import_names {
        if local_types
            .get(*imp)
            .map(|s| s.contains(name))
            .unwrap_or(false)
        {
            in_scope = true;
            candidates.push(format!("{imp}.{name}"));
        }
    }
    for implicit in implicit_imports {
        if import_names.contains(implicit) {
            continue;
        }
        if local_types
            .get(*implicit)
            .map(|s| s.contains(name))
            .unwrap_or(false)
        {
            in_scope = true;
            candidates.push(format!("{implicit}.{name}"));
        }
    }
    if in_scope {
        return Ok(());
    }
    Err(WorkspaceLoadError::BareCrossModuleTypeRef {
        module: owning_module.to_string(),
        name: name.to_string(),
        candidates,
    })
```

- [ ] **Step 4: Narrow the `#[error(...)]` message on `BareCrossModuleTypeRef`**

Replace `crates/ailang-core/src/workspace.rs:320-324`:

```rust
    #[error(
        "module `{module}` references bare type `{name}`, which is not in scope. \
        Add `(import <module>)` to bring it into scope (candidates: {candidates:?}), \
        or rewrite the call to type-scoped form `<TypeName>.<member>`."
    )]
```

Replace `crates/ailang-core/src/workspace.rs:335-338`:

```rust
    #[error(
        "module `{module}` references qualified type `{name}` but the owner module \
        is not known in the workspace, or it declares no type by that name. \
        Use the bare type-name from an imported module instead."
    )]
```

- [ ] **Step 5: Update the flipped existing test**

Rename + repurpose `ct1_validator_rejects_bare_xmod_with_import_candidate` at `crates/ailang-core/src/workspace.rs:1862-1876`. Replace its body so the rejection path it pins is the still-RED case: bare `Ordering` from a module with NO explicit import of `other` (and not in implicit-imports). New name + body:

```rust
/// prep.1: a bare `Type::Con` whose `name` is a TypeDef in some
/// workspace module BUT the owning module does NOT import that
/// module (and the type is not implicit-imported either) must still
/// fire `BareCrossModuleTypeRef` — the candidates list names the
/// importable owner(s) so the error message can suggest the fix.
#[test]
fn ct1_validator_rejects_bare_when_owner_not_imported() {
    let mut modules = BTreeMap::new();
    modules.insert("other".to_string(), module_with_type_def("other", "Ordering"));
    // `m` references `Ordering` but does NOT import `other`.
    modules.insert("m".to_string(), single_module_with_type_con("m", "Ordering").remove("m").unwrap());
    let err = validate_canonical_type_names(&modules, &["prelude"])
        .expect_err("bare `Ordering` must be rejected when `other` not imported");
    match err {
        WorkspaceLoadError::BareCrossModuleTypeRef { name, candidates, .. } => {
            assert_eq!(name, "Ordering");
            // Candidates list comes from the workspace scan, not the
            // local imports — for the message-side suggestion.
            // Today's implementation walks `import_names`, which is
            // empty here, so candidates is empty. (If a future
            // refactor changes this to scan all workspace modules,
            // adjust the assertion.)
            assert!(candidates.is_empty(),
                "no imports => no candidates; got {candidates:?}");
        }
        other => panic!("expected BareCrossModuleTypeRef, got {other:?}"),
    }
}
```

(Adjust the helper-call shape to match the existing helpers in the test module. The point: a `m` whose `imports` is empty but whose body references bare `Ordering`.)

- [ ] **Step 6: Verify all `ailang-core` workspace tests pass**

Run: `cargo test --workspace -p ailang-core ct1_validator`
Expected: PASS — all 6+ `ct1_validator_*` tests green, including the new acceptance test and the renamed rejection test.

Run: `cargo test --workspace -p ailang-core 2>&1 | tail -25`
Expected: zero new failures across the full crate suite.

---

### Task 3: CLI diagnostic-rendering update + ct1_check_cli assertion

**Files:**

- Modify: `crates/ail/src/main.rs:1249-1278` (`workspace_error_to_diagnostic` arms for `BareCrossModuleTypeRef` and `BadCrossModuleTypeRef`)
- Modify: `crates/ail/tests/ct1_check_cli.rs:154-157` (the migration-command-hint assertion)
- Modify: `examples/test_ct1_bare_xmod_rejected.ail.json` (if it lacks an explicit prelude import — see Step 1)

- [ ] **Step 1: Inspect the existing `test_ct1_bare_xmod_rejected.ail.json` fixture**

Run: `cat examples/test_ct1_bare_xmod_rejected.ail.json | python3 -m json.tool | head -40`
Expected: a module whose body references bare `Ordering` with no `(import prelude)` declaration. This is the still-RED case for `BareCrossModuleTypeRef` post-prep.1 (because `prelude` is in `implicit_imports`, the implicit path would normally let the type through — verify whether the current fixture's `imports` array is empty AND whether the workspace test runner injects prelude implicitly). If after Task 2 the existing fixture starts producing exit-0 instead of exit-non-zero, switch the fixture to a still-rejecting case: bare `Mystery_Type` (a name no module declares). Either way, the CLI test's intent is preserved: a human-mode error path must fire on a still-RED case.

- [ ] **Step 2: Update the human-mode assertion in `ct1_check_cli.rs:154-157`**

Replace lines 154-157 of `crates/ail/tests/ct1_check_cli.rs`:

```rust
    assert!(
        stderr.contains("not in scope"),
        "expected the narrowed not-in-scope wording in stderr; got {stderr}"
    );
```

(The old assertion was `stderr.contains("ail migrate-canonical-types")` — that hint is removed in Task 2 Step 4.)

- [ ] **Step 3: Update the `workspace_error_to_diagnostic` arms in `main.rs`**

`main.rs:1249-1263` (the `BareCrossModuleTypeRef` arm) — adjust the user-facing message string in the diagnostic body to mirror the new `#[error(...)]` wording. The arm constructs a `Diagnostic` with `message`, `code`, `ctx`. The `message` field is what `--json` consumers see; the `thiserror::Display` impl drives the human-mode stderr (which is what Step 2's assertion covers).

If the existing arm builds `message` by formatting strings other than the `WorkspaceLoadError`'s own `Display`, update the format string to match: drop the `ail migrate-canonical-types` reference; add the import-or-type-scoped-form suggestion. If the arm just delegates to `err.to_string()`, no edit is needed (the `#[error(...)]` change at workspace.rs:320 already carries through).

`main.rs:1266-1278` (the `BadCrossModuleTypeRef` arm) — symmetric treatment.

- [ ] **Step 4: Verify ct1_check_cli.rs passes**

Run: `cargo test --workspace -p ail --test ct1_check_cli`
Expected: PASS — all tests in that file. `check_human_mode_emits_actionable_message_to_stderr` (line 139) now asserts on `"not in scope"` and `"Ordering"`, both of which are in the new message.

- [ ] **Step 5: Regression check across the `ail` crate**

Run: `cargo test --workspace -p ail 2>&1 | tail -25`
Expected: zero new failures.

---

### Task 4: Migrate 12 `.ail` example fixtures to type-scoped form

**Files:**

- Modify: `examples/ct_2_bare_cross_module.ail`
- Modify: `examples/ct_3b_bad_qualified_known_module.ail`
- Modify: `examples/nested_pat.ail`
- Modify: `examples/std_either_demo.ail`
- Modify: `examples/std_either_list.ail`
- Modify: `examples/std_either_list_demo.ail`
- Modify: `examples/std_list.ail`
- Modify: `examples/std_list_demo.ail`
- Modify: `examples/std_list_more_demo.ail`
- Modify: `examples/std_list_stress.ail`
- Modify: `examples/std_maybe_demo.ail`
- Modify: `examples/std_pair_demo.ail`

**Rewrite rules** (apply consistently across all 12 files):

| Old form | New form | Notes |
|---|---|---|
| `(con std_X.Y ...)` in type position | `(con Y ...)` | Type-position; bare type-name now in scope via existing `(import std_X)`. |
| `(term-ctor std_X.Y Ctor ...)` | `(term-ctor Y Ctor ...)` | Same — bare type-name in term-ctor head. |
| `(pat-ctor std_X.Y Ctor ...)` | `(pat-ctor Y Ctor ...)` | Same — bare type-name in pat-ctor head (if any occurrence exists). |
| `(app std_X.fn ...)` where `fn` is type-associated to a single type `T` | `(app T.fn ...)` | Type-scoped function reference; e.g. `std_maybe.from_maybe` → `Maybe.from_maybe`. |
| `(app std_X.fn ...)` where `fn` is a free-standing combinator (no single receiver type, e.g. `std_either_list.partition_eithers`) | Keep as `(app std_X.fn ...)` | Module-as-receiver form retained for free-standing defs. |

**Type-association lookup table** (per-module — implementer references when classifying fns):

| Module | Type-associated fns (rewrite prefix → type name) | Free-standing fns (keep module prefix) |
|---|---|---|
| `std_maybe` | `from_maybe`, `is_some`, `is_none`, `map_maybe`, ... — all map to `Maybe.*` | (none expected) |
| `std_either` | `is_left`, `is_right`, `map_left`, `map_right`, `either`, `from_left`, `from_right`, ... — all map to `Either.*` | (none expected) |
| `std_list` | `head`, `tail`, `length`, `map`, `filter`, `foldl`, `foldr`, `append`, ... — all map to `List.*` | (none expected) |
| `std_pair` | `fst`, `snd`, `swap`, `map_first`, `map_second`, ... — all map to `Pair.*` | (none expected) |
| `std_either_list` | (none — module exists to host combinators on Either×List) | `partition_eithers`, `lefts`, `rights`, ... — all stay as `std_either_list.*` |

If a fn's home module declares it without a clear single receiver type, leave the module-scoped form. The implementer reads each `std_X.ail` to confirm the per-fn signature when in doubt.

- [ ] **Step 1: Sweep all 12 files with the rewrite rules**

For each of the 12 files listed under "Files" above, open in editor and apply the rewrites mechanically. Order: easiest first (`std_maybe_demo.ail` and `std_pair_demo.ail` have the cleanest mappings; `std_either_list_demo.ail` has the most mixed cases).

Notes on the two negative-fixture files:

- `examples/ct_2_bare_cross_module.ail` (lines 14-31): this file's CURRENT role is a NEGATIVE fixture pinning the old "bare type-name rejected" behaviour. Post-prep.1, the bare form is no longer the violation — but the file's role can be preserved by keeping it WITHOUT an `(import std_maybe)` declaration. With no import, bare `Maybe` falls through `check_type_con_name`'s new scope check and still fires `BareCrossModuleTypeRef` (narrowed message). The fixture's role flips from "bare-rejected-always" to "bare-rejected-when-not-imported"; the rejection itself is preserved.

- `examples/ct_3b_bad_qualified_known_module.ail` (lines 12-16): this fixture references `std_maybe.Widget` (known module, unknown type). Post-prep.1, this still fires `BadCrossModuleTypeRef` — the qualified-form rejection path is unchanged structurally (the spec only widens the bare-form path). Verify by `ail check examples/ct_3b_bad_qualified_known_module.ail` after Task 2 lands; if the diagnostic still fires with the new message, no rewrite is needed for this file.

- [ ] **Step 2: Run e2e to verify all 12 fixtures still build and check cleanly (or fail as expected for the two negatives)**

Run: `cargo build --release --bin ail && cargo test --workspace -p ail --test e2e 2>&1 | tail -40`
Expected: zero new failures. The 10 positive fixtures (everything except `ct_2_*` and `ct_3b_*`) check clean; the two negatives produce their expected diagnostics. If a fixture fails because a rewrite missed an occurrence, fix the fixture and re-run.

- [ ] **Step 3: Round-trip sanity (Form-A printer symmetry)**

Run: `cargo test --workspace -p ailang-surface round_trip 2>&1 | tail -15`
Expected: PASS. The Form-A round-trip is invariant under the rewrites (bare type-names print and re-parse identically; the parser layer doesn't change in prep.1).

---

### Task 5: Vocabulary cleanup in source-side doc-comments

**Files:**

- Modify: `crates/ail/tests/e2e.rs` — test-fn doc-comments referencing `std_list.List<a>`-style vocabulary
- Modify: `crates/ailang-check/src/lib.rs` lines 2513, 2520, 2538, 2560, 2953, 3372, 3864, 5234, 5240, 5246, 6878 — doc-comments using `std_list.length`-as-canonical-example wording (the `parse_method_qualifier` doc-comment at 2513-2540 stays — it describes the module-as-receiver fallback path which is still valid, but the canonical example is updated to mention type-scoped first)
- Modify: `crates/ailang-check/src/lift.rs:71` — single doc-comment mentioning `std_list.List Int`
- Modify: `crates/ailang-check/src/mono.rs:1034` — single doc-comment naming `std_list.length`
- Modify: `crates/ailang-codegen/src/lib.rs:3444` — single doc-comment about `std_list.List<...>` qualification
- Modify: `crates/ailang-codegen/src/subst.rs:157` — single doc-comment about `std_maybe.Maybe<Int>` unification
- KEEP UNCHANGED: `crates/ailang-surface/src/lex.rs:20, 320, 328` — these are tokenizer-level (the tokenizer doesn't distinguish type-scoped vs module-scoped; the test at line 320 asserts `"std_list.map"` tokenizes as one ident, which remains true)
- KEEP UNCHANGED: `crates/ailang-check/src/lib.rs:6518-6519` — `parse_method_qualifier` test bodies (pure string-split assertion, semantics-neutral)

- [ ] **Step 1: Sweep each file for `std_(maybe|either|list|pair).` references in doc-comments**

For each file in the modify-list, open and search for `std_X.` patterns in `///` or `//!` doc-comments. Reword to use type-scoped vocabulary as the canonical form, mentioning module-as-receiver as the fallback for free-standing fns.

Example before/after for `crates/ailang-check/src/mono.rs:1034`:

```
// Before:
/// the canonical free-fn call example: `std_list.length`. The
/// mono pass synthesises a body that ...

// After:
/// the canonical free-fn call example: `List.length` (type-scoped).
/// The mono pass synthesises a body that ...
```

The exact reword is a judgement call per site; the goal is to drop misleading "this is the canonical form" claims attached to the old vocabulary while preserving accurate descriptions of resolution mechanics (the `parse_method_qualifier`-anchored comments must still describe the module-as-receiver path, which exists for free-standing fns).

- [ ] **Step 2: Verify nothing compiled around those doc-comments broke**

Run: `cargo build --workspace 2>&1 | tail -10`
Expected: 0 errors. Doc-comment edits are non-load-bearing.

- [ ] **Step 3: Verify the full workspace test suite is clean**

Run: `cargo test --workspace 2>&1 | tail -25`
Expected: zero new failures across all crates. This is the iter-level smoke gate; if it's red, fix before the implementer declares DONE.

---

## Self-review (planner Step 5)

1. **Spec coverage:** every prep.1 spec subsection has a task —
   - resolver change → Task 1
   - two new diagnostics → Task 1
   - type-position narrowing → Task 2
   - diagnostic-message narrowing → Task 2
   - CLI-side updates → Task 3
   - 12 fixture rewrites → Task 4
   - source-side vocabulary → Task 5

2. **Placeholder scan:** searched for "TBD", "TODO", "implement later", "similar to", "add appropriate". No hits in the body of this plan. (The phrase "similar to Task N" does not appear; Task 4's rewrite rules are explicit per file, not "similar to Task 1's" or such.)

3. **Type consistency:** `TypeScopedMemberNotFound` (with fields `type_name`, `member`, `home_module`) and `TypeScopedReceiverNotAType` (with field `name`) are spelled identically in Task 1 Step 3 (variant declaration), Step 1 (test assertions), and Step 4 (resolver-side emission). `BareCrossModuleTypeRef` and `BadCrossModuleTypeRef` retain their spellings across Tasks 2-3.

4. **Step granularity:** each step is bite-sized (2-5 minutes typical; a couple of the resolver-write steps push to ~8 minutes, but they're single coherent edits, not multi-decision composites).

5. **No commit steps:** zero `git commit` instructions appear. Implement leaves work in the working tree.

6. **Pin/replacement substring contiguity:** Task 3 Step 2's verbatim assertion replacement (`stderr.contains("not in scope")`) IS the substring the new `#[error(...)]` body in Task 2 Step 4 contains. The phrase "not in scope" appears contiguously in the workspace.rs `#[error(...)]` string at the same line (no line-wrap split).

7. **Compile-gate vs. deferred-caller ordering:** the new `CheckError` variants in Task 1 Step 3 are an additive enum change; Rust's exhaustiveness check forces the `code()` arms to be added in the same step (which they are). The new variants are not yet emitted until Step 4 — `cargo check` at Step 3 succeeds with `#[allow(dead_code)]`-equivalent silence (Rust does not warn on unused enum variants in pub enums). No compile-gate is set against unused emission. The Task-2 changes to `check_type_con_name` and `#[error(...)]` strings touch the same workspace.rs file; the in-source mod tests at lines 1820-1983 ARE callers and ARE updated in the same task (Step 5), so the compile-gate-vs-caller rule is satisfied.

8. **Verification-command filter strings:**
   - `cargo test --workspace -p ailang-check type_scoped_` — Task 1 Steps 2/5 — filter resolves to the three NEW test functions named `type_scoped_member_resolves`, `type_scoped_member_not_found`, `type_scoped_receiver_not_a_type` (all defined in Step 1). After Step 1 lands, the filter matches three tests. At Step 2 (before Step 3-4 land) the filter matches the tests in compile-failed state; at Step 5 they're green.
   - `cargo test --workspace -p ailang-core ct1_validator_accepts_bare_with_explicit_import` — Task 2 Step 2 — filter resolves to the NEW test named exactly that (defined in Step 1). One test matched.
   - `cargo test --workspace -p ailang-core ct1_validator` — Task 2 Step 6 — filter matches all existing `ct1_validator_*` tests (verified ≥6 tests in `workspace.rs:1820-1983`) PLUS the new acceptance test. Result count ≥7.
   - `cargo test --workspace -p ail --test ct1_check_cli` — Task 3 Step 4 — `--test ct1_check_cli` resolves to `crates/ail/tests/ct1_check_cli.rs` (verified file exists).
   - `cargo test --workspace -p ail --test e2e` — Task 4 Step 2 — `--test e2e` resolves to `crates/ail/tests/e2e.rs` (verified file exists, contains `build_and_run` test runner).
   - `cargo test --workspace -p ailang-surface round_trip` — Task 4 Step 3 — filter matches the round-trip tests in `crates/ailang-surface/tests/round_trip.rs` (verified file exists).
   - `cargo build --workspace 2>&1 | tail -10` and `cargo test --workspace 2>&1 | tail -25` — Task 5 Steps 2-3 — unfiltered, count-based assessment via tail output.

All filter strings resolve to ≥1 named target in the current tree.

## Handoff

Plan sits in the working tree at `docs/plans/0101-prep.1-type-scoped-namespacing.md`. Hand off to `skills/implement` with: path to this plan; no task-range focus (run all 5 tasks in sequence). Iter-completion commit body closes #31.
