AILang/docs/plans/0005-22c-user-class-e2e.md

22c — User-class e2e fixture

Parent spec: docs/specs/0002-22-typeclasses.md

For agentic workers: REQUIRED SUB-SKILL: use skills/implement to run this plan. Steps use - [ ] checkboxes for tracking.

Goal: ship one .ail.json fixture exercising the typeclass machinery end-to-end through user-defined code (no Prelude involvement). Running ail build on the fixture and executing the binary prints 42.

Architecture: the fixture defines a user class Foo a with one method, a user ADT IntBox, and an instance Foo IntBox whose body matches on the ctor and returns the wrapped int. main calls foo (MkIntBox 42) and prints the result through io/print_int. The 22b.3 monomorphisation pass synthesises foo__<typehash> for Foo IntBox, rewrites the call site, and the existing match-lowering emits the body as ordinary code. No new compiler passes, no new runtime primitives, no new surface syntax.

Tech Stack: examples/ (one new fixture), crates/ail/tests/ (one new e2e test file). No production-code crates touched.

Out of scope: Prelude class for primitives (deferred per spec amendment 2026-05-09 §"22b.4b dropped"). Multiple instances per class, multi-method classes (test_22b3_coherence_two_instances and test_22b3_default_e2e already cover those).

---

Files this plan creates or modifies

• Create: examples/test_22c_user_class_e2e.ail.json — the fixture.
• Create: crates/ail/tests/typeclass_22c.rs — the e2e test (cargo test -p ail --test typeclass_22c). Asserts the binary prints 42\n.
• Modify: docs/JOURNAL.md — append iteration entry at iter close.

That is the entire iteration's surface. No code crate is modified, because 22b.3 already shipped every machine-code path the fixture exercises.

---

Cross-task invariants

1. No production-code changes. If a task requires editing anything under crates/*/src/ (other than tests), that is a sign of a hidden bug surfaced by the fixture — STOP and route through debug skill (RED-first), not through this plan.
2. No Prelude. The fixture defines its own class; do NOT import any examples/prelude*.ail.json (none exists yet anyway, but the discipline matters: 22c's property is "user-defined" end-to-end).
3. Bench gates green. Per spec acceptance criterion 2, bench/check.py / bench/compile_check.py / bench/cross_lang.py must all exit 0/0/0 at iter close.

---

Task 1: Author the fixture

Files:

• Create: examples/test_22c_user_class_e2e.ail.json

Step 1.1 — Write the fixture

Hand-write the canonical JSON. Schema validation via ail check catches any shape error in Step 1.2. Key shapes verified against existing fixtures: examples/box.ail.json (data-type + match + term-ctor), examples/test_22b3_default_e2e.ail.json (class + instance with (t: "lam") body), examples/borrow_own_demo.ail.json (param_modes: ["borrow"] snake_case).

{
  "schema": "ailang/v0",
  "name": "test_22c_user_class_e2e",
  "imports": [],
  "defs": [
    {
      "kind": "type",
      "name": "IntBox",
      "ctors": [
        { "name": "MkIntBox", "fields": [{ "k": "con", "name": "Int" }] }
      ]
    },
    {
      "kind": "class",
      "name": "Foo",
      "param": "a",
      "methods": [
        {
          "name": "foo",
          "type": {
            "k": "fn",
            "params": [{ "k": "var", "name": "a" }],
            "param_modes": ["borrow"],
            "ret": { "k": "con", "name": "Int" },
            "effects": []
          }
        }
      ]
    },
    {
      "kind": "instance",
      "class": "Foo",
      "type": { "k": "con", "name": "IntBox" },
      "methods": [
        {
          "name": "foo",
          "body": {
            "t": "lam",
            "params": ["b"],
            "paramTypes": [{ "k": "var", "name": "a" }],
            "retType": { "k": "con", "name": "Int" },
            "body": {
              "t": "match",
              "scrutinee": { "t": "var", "name": "b" },
              "arms": [
                {
                  "pat": {
                    "p": "ctor",
                    "ctor": "MkIntBox",
                    "fields": [{ "p": "var", "name": "v" }]
                  },
                  "body": { "t": "var", "name": "v" }
                }
              ]
            }
          }
        }
      ]
    },
    {
      "kind": "fn",
      "name": "main",
      "type": {
        "k": "fn",
        "params": [],
        "ret": { "k": "con", "name": "Unit" },
        "effects": ["IO"]
      },
      "params": [],
      "body": {
        "t": "do",
        "op": "io/print_int",
        "args": [
          {
            "t": "app",
            "fn": { "t": "var", "name": "foo" },
            "args": [
              {
                "t": "ctor",
                "type": "IntBox",
                "ctor": "MkIntBox",
                "args": [{ "t": "lit", "lit": { "kind": "int", "value": 42 } }]
              }
            ]
          }
        ]
      }
    }
  ]
}

Notes on canonical key shape:

• data def: kind: "type" (NOT "data").
• Pattern: {"p": "ctor", ...} / {"p": "var", ...} — discriminator field is "p", not "pattern" or "kind". Pattern's child patterns are under "fields", not "args".
• term-ctor: {"t": "ctor", "type": "IntBox", "ctor": "MkIntBox", "args": [...]} — the type name and the ctor name are sibling fields; do NOT use "t": "term-ctor".
• Instance method body's paramTypes references the class param variable a (not the concrete type IntBox). The mono pass substitutes a := IntBox when synthesising the per-instance function. Mirror the existing 22b.3 fixtures (test_22b3_coherence_two_instances shows paramTypes: [{"k": "var", "name": "a"}]).

Step 1.2 — Verify the fixture loads

cargo run -q -p ail -- check examples/test_22c_user_class_e2e.ail.json

Expected: exit 0, no diagnostics.

If ail check reports an error like unknown method "foo" or no-instance for Foo IntBox, that is a fixture bug — fix the JSON shape until check passes.

If ail check reports an internal error or panics, STOP and route through debug skill RED-first — that is a real compiler bug surfaced by 22c, not a fixture issue.

Step 1.3 — Verify the fixture compiles and runs

cargo run -q -p ail -- build examples/test_22c_user_class_e2e.ail.json -o /tmp/test_22c
/tmp/test_22c

Expected: stdout 42\n, exit 0.

If ail build errors during monomorphisation / codegen / linking, STOP and route through debug skill — the fixture proves a real compiler-side gap (most likely candidates: mono pass on instance where the type is a user ADT, or match-lowering inside a synthesised mono fn).

Step 1.4 — Commit the fixture

git add examples/test_22c_user_class_e2e.ail.json
git commit -m "iter 22c.1: fixture — user class + user ADT + instance, prints 42"

---

Task 2: E2E test

Files:

• Create: crates/ail/tests/typeclass_22c.rs

Step 2.1 — Write the e2e test

Use the same shape as crates/ail/tests/typeclass_22b3.rs's synthetic_fixture_runs_and_prints_five test (an existing precedent for "build + run a fixture and assert stdout"). Concretely:

//! Iter 22c: user-class end-to-end. The single 22c fixture defines a
//! user class `Foo`, a user ADT `IntBox`, an `instance Foo IntBox`,
//! and a `main` that calls `foo (MkIntBox 42)` through the
//! monomorphisation pass and prints the result via `io/print_int`.
//! This is the milestone-22 acceptance fixture for the user-class
//! path (no Prelude involvement).

use std::process::Command;

fn workspace_root() -> std::path::PathBuf {
    let manifest = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    manifest.parent().unwrap().parent().unwrap().to_path_buf()
}

#[test]
fn user_class_fixture_compiles_runs_and_prints_42() {
    let root = workspace_root();
    let fixture = root.join("examples/test_22c_user_class_e2e.ail.json");
    let out = root.join("target/test-22c/test_22c");
    std::fs::create_dir_all(out.parent().unwrap()).expect("mkdir");

    // Build
    let build = Command::new("cargo")
        .args([
            "run", "-q", "-p", "ail", "--",
            "build", fixture.to_str().unwrap(),
            "-o", out.to_str().unwrap(),
        ])
        .current_dir(&root)
        .output()
        .expect("spawn cargo run ail build");
    assert!(
        build.status.success(),
        "ail build failed:\nstdout:\n{}\nstderr:\n{}",
        String::from_utf8_lossy(&build.stdout),
        String::from_utf8_lossy(&build.stderr)
    );

    // Run
    let run = Command::new(&out)
        .output()
        .expect("spawn produced binary");
    assert!(
        run.status.success(),
        "binary returned non-zero:\nstdout:\n{}\nstderr:\n{}",
        String::from_utf8_lossy(&run.stdout),
        String::from_utf8_lossy(&run.stderr)
    );
    assert_eq!(
        String::from_utf8_lossy(&run.stdout).trim_end(),
        "42",
        "expected stdout `42` (with trailing newline)"
    );
}

If crates/ail/tests/typeclass_22b3.rs uses a different "build + run + capture stdout" idiom, mirror it instead — the project's existing convention takes priority over this template.

Step 2.2 — Run the test

cargo test -p ail --test typeclass_22c

Expected: 1 passed; 0 failed.

Step 2.3 — Run the full bench gate

python3 bench/check.py
python3 bench/compile_check.py
python3 bench/cross_lang.py

Expected: all three exit 0/0/0.

Step 2.4 — Commit

git add crates/ail/tests/typeclass_22c.rs
git commit -m "iter 22c.2: e2e test — user-class fixture compiles, runs, prints 42"

---

Task 3: JOURNAL entry + milestone-close handoff

Files:

• Modify: docs/JOURNAL.md — append iteration entry.

Step 3.1 — Append the iteration entry

## 2026-05-09 — Iteration 22c: User-class e2e fixture

The milestone-22 acceptance fixture for the user-class path. One new
`examples/test_22c_user_class_e2e.ail.json` defines a user class
`Foo a where foo : (a borrow) -> Int`, a user ADT `IntBox = MkIntBox
Int`, an `instance Foo IntBox` whose body matches on the ctor and
returns the wrapped int, and a `main` that calls `foo (MkIntBox 42)`
through the 22b.3 monomorphisation pass and prints the result via
`io/print_int`. Stdout: `42`.

**Per-task subjects (mirror commit messages):**

- 22c.1: fixture — user class + user ADT + instance, prints 42
- 22c.2: e2e test — user-class fixture compiles, runs, prints 42

**No production-code changes.** 22b.3 shipped every compiler path
this fixture exercises (mono of class methods, call-site rewrite,
synthesised symbol naming via `__` separator, match lowering inside
synthesised bodies). The fact that 22c lands as a pure-fixture iter
is the strongest possible evidence that the typeclass machinery is
done — there is nothing left to wire.

**Spec amendments folded into 22b.4a's amendment block:**
22b.4b (Prelude for primitives) dropped from milestone scope; 22c's
fixture re-scoped to vocabulary AILang already has (no `++`, no
named-field record syntax, no top-level polymorphic `print`). See
`docs/specs/0002-22-typeclasses.md` "Amendments" §"22b.4b
dropped" and §"22c scope tightened".

**Milestone-22 acceptance check:**

1. ✓ 22b.1 + 22b.2 + 22b.3 + 22b.4a + 22c JOURNAL entries committed.
2. (pending) Audit suite green — `audit` skill runs next.
3. ✓ 22c user-class fixture compiles, runs, prints `42` (this iter).
4. ✓ Round-trip filter retired in 22b.4a; all `examples/*.ail.json`
   pass round-trip.

**Bench gates:** all three exited 0/0/0.

**Next step:** dispatch `audit` skill to close the milestone —
architect drift review against `docs/DESIGN.md` plus the three
regression scripts (already 0/0/0 here but `audit` re-runs as
its own gate). On clean audit: milestone 22 closes; queue moves
to whatever's next. On drift: tidy iteration first.

Step 3.2 — Commit

git add docs/JOURNAL.md
git commit -m "iter 22c: journal entry — milestone-22 acceptance fixture lands"

---

Acceptance gate (run after Task 3)

cargo test --workspace
python3 bench/check.py
python3 bench/compile_check.py
python3 bench/cross_lang.py

All four green is the iteration close. The orchestrator then dispatches skills/audit to close milestone 22.

---

Self-review checklist (orchestrator, pre-commit)

1. Spec coverage: every spec acceptance criterion has a task that satisfies it. Criterion 1 (JOURNAL) → Task 3; Criterion 3 (22c fixture compiles + runs) → Tasks 1+2; Criterion 4 (round-trip) → already satisfied by 22b.4a. ✓
2. Placeholder scan: grep this file for "TBD" / "TODO" / "fill in" / "implement later" / "similar to" / "add appropriate". Zero hits. ✓
3. Type consistency: the fixture's class name, method name, ADT name, ctor name, instance binding, and main call site all use Foo / foo / IntBox / MkIntBox consistently. ✓
4. Step granularity: every step ≤ 5 minutes. The two ambiguous steps are 1.2 and 1.3 (verify check + verify build) — they may surface compiler bugs that aren't 5-minute fixes. The plan instructs STOP and route to debug in that case, which is the right discipline. ✓