AILang/docs/specs/0026-fieldtest-form-a.md

# Fieldtest — form-a-default-authoring — 2026-05-13

**Status:** Draft — awaiting orchestrator triage
**Author:** ailang-fieldtester (dispatched by skills/fieldtest)

## Scope

Form A (`.ail`) became the sole authoring surface across the working
tree. 156 non-carve-out `.ail.json` files were rendered to `.ail`
siblings and deleted (8 carve-outs remain). The Roundtrip Invariant
was restated as parse-determinism + idempotency-under-print + CLI-
pipeline-idempotency. CLI subcommands `ail check / build / run /
parse / render` accept `.ail` directly via extension dispatch (since
iter ext-cli.1). This fieldtest probes whether a downstream LLM-author
working only from DESIGN.md + `crates/ailang-core/specs/form_a.md` +
the public corpus can hand-author programs that exercise the new
authoring surface, the milestone-23/24 typeclass machinery (`Eq`,
`Ord`, `Show`, `print`), and multi-module workspaces.

## Examples

### `examples/fieldtest/forma_1_factorial.ail` — tail-recursive factorial
- What it does: two top-level fns (`fact_acc/2`, `fact/1`) plus `main`
  prints `fact 5` and `fact 10`. Exercises `tail-app`, `if`, primitive
  arithmetic, no class machinery. The LLM-natural shape for "is the
  basic authoring path frictionless?".
- Why it fits the milestone: pure-arithmetic smoke for the
  authoring-ergonomics axis. No class or workspace surface; just
  exercises parser → checker → codegen on a spontaneous LLM-author
  shape derived from the form_a.md few-shot corpus (sum_demo /
  hello).
- Outcome: `ail check` → `ok (23 symbols across 2 modules)`; `ail build`
  → `built`; stdout `120\n3628800\n` (expected). First-shot clean.

### `examples/fieldtest/forma_2_show_color.ail` — `instance Show Color` + polymorphic `print`
- What it does: declares `data Color { Red | Green | Blue }`, an
  `instance prelude.Show Color` whose body pattern-matches and returns
  a `Str` literal, and calls `print` three times. Exercises milestone
  24's polymorphic `print` end-to-end on a user ADT with a manually
  written Show instance.
- Why it fits the milestone: the Show+print axis. Tests that the
  iter-24.3 cross-module-references-in-synthesised-bodies invariants
  fire correctly on a user-defined enum-like ADT.
- Outcome: `ail check` → ok; `ail build` → built; stdout
  `Red\nGreen\nBlue\n` (expected). First-shot clean.

### `examples/fieldtest/forma_3_user_class_describe.ail` — user-defined `class Describe` with two instances
- What it does: declares `class Describe a where describe : (borrow a)
  -> Str`, ships `instance Describe Int` and `instance Describe Shape`
  (a 2-variant ADT), then a polymorphic free fn `announce : forall a.
  Describe a => (borrow a) -> Unit !IO` that calls `describe` then
  `io/print_str`. `main` calls `announce` at three concrete types.
- Why it fits the milestone: stresses the user-typeclass authoring
  surface, `(forall (vars a) (constraints (constraint Describe a))
  ...)` shape, monomorphisation of a polymorphic free fn through a
  user constraint, and dispatch to two distinct user instances.
- Outcome: **first attempt failed** because I reached for `str_concat`
  (a builtin I assumed existed for `"Circle r=" ++ int_to_str r`-style
  bodies); `ail check` returned `ok` but `ail build` died with
  `monomorphise_workspace: unknown identifier: str_concat`. Repaired
  by dropping the prefix-string concatenation. **Repaired version
  runs clean**: stdout `42\n3\n5\n` (expected). See findings below.

### `examples/fieldtest/forma_4_intmath_lib.ail` + `forma_4_intmath_main.ail` — two-module workspace
- What it does: `forma_4_intmath_lib` exports three pure-`Int` fns
  (`square`, `cube`, `abs_int`); `forma_4_intmath_main` imports it
  and calls each via qualified references (`forma_4_intmath_lib.square
  7`, etc.) inside `main`.
- Why it fits the milestone: stresses extension-dispatch on a
  workspace entry plus canonical-form qualified cross-module refs
  (ct.1 / mq.1 mature features) on hand-authored `.ail`.
- Outcome: `ail check examples/fieldtest/forma_4_intmath_main.ail` →
  `ok (24 symbols across 3 modules)` (lib + main + prelude); `ail
  build` → built; stdout `49\n27\n42\n` (expected). First-shot clean.

## Findings

### [bug] `ail check` does NOT catch unbound identifiers inside `(instance ... (method (body (lam ... (body APP)))))`
- Example: forma_3 first attempt; isolated repro in spec body below.
- What happened (verbatim, isolated repro):
  ```
  (module ft_concat_in_instance
    (class Describe (param a)
      (method describe (type (fn-type (params (borrow a)) (ret (con Str))))))
    (instance (class Describe) (type (con Int))
      (method describe (body (lam (params (typed n (con Int))) (ret (con Str))
        (body (app str_concat "n=" (app int_to_str n))))))))
    (fn main (type (fn-type (params) (ret (con Unit)) (effects IO))) (params)
      (body (do io/print_str (app describe 5)))))
  ```
  `ail check`: `ok (23 symbols across 2 modules)`.
  `ail build`: `Error: monomorphise_workspace: unknown identifier: str_concat`.

  The same shape at fn-body level (a plain `(fn ... (body (app str_concat ...)))`)
  correctly fires `error: [unbound-var] greet: unknown identifier:
  str_concat` at `ail check`. So the typechecker has the diagnostic
  machinery; it does not walk the lambda body inside an instance
  method's `(method (body (lam ... (body ...))))` when looking up
  identifiers (or it walks but does not produce an error at the
  unbound-var). The error eventually fires at the monomorphisation
  pass, whose diagnostic ("monomorphise_workspace: unknown identifier")
  is significantly less helpful than the typechecker's
  `[unbound-var]` — no source location, no symbol kind, no `did you
  mean ...?`.
- Why it is a bug: `ail check` is documented as the typecheck step
  whose purpose is exactly to catch this class of error before
  codegen runs. The split-pipeline diagnostic surface is a regression
  in the user-facing contract.
- One-line repro: see the four-line isolated repro above.
- Recommended downstream action: `debug` → write a RED test asserting
  `ail check` fires `[unbound-var]` on the instance-method-body shape,
  then `implement` mini-mode walks the lambda body during instance
  validation. (Plausible cause: instance method bodies are validated
  later than fn bodies, after the registry build, and the unbound-var
  check is not threaded through that path.)

### [spec_gap] `crates/ailang-core/specs/form_a.md` does not document the typeclass surface
- Example(s): forma_2 (Show user ADT) and forma_3 (user-defined class
  + constraint).
- What happened: I needed to write `(class ...)`, `(instance ...)`,
  `(method ...)`, and `(constraints (constraint ClassName tyvar))`
  inside a `forall`. `form_a.md` — the document explicitly billed as
  "the **complete LLM-targeted specification**. If you are an LLM and
  this is in your context, you have everything you need to produce
  valid Form-A" — has zero references to "class", "instance",
  "constraint", or "method". The grep is empty. I reverse-engineered
  the surface entirely from `examples/show_user_adt.ail`,
  `examples/bench_mono_dispatch.ail`, and
  `examples/mq1_xmod_constraint_class.ail`.
- Reading I picked: the `(class NAME (param TYVAR) (method NAME (type
  FN-TYPE)))` form for class declarations; `(instance (class CLASS-
  REF) (type TYPE) (method NAME (body LAM-TERM)))` for instances;
  `(constraints (constraint CLASS-REF TYVAR))` inside a `(forall ...)`
  schema. These work but are not in the spec; another reading (e.g.
  whether `(class CLASS-REF)` must be qualified vs. bare for same-
  module instances) was not determinable from the spec text and had
  to be derived by example-mining.
- Why spec_gap: a foreign LLM-author with form_a.md in context but
  without the example corpus cannot author class / instance / poly-
  constrained-fn programs at all. DESIGN.md §Decision-11 documents
  the JSON-AST schema for `ClassDef` / `InstanceDef` / `FnDef.type`
  constraints (lines ~1526-1582) but the Form-A textual projection
  for any of those keywords is not anchored anywhere. The milestone-
  24 close ratified `print` + four `Show` instances ship in the
  prelude — without a documented Form-A surface for user-class
  authoring, the LLM-utility criterion for typeclasses (Decision 11
  → "LLM author reaches for it unprompted") cannot be tested on
  foreign LLMs by the procedure that cma.3 / ms.2 used for non-class
  programs.
- Recommended downstream action: `tighten DESIGN.md` (or extend
  `form_a.md`) — `plan` an iter that adds three sections to
  form_a.md: "Class declarations", "Instance declarations", and
  "Constraints on polymorphic fns". Each with the EBNF production
  and one or two few-shot fixtures lifted from the corpus
  (`show_user_adt.ail`, `mq1_xmod_constraint_class.ail`).

### [spec_gap] Form-A grammar for `prelude.Show` qualifier in `(instance (class ...))`: when is the prefix required?
- Example: forma_2 (`(instance (class prelude.Show) (type (con Color))
  ...)`).
- What happened: I copied the qualified `prelude.Show` form from
  `examples/show_user_adt.ail`. It works. But I also note that
  `examples/mq3_class_eq_vs_fn_eq_classmod.ail` writes `(instance
  (class MyEq) ...)` bare (no prefix) — because the class is declared
  in the SAME module. The rule appears to be the mq.1 canonical-form
  rule (qualify for cross-module, bare for same-module). DESIGN.md
  §mq.1 makes this explicit at the JSON-AST `InstanceDef.class` field
  level, but not at the Form-A surface level.
- Reading I picked: a class reference inside `(instance (class ...))`
  follows the same canonical-form rule as `Type::Con.name` — bare for
  same-module, `module.Class` for cross-module. Another plausible
  reading: always-qualified (since `prelude` is auto-imported, bare
  `Show` could resolve to prelude.Show — but the empirical evidence
  in `show_user_adt.ail` says no, qualifier is required for cross-
  module).
- Why spec_gap: a downstream LLM-author cannot determine whether
  `(instance (class Show) (type (con MyType)) ...)` (bare, same module
  as class? cross-module to prelude?) is well-formed without reading
  the corpus. form_a.md doesn't carry the rule; DESIGN.md carries
  it at the JSON-AST level but not for the surface.
- Recommended downstream action: same iter as the previous gap —
  one paragraph in form_a.md's new "Class declarations" / "Instance
  declarations" sections naming the canonical-form rule for
  `Constraint.class`, `InstanceDef.class`, `SuperclassRef.class` at
  the Form-A surface.

### [friction] No primitive `str_concat` / `str_append` in builtins
- Example: forma_3 first attempt.
- What happened: while writing a `Describe Shape` instance, I reached
  for a string-concatenation primitive to format `"Circle r=" ++
  int_to_str r`. `ail builtins` lists `int_to_str`, `bool_to_str`,
  `str_clone`, `float_to_str` — no `str_concat`, no `str_append`,
  no `++`. The natural `Show MyType` body shape for any non-trivial
  ADT (a record-like print, a `name=value` style, anything with a
  label) requires string concatenation. Without it, the LLM-author
  either writes degenerate instance bodies (return just the inner
  Int as if it were the whole repr — what forma_3's repaired version
  does) or punts on milestone-24 Show-of-rich-ADTs entirely.
- Why friction: milestone 24 shipped polymorphic `print` and four
  prelude `Show` instances on primitives; the natural LLM-author
  follow-up is `Show MyRecord = "MyRecord { x = " ++ show x ++ "
  }"`-shaped instance bodies. With no concatenation primitive, the
  shipped Show feature is observably under-powered for the very task
  it was advertised to enable (user-ADT pretty-printing through
  `print`). The friction is real for the milestone's downstream
  utility, not just for hypothetical foreign LLMs.
- Recommended downstream action: `plan` a small follow-up iter that
  adds `str_concat : (Str, Str) -> Str` as a runtime + checker +
  codegen primitive (symmetric to `str_clone` / `int_to_str` plumbing
  in 24.1 / hs.4). The cost surface is small (single-fn slab-
  allocating C helper + four-site lockstep registration); the LLM-
  utility payoff is high because every realistic `Show MyType` body
  needs it.

### [working] User-defined typeclass with `forall + Constraint` polymorphic fn dispatches correctly
- Example: forma_3 (repaired).
- What happened: declared `class Describe a where describe : (borrow
  a) -> Str`, shipped two instances (`Int` and `Shape`), wrote
  `announce : forall a. Describe a => (borrow a) -> Unit !IO`, called
  it three times at two concrete types in `main`. `ail check`
  reported ok across 2 modules (entry + prelude); `ail build`
  produced a binary; stdout was correct. The mq.3 type-driven
  dispatch + the iter-23.4 unified mono pass + the milestone-24
  `print`-style polymorphic-fn pipeline all visibly cooperate on a
  workload they were not specifically calibrated against. No
  diagnostic surfaced spuriously; the surface was discoverable from
  three corpus examples in ~5 minutes.
- Why working: the full Decision-11 trajectory (class declaration +
  multiple instances + polymorphic free fn over a constraint set +
  mono-pass synthesis of `describe__Int` and `describe__Shape` +
  call-site rewrite) ran end-to-end on a hand-authored `.ail`
  workspace without any compiler crate hint. This is the LLM-utility
  acceptance test for milestone 22+23+24 cumulative, run on one
  spontaneous fresh-author shape, and it passes.
- Recommended downstream action: `carry-on`. Worth pinning the
  fixture so a future regression cannot silently break the
  trajectory. (Already a working-tree artefact;
  `crates/ailang-core/tests/schema_coverage.rs`'s dynamic walk picks
  it up automatically per the form-a.1 refactor.)

### [working] Multi-module workspace via `(import ...)` + qualified refs runs end-to-end on `.ail`
- Example: forma_4_intmath_main + forma_4_intmath_lib.
- What happened: two `.ail` modules in `examples/fieldtest/`, one
  importing the other with `(import forma_4_intmath_lib)` and using
  qualified `forma_4_intmath_lib.square` / `.cube` / `.abs_int`
  references inside `main`. `ail check
  examples/fieldtest/forma_4_intmath_main.ail` correctly resolved
  the import (workspace prefers `.ail` sibling over `.ail.json` per
  the ext-cli.1 doc), typechecked across 3 modules (main + lib +
  prelude), built, and ran. No friction from the canonical-form rule
  — qualified names worked first-shot.
- Why working: the ext-cli.1 + form-a.1 stack (extension-dispatching
  workspace loader + `.ail`-preferred sibling resolution) functions
  exactly as DESIGN.md promises for a hand-authored two-module
  workspace.
- Recommended downstream action: `carry-on`.

### [working] Polymorphic `print` on user ADT through `instance prelude.Show MyType`
- Example: forma_2.
- What happened: declared `data Color { Red | Green | Blue }`, wrote
  `instance prelude.Show Color` with a 3-arm match body returning a
  Str literal, called `(app print (term-ctor Color Red))` three times
  in main. Compiled clean; ran clean; produced `Red\nGreen\nBlue\n`.
  The whole iter-24.3 cross-module-references-in-synthesised-bodies
  trajectory (the three invariants in DESIGN.md §Cross-module
  references in synthesised bodies — canonical-form type_args,
  import_map-bypass fallback, FreeFnCall residual push) ran on a
  user-ADT that the implementation tests did not specifically pin.
- Why working: the LLM-utility acceptance test for milestone-24's
  flagship feature (polymorphic `print` reaching user ADTs through a
  user-written Show instance) passes on a first-shot LLM-author
  example.
- Recommended downstream action: `carry-on`.

## Recommendation summary

| Finding | Class | Action |
|---|---|---|
| `ail check` misses unbound-var inside instance method lambda body | bug | `debug` (RED test on instance-body unbound-var; mini `implement`) |
| `form_a.md` lacks class/instance/constraint grammar | spec_gap | `plan` (form_a.md addendum: 3 new sections + corpus fixtures) |
| Form-A canonical-form rule for `(instance (class X))` qualifier not anchored | spec_gap | `plan` (paragraph in form_a.md's new class-section; tighten DESIGN.md §Decision 11 surface anchor) |
| No `str_concat` builtin | friction | `plan` (small follow-up iter; adds runtime + checker + codegen + lockstep wiring symmetric to `str_clone`) |
| User-typeclass + constraint poly fn end-to-end | working | `carry-on` |
| Multi-module `.ail` workspace + qualified refs | working | `carry-on` |
| `print` on user ADT through user `instance prelude.Show` | working | `carry-on` |