AILang/docs/specs/0021-ct-tidy.md

Canonical-Type-Names Tidy Sweep — Design Spec

Date: 2026-05-12 Status: Draft — awaiting user spec review Authors: Brummel (orchestrator) + Claude

Goal

Close three follow-up todos that the canonical-type-names milestone (ct.1 → ct.4, closed 2026-05-11) explicitly deferred or surfaced. All three touch workspace / env / registry mechanics and share the theme "structural gaps the canonical-type-names milestone declared out-of-scope". Bundling them into one tidy milestone keeps the closeout coherent rather than scattering three orphan tidy patches across the next several weeks.

The three items:

1. env-overlay shape ratification + narrowing. Decide whether the env's parallel types / ctor_index maps should collapse into one overlay or stay split, anchor the decision in docs/DESIGN.md, and narrow check_in_workspace's per-module overlay rebuild symmetric to ct.3.2's mono-side fix.
2. Registry.type_def_module re-key. Replace the BTreeMap<String, String> keyed by bare type name with a key that survives cross-module bare-name collisions.
3. KindMismatch retire. Delete the WorkspaceLoadError::KindMismatch variant and walk_kind_mismatch helper — structurally unreachable post-ct.1, ratified by the already-green test class_param_in_applied_position_fires_canonical_form_rejection at crates/ailang-core/src/workspace.rs:1867.

Items deliberately not in scope: CLI human-mode diagnostic surface for WorkspaceLoadError (different layer — diagnostic routing, not workspace mechanics); Split BadCrossModuleTypeRef (diagnostic shape); Workspace search beyond entry-module's directory (CLI / IO layer); io/print_float .0 fallback (runtime printer asymmetry); Boehm retirement (memory subsystem); rustdoc warning sweep (documentation). Each of these is a coherent tidy in its own right but does not share the workspace-mechanics theme.

Architecture

The milestone is three iterations, ordered from highest-design- substance to lowest. The order is deliberate: the env-overlay decision in ctt.1 is the only one carrying a real choice, so it happens first while the design context is fresh. ctt.2 and ctt.3 are mechanical follow-ups whose shape does not depend on ctt.1.

Iteration ctt.1 — env-overlay shape ratification + narrowing

Design substance: Today Env carries two parallel maps that are rebuilt in lockstep:

• env.types: IndexMap<String, TypeDef> — bare-type-name → full TypeDef. The owning index for type definitions.
• env.ctor_index: IndexMap<String, CtorRef> — bare-ctor-name → owning-type-name. A reverse index over env.types.

The "shape question" from docs/journals/2026-05-10 ("Audit close: env-construction unify") is: collapse into one overlay (Map<Name, EntryKind> with Type(TypeDef) | Ctor(owner)) or stay split?

Decision: stay split. Reason (semantic, not effort): the two maps have distinct semantic roles. env.types is an owning index — it stores the data. env.ctor_index is a reverse index — it accelerates ctor-name → type-name lookup over the same data. A collapsed variant-keyed map would conflate these roles and force every consumer to discriminate EntryKind at the call site. The current split lets type-consumers iterate env.types directly and ctor-consumers query env.ctor_index directly; neither needs to know the other exists.

This rationale gets anchored in docs/DESIGN.md as a new top-level section ## Env construction, placed between the existing ## Convention: qualified cross-module references (docs/DESIGN.md:1941) and ## Data model (docs/DESIGN.md:1959). DESIGN.md today has no env / overlay section, so this iter introduces the heading. The initial body is one short paragraph naming the split (env.types owning vs. env.ctor_index reverse-index) with the rationale above; future env / overlay mechanics can extend the section without re-anchoring. Future tidies cannot re-litigate the split without first amending this section.

Code change: one new pinning test. The DESIGN.md anchor is the primary deliverable, plus the roadmap close. The iter also adds one positive test that pins the load-bearing DuplicateCtor consumer, because the in-band check at crates/ailang-check/src/lib.rs:1366-1376 has no in-tree test ratifying it today (the variant is emitted in the production code path but no fixture currently triggers it). The pinning test is what makes the ratification load-bearing rather than documentation-of-belief — the asymmetry-with-mono-side argument rests on this consumer being real.

Inspection of the existing per-module rebuild at crates/ailang-check/src/lib.rs:1342-1384 confirms both halves are load-bearing:

• env.types.clear() + rebuild: needed for the local DuplicateType diagnostic at lib.rs:1358-1364 and for bare-name Type::Con lookup against the current module.
• env.ctor_index.clear() + rebuild: emitted into the in-band DuplicateCtor diagnostic at lib.rs:1366-1376, which consults the rebuilt per-module env.ctor_index to detect duplicates within the current module. The new pinning test is the consumer evidence.

The ct.3.2 mono-side fix narrowed the mono overlay because the mono-side env.ctor_index was only feeding runtime ctor lookup (type-driven post-ct.2.2). The check-side overlay is shaped differently — it serves the workspace-build-time duplicate diagnostic — so the analogous narrowing does not apply.

The roadmap todo "check_in_workspace per-module overlay narrowing" closes via this finding: the rebuild stays, the asymmetry with the mono-side is intentional and now documented. The roadmap todo "types / ctor_index overlay shape question" closes via the DESIGN.md anchor recording the split rationale.

If a future recon surfaces a non-DuplicateCtor consumer of the post-rebuild env.ctor_index that could survive removal of the per-module rebuild, the question re-opens; until then the ratification holds.

Iteration ctt.2 — Registry.type_def_module re-key

Bug being closed: crates/ailang-core/src/workspace.rs:106 declares type_def_module: BTreeMap<String, String>. Today this map is bare-name → defining-module. The doc-comment at workspace.rs:97-105 flags the issue: if two modules each declare type Foo, the second insert at workspace.rs:547 silently overwrites the first; subsequently normalize_type_for_registry (workspace.rs:892) qualifies Foo to whichever module won the insert race.

For the current corpus (every in-tree fixture uses distinct bare type names across modules) the bug is dormant. The proper fix is explicitly written into the doc-comment: re-key as (owning_module, bare_name) -> defining_module and thread the calling module through every consumer site.

Re-keying choice. Two shapes are conceivable:

• BTreeMap<(String, String), String> keyed by (owning_module, bare_name) — straightforward extension.
• BTreeMap<String, Vec<(String, String)>> keyed by bare name, value being a list of (owner, defining_module) pairs — preserves the bare-name-as-primary-lookup intuition but forces every consumer to handle the multi-candidate case.

Decision: tuple key. Reason (semantic): the function the map serves — "given a type reference written in module M, where is its type defined?" — already requires the owning module M as input. The tuple key makes that input explicit at the API surface. The list-valued alternative would defer multi-candidate handling to every consumer.

Consumer site count. grep "type_def_module" returns 13 hits in workspace.rs. Most are inside the workspace-load function where the calling module is local context (loop variable mod_name), so threading is trivial. The interesting site is normalize_type_for_registry at workspace.rs:879-928, which today takes type_def_module: &BTreeMap<String, String> as a parameter. The signature changes to accept the calling module as well, and the map type changes to &BTreeMap<(String, String), String>. All call sites already have the calling module in scope (the workspace-load loop threads it through mod_name).

The Registry::normalize_type_for_lookup method at workspace.rs:121-123 exposes normalize_type_for_registry publicly without a calling-module argument. The signature gains a caller_module: &str argument. The two test-only call sites at workspace.rs:2525, 2549 use synthetic modules; both update trivially.

Test: add a positive fixture where two modules each declare type Foo with distinct ctors, an instance on each, and confirm both instances resolve correctly under registry lookup. This catches the regression: under the old bare-name key, one of the two instances would silently lose its registry entry.

Iteration ctt.3 — KindMismatch retire

Path being deleted:

• WorkspaceLoadError::KindMismatch variant (crates/ailang-core/src/workspace.rs:259-264).
• walk_kind_mismatch helper (crates/ailang-core/src/workspace.rs:834-854).
• Dispatch site in validate_classdefs (crates/ailang-core/src/workspace.rs:786-795).
• Display arm in crates/ail/src/main.rs:1163 for the human-mode diagnostic.

Ratification: Already-green test class_param_in_applied_position_fires_canonical_form_rejection (crates/ailang-core/src/workspace.rs:1867-1888) demonstrates that the malformed shape class C f { foo : f Int -> f Int } fires BareCrossModuleTypeRef before validate_classdefs runs. This is the structural-unreachability claim made by the roadmap entry, ratified by a workspace-loaded test that currently passes.

The test must keep passing after the deletion. It asserts on BareCrossModuleTypeRef, not KindMismatch, so no test edit is required.

Defensive vs. retired: The doc comment at workspace.rs:1858-1866 reads "stays in the codebase as dead-but-defensive code; a future tidy may retire it." This iter is that future tidy. The "defensive" framing was a deliberate hedge during ct.1 in case a canonical-form bug let malformed shapes through later — none has surfaced. Carrying the dead branch indefinitely is itself a hazard: future refactors of the workspace error-enum touch shapes that no code path produces. Retire now, before the dead branch accumulates churn.

If a future canonical-form bug does let a malformed shape through, the right repair is to fix the canonical-form validator, not to resurrect KindMismatch. The diagnostic that fires today (BareCrossModuleTypeRef) is structurally correct: a class param f used as f Int is, post-ct.1, a reference to a non-existent type f in the owning module — that is a bare-cross-module type ref. The earlier KindMismatch diagnostic was a less-precise pre-ct.1 framing.

Components

Files touched per iter

ctt.1 — env-overlay shape ratification + DuplicateCtor pin:

• docs/DESIGN.md — new top-level section ## Env construction inserted between ## Convention: qualified cross-module references (line 1941) and ## Data model (line 1959). Initial body: one paragraph naming the env.types / env.ctor_index split with the owning-vs-reverse-index rationale.
• crates/ailang-check/tests/ — new test (path TBD by planner — candidate: a new file duplicate_ctor_pin.rs, or appended to an existing fixture-driven test module) that builds a one- module fixture with two Def::Types declaring same-named ctors and asserts check_workspace returns CheckError::DuplicateCtor { ctor, a, b }. The exact assertion path follows the existing CheckError-asserting test conventions in the crate.
• docs/roadmap.md — strike both relevant todo lines ("types / ctor_index overlay shape question" and "check_in_workspace per-module overlay narrowing") with a reference to docs/journals/<this iter>.md.

ctt.2 — Registry.type_def_module re-key:

• crates/ailang-core/src/workspace.rs:106 — field type change to BTreeMap<(String, String), String>.
• crates/ailang-core/src/workspace.rs:121-123 — Registry::normalize_type_for_lookup gains caller_module: &str.
• crates/ailang-core/src/workspace.rs:537, 547 — Pass 1 collection: insert (mod_name.clone(), t.name.clone()) instead of t.name.clone().
• crates/ailang-core/src/workspace.rs:656-657 — type_def_module.get(&type_repr) becomes a per-module-aware lookup (the call-site context provides mod_name).
• crates/ailang-core/src/workspace.rs:879-928 — normalize_type_for_registry signature + body adapt to tuple key + caller_module argument.
• crates/ailang-core/src/workspace.rs:2525, 2549 — test-only call sites update.
• crates/ailang-core/src/workspace.rs:97-105 — doc-comment flagging the bug is replaced with the new shape's invariant.
• New test fixture: examples/ct_tidy_cross_module_foo_collision.ail.json (or analogous), exercising two-module bare-name collision.
• crates/ailang-core/tests/ or crates/ail/tests/e2e.rs — test that exercises the new fixture and asserts both instances resolve correctly.

ctt.3 — KindMismatch retire:

• crates/ailang-core/src/workspace.rs:259-264 — variant deletion.
• crates/ailang-core/src/workspace.rs:786-795 — dispatch site deletion (the walk_kind_mismatch(&method.ty, &c.param) call inside validate_classdefs).
• crates/ailang-core/src/workspace.rs:834-854 — helper deletion.
• crates/ail/src/main.rs:1163 — Display arm deletion.
• crates/ailang-core/src/workspace.rs:1858-1866 — the "dead-but-defensive" doc comment on the existing test gets dropped (the test stays; its rationale is now "the canonical-form rejection is the path", which the test name already states).

Files NOT touched

• crates/ailang-check/src/lib.rs:1342-1384 — the per-module overlay rebuild stays as-is after ctt.1's recon confirms DuplicateCtor depends on it. The narrowing question closes via DESIGN.md ratification, not code change. If planner-recon for ctt.1 surfaces a consumer that would survive narrowing, this changes; default expectation is no edit here.
• crates/ailang-codegen/ — no codegen edits. None of the three items touch IR or runtime.
• Snapshots — no IR-shape snapshots are affected. The bench baseline is not affected (no codepath frequency change).

Data flow

The three iters do not interact at the data level:

• ctt.1 records a decision in DESIGN.md; no code-side data flow change.
• ctt.2 changes the registry's internal key shape but preserves the public Registry::normalize_type_for_lookup semantics for every call site that already has its calling module in scope. External canonical-form behaviour is unchanged for the current corpus (which has no bare-name collisions); the fix is load-bearing only when a future workspace introduces a collision.
• ctt.3 deletes an unreachable branch; no data flow.

Canonical-form bytes: unchanged. None of the three iters touches serialised AST shapes. ctt.2's registry-key change is internal — the canonical-form output of normalize_type_for_registry for any valid input is the same as today (the bug surfaces only on the malformed-collision input that the current corpus doesn't contain, and the new behaviour is "qualify to the correct owner" rather than "qualify to whichever module won the race", which is by definition a fix not a shape change).

Error handling

ctt.1: no new diagnostics. The ratification is documentation- only at the analyser level.

ctt.2: no new diagnostics. The DuplicateInstance / OrphanInstance paths at workspace.rs:682, 660 already cover the collision-error space; the re-key fixes the silent collision by ensuring the right registry entry survives, which means a previously-masked instance becomes visible to the existing DuplicateInstance detector when its canonical-form key matches another (and is not falsely promoted to "duplicate" when it actually belongs to a different owner).

ctt.3: one diagnostic variant goes away. The Display path in main.rs:1163 deletes the human-mode [kind-mismatch] line; the structurally-identical class-param-in-applied-position malformed shape now produces [bare-cross-module-type-ref] instead. Existing user-facing diagnostic for the canonical malformed-fixture is the latter (the existing test confirms this).

Testing strategy

ctt.1:

• New pinning test: one-module fixture with two Def::Types declaring same-named ctors. Asserts check_workspace returns CheckError::DuplicateCtor { ctor, a, b } with a and b naming the two types. Catches any future regression that silently removes the per-module env.ctor_index rebuild — if the rebuild goes away, this test goes red, which is exactly the load-bearing-asymmetry-argument's safety net.
• cargo test --workspace continues to pass with all other tests unchanged.
• DESIGN.md anchor presence verified manually (no schema-drift test exists for the env section yet — see roadmap item "design_schema_drift.rs fidelity widening", out-of-scope here).
• Roadmap close: both relevant lines struck through.

ctt.2:

• New fixture: two modules each declaring type Foo with distinct ctors; an instance on each. Test: both instances registerable, both retrievable by their canonical-form registry key, no DuplicateInstance false positive, no silent overwrite.
• Existing test suite must continue to pass (no current fixture exercises the collision case, so no existing test regresses).

ctt.3:

• Existing test class_param_in_applied_position_fires_canonical_form_rejection (crates/ailang-core/src/workspace.rs:1867) continues to pass, asserting BareCrossModuleTypeRef on the malformed fixture.
• cargo test --workspace continues to pass (no other test references KindMismatch — grep KindMismatch returns the three deletion sites only).
• cargo build --workspace succeeds (no orphan match arms, no dead-code warnings introduced).

Workspace-wide gate (all three iters):

• bench/cross_lang.py, bench/compile_check.py, bench/check.py all green. No metric should plausibly shift, but the audit at milestone close confirms.

Acceptance criteria

• docs/DESIGN.md carries a new top-level section ## Env construction (placed between ## Convention: qualified cross-module references and ## Data model) whose initial paragraph anchors the env.types / env.ctor_index split with the semantic rationale (owning index vs. reverse index).
• A new pinning test in crates/ailang-check/tests/ (path finalised in planning) asserts CheckError::DuplicateCtor fires for a one-module fixture with two Def::Types declaring same-named ctors — ratifies the consumer the ctt.1 ratification rests on.
• Registry.type_def_module key is (String, String), value is String. Every consumer site provides the calling module at the call site. A regression test exercises two-module bare-name collision and confirms both instances resolve correctly.
• WorkspaceLoadError::KindMismatch, walk_kind_mismatch, its dispatch site, and its main.rs Display arm are deleted. The existing test class_param_in_applied_position_fires_canonical_form_rejection still passes, asserting BareCrossModuleTypeRef.
• cargo test --workspace, bench/cross_lang.py, bench/compile_check.py, bench/check.py all green at milestone close.
• docs/roadmap.md has the three relevant todo lines struck through with reference to this spec or the per-iter journals.
• docs/WhatsNew.md carries one entry covering the milestone in user-as-reader prose (no internals, no iter codes).