# 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 (`.`) 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__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::(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::(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 = 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 = 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 )` to bring it into scope (candidates: {candidates:?}), \ or rewrite the call to type-scoped form `.`." )] ``` 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`-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` 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.