AILang/docs/journals/2026-05-12-audit-ct-tidy.md

audit-ct-tidy — Milestone close: ct-tidy (closing iter ctt.3)

Date: 2026-05-12 Milestone: ct-tidy (ctt.1 + ctt.2 + ctt.3) Status: Closed, three doc-drift items fixed inline (ctt.tidy)

Architect drift review

ailang-architect reported drift_found across the commit range 805bba3..0d3f44b. Code-side changes match DESIGN.md / spec / iters; three doc-side drift items surfaced (two high, one low; one medium is acceptable per spec).

[high — spec acceptance] docs/DESIGN.md:1735-1736 — KindMismatch listed as a live class-schema diagnostic. Stale since ctt.3.

[high — spec acceptance] docs/DESIGN.md:1761-1763 — KindMismatch cited as the rejection mechanism for higher-kinded class params. Stale since ctt.3.

[high — spec acceptance] docs/roadmap.md:91-97 — the KindMismatch retire todo unchecked with no forward-reference to ctt.3. Spec acceptance criterion called for strikes on the relevant todo lines; ctt.3 struck none.

[medium — record-keeping] examples/test_22b2_kind_mismatch.ail.json keeps the retired-diagnostic-name in its filename. Spec is silent (acceptable as-is); rename is a future candidate, not in this audit's scope.

[low — numerical drift] Spec claim "grep type_def_module returns 13 hits" is now 18 hits post-ctt.2. Intent honoured (every consumer threaded); numerical figure is historical.

Tidy fixes applied inline (ctt.tidy)

All three high-severity items addressed in this audit commit (Boss-mechanical edits — three doc edits, no separate plan / implement dispatch warranted):

1. docs/DESIGN.md:1733-1740 — dropped the KindMismatch bullet from the class-schema diagnostics list; added a successor paragraph naming BareCrossModuleTypeRef as the structural rejection path for the malformed class-param-in-applied-position shape; cross-references iter ctt.3.

2. docs/DESIGN.md:1761-1763 — rewrote the "Higher-kinded class params" bullet under "What this typeclass design explicitly does NOT support" to name BareCrossModuleTypeRef from canonical-form validation instead of KindMismatch at class declaration.

3. docs/roadmap.md:91-97 — struck [x] with a forward-reference to ctt.3 (canonical-form-rejection test stays green asserting BareCrossModuleTypeRef). Adjacent ctt.2 todo at lines 98-105 also struck (mechanical follow-up — ctt.2 closed the re-key it tracks).

Medium / low items skipped: filename rename + spec numerical claim both fall outside ctt.tidy's scope (spec acceptance was on intent-honour, not figure-precision; filename rename is a future candidate the spec already permits as-is).

Bench-regression check

Sequence run as Boss (the && chain tripped at check.py's exit 1; compile_check.py and cross_lang.py then ran separately):

• check.py: exit 1 — 63 metrics; 3 regressed, 3 improved beyond tolerance, 57 stable.
  • Regressions:
    • bench_list_sum.bump_s +12.23% (tol 10%) — second consecutive sighting (audit-eob first-sighted this at +12.60%, this audit at +12.23%).
    • latency.explicit_at_rc.max_us +44.31% (tol 25%) — first sighting, rc-cohort tail-latency.
    • latency.implicit_at_rc.max_us +35.07% (tol 30%) — first sighting, rc-cohort tail-latency.
  • Improvements:
    • bench_list_sum.gc_over_bump -10.40% — mirror of the bump_s regression (gc/bump ratio falls because bump rose).
    • bench_closure_chain.gc_over_bump -15.05% — new improvement.
    • bench_list_sum_explicit.gc_over_bump -8.30% — new improvement.
• compile_check.py: exit 0; 24 metrics, all stable within ±25%.
• cross_lang.py: exit 0; 25 metrics, all stable within ±15%.

Classification

bump_s persistence (bench_list_sum.bump_s): second consecutive sighting (audit-eob → audit-ct-tidy) at near-identical magnitude (+12.60% → +12.23%). The audit-eob classification was "first-sighting rule — observe in the next audit; if it persists, investigate". This audit IS that next audit, and it persists.

ctt.* milestone made zero codegen-relevant edits (the three iters touched env-overlay doc + check-side registry key shape + workspace-load-time diagnostic deletion). No plausible attribution to ctt.*. The persistence is real but uncaptured — the underlying cause predates this milestone and is independent of the work in the audit window.

Conservative call (same standing rule as previous three audits): do not baseline-update. The persistence is now documented across two audits; if it persists into the next audit unchanged, ratify-without-attribution becomes the right call (at three consecutive sightings the noise hypothesis is unsupported). The latency tail-cluster regressions are first sightings — observe.

Latency max_us regressions (explicit_at_rc.max_us, implicit_at_rc.max_us): first sighting in any recent audit. Both metrics are rc-cohort tail-latency (the extreme-outlier window). The bench harness runs ~50ms workloads; a single outlier of +183µs (explicit) or +167µs (implicit) absolute moves the max_us proportionally. ctt.* made zero codegen edits, so the noise hypothesis is the most parsimonious explanation on first sighting.

Conservative call: first-sighting rule — do not baseline-update; observe in the next audit.

Recurring latency.explicit_at_rc improvement cluster: the three-audit-long improvement cluster on p99_us / p99_9_us / p99_over_median (previously at ~-37%, classified as ratify-candidate after one more audit at audit-eob) now reports within tolerance this audit:

• p99_us -24.87% (tol 25%) — stable (was: improvement)
• p99_over_median -24.10% (tol 25%) — stable (was: improvement)
• p99_9_us not flagged (within tolerance)

The cluster has narrowed from ~-37% improvements to ~-24% near-tolerance stable. The improvements partially reverted — the metrics are still on the improvement side, but no longer beyond tolerance. The audit-eob recommendation ("if the cluster persists into the next two audits unchanged, ratify; if it shifts or shrinks meaningfully, that is itself the attribution signal") has fired: the cluster shrank meaningfully this audit. This is itself attribution-evidence — the underlying cause is variable rather than persistent. The ratify-pending plan is withdrawn; the cluster is now noise-class, not signal-class.

Baseline left pristine on every script for the fourth consecutive audit. No --update-baseline invocation.

Status

Closed. Ct-tidy milestone fully landed:

• env-overlay shape ratified (ctt.1: DESIGN.md ## Env construction section + DuplicateCtor pinning test + 2 P2 todos closed).
• Registry.type_def_module re-keyed to (owning_module, bare_name) with caller_module threaded through every consumer (ctt.2: 3-module fixture + regression test).
• KindMismatch retired (ctt.3: variant + helper + dispatch + Display arm deleted; test stays green via canonical-form successor BareCrossModuleTypeRef).
• DESIGN.md tracks all three iters' anchors (ctt.tidy in this audit: class-schema diagnostics list updated, higher-kinded params bullet updated, ctt.3 retirement marker pattern).
• Roadmap reflects closure (ctt.tidy: two P2 todos struck [x]).

Working tree exits audit clean. main HEAD advances by exactly this audit commit.