# prep.2 — Term::New construct — Implementation Plan > **Parent spec:** `docs/specs/0052-kernel-extension-mechanics.md` (Iteration prep.2 section, lines 232-356) > **Gitea issue:** refs #32 (the implementer-side iter-completion commit closes via `closes #32`) > > **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` > to run this plan. Steps use `- [ ]` checkboxes for tracking. **Goal:** Ship the `new` Form-A keyword + `Term::New { type_name, args: Vec }` AST variant + `NewArg::Type|Value` enum end-to-end through schema/surface/checker, with two new diagnostics, a workspace-wide bare→qualified rewrite extension (piggybacking on prep.1's `qualify_workspace_term`), and drift/spec anchors. Codegen is deliberately out of scope — the construct is verified at `ail check` cleanness. **Architecture:** A new Term variant Term::New holds an unqualified type-name plus a heterogeneous arg vector (`NewArg::Type` or `NewArg::Value`). The prep.1 pre-pass `qualify_workspace_term` gains a `Term::New` arm that rewrites bare `type_name` to qualified `.` form, mirroring the existing `Term::Ctor` arm — so the synth pass sees qualified Types. The checker elaborates `Term::New` via type-scoped lookup → home module → find `new` def → arg-count + arg-kind check → forall binding. The variant addition is compile-forced across 24 files (44+ exhaustive `match … { Term::Lit | … }` sites); Task 1 walks all of them with a small set of mechanical arm patterns. Tasks 2-4 layer surface, checker, and schema-anchor work on top. **Tech stack:** `crates/ailang-core` (AST + serde + drift tests), `crates/ailang-surface` (lex/parse/print + round-trip), `crates/ailang-check` (synth elaboration + diagnostics + pre-pass arm + 21+ analysis-walker arms), `crates/ailang-codegen` (error arms — codegen is out of scope), `crates/ailang-prose`, `crates/ail/src/main.rs`, and the spec/contract anchors `design/contracts/0002-data-model.md` + `crates/ailang-core/specs/form_a.md`. **Out of scope (deferred per spec §50-55, §327-330, §687-700):** - Codegen lowering of `Term::New` — codegen arms return `CodegenError::Internal(...)`. Real codegen lands in the `raw-buf` milestone. - `param-in` enforcement on the type-arg of `Term::New` — prep.3. - Kernel-tier module auto-import — prep.3. - Hash-pin refreshes — additive variant, no existing fixture emits `"t": "new"`. **Files this plan creates or modifies:** - Modify: `crates/ailang-core/src/ast.rs` — add `Term::New { type_name, args }` to the Term enum (line 405); add `pub enum NewArg { Type(Type), Value(Term) }` with tagged serde repr (after line 565). - Modify: `crates/ailang-core/src/desugar.rs` — 9 exhaustive Term matches gain `Term::New` arms (Pattern A or B per site). - Modify: `crates/ailang-core/src/workspace.rs` — 2 walker sites gain `Term::New` arms (Pattern A). - Modify: `crates/ailang-check/src/lib.rs` — `substitute_rigids_in_term` (line 181, Pattern B), `verify_tail_positions` (line 2749, Pattern A), `verify_loop_body` (line 2862, Pattern A), `synth` Term-match (line ~3005, Pattern E stub in Task 1 → real elaboration in Task 3), `synth`'s "what was here" descriptor (line ~3886, Pattern F), `qualify_workspace_term` (line 4155, Pattern C). - Modify: `crates/ailang-check/src/lib.rs` — add `CheckError::NewTypeNotConstructible` + `CheckError::NewArgKindMismatch` variants (Task 3, after `TypeScopedReceiverNotAType` at line ~705); add to `code()` (line ~759), `ctx()` (line ~837), and message-format arms. - Modify: `crates/ailang-check/src/lift.rs` — 3 exhaustive Term matches gain `Term::New` arms (Pattern A). - Modify: `crates/ailang-check/src/linearity.rs` — 5 Term matches (Pattern A or specific per arm). - Modify: `crates/ailang-check/src/mono.rs` — 2 sites (Pattern A walker + Pattern B rewrite). - Modify: `crates/ailang-check/src/pre_desugar_validation.rs` — 1 site (Pattern A). - Modify: `crates/ailang-check/src/reuse_shape.rs` — 2 sites (Pattern A). - Modify: `crates/ailang-check/src/uniqueness.rs` — 2 sites (Pattern A). - Modify: `crates/ailang-codegen/src/lib.rs` — `lower_term` + `synth_with_extras` (Pattern D — error). - Modify: `crates/ailang-codegen/src/escape.rs` — 3 sites (Pattern A). - Modify: `crates/ailang-codegen/src/lambda.rs` — 1 site (Pattern A). - Modify: `crates/ailang-surface/src/parse.rs` — head-keyword dispatcher (~line 1227), `is_term_head_kw` (~line 1610), new `parse_new` method (Task 2). - Modify: `crates/ailang-surface/src/print.rs` — `write_term` (line 420-597) gains `Term::New` arm (Task 2). - Modify: `crates/ailang-prose/src/lib.rs` — 3 sites (Pattern A — walker / printer per site). - Modify: `crates/ail/src/main.rs` — `walk_term` + rewrite_term inner (Pattern A). - Modify: `crates/ailang-core/tests/design_schema_drift.rs` — exhaustive Term match arm (Task 1, Pattern F) + new `term_new_round_trips` test (Task 4). - Modify: `crates/ailang-core/tests/schema_coverage.rs` — `VariantTag::TermNew` enum entry; `EXPECTED_TAGS` array gains the entry; `visit_term` arm. - Modify: `crates/ailang-core/tests/spec_drift.rs` — exhaustive Term match arm + exemplar row + form_a.md anchor assertion (Task 4 covers the anchor add). - Modify: `crates/ail/tests/codegen_import_map_fallback_pin.rs` — `contains_xmod_show_var` Term match (Pattern A). - Modify: `crates/ailang-surface/tests/round_trip.rs` — Task 2: add `(new T )` fixture. - Modify: `design/contracts/0002-data-model.md` — Task 4: add `{ "t": "new", "type": "", "args": [NewArg...] }` to the JSON-tag block (lines 107-178 area) + add the `NewArg` shape definition. - Modify: `crates/ailang-core/specs/form_a.md` — Task 4: add `(new TYPE-NAME ARG*)` to the surface-keyword cheatsheet (lines 289-298 area). - Test (in-source `#[cfg(test)] mod tests` in `crates/ailang-check/src/lib.rs`): three new tests — `new_resolves_via_type_scope`, `new_type_not_constructible`, `new_arg_kind_mismatch_value_where_type` (Task 3). --- ## Task 1: AST variant + NewArg + workspace-wide compile-forced arms **Files:** see "Files this plan creates or modifies" above — every entry except the surface-parse/print sites (Task 2), the synth real-logic arm (Task 3), and the spec/contract anchors (Task 4). Roughly 20 production files + 4 test files. **Six arm patterns** (each new `Term::New` arm matches one of these): ```rust // Pattern A — walker that recurses into sub-terms. Most analysis // passes use this. NewArg::Type carries no value and contributes // nothing. Term::New { args, .. } => { for arg in args { match arg { NewArg::Value(v) => /* the function's recursion call on v */, NewArg::Type(_) => {} } } } ``` ```rust // Pattern B — Term-reconstruction (substitution, desugar map). // NewArg::Type may carry a Type that itself needs rewriting. Term::New { type_name, args } => Term::New { type_name: type_name.clone(), args: args.iter().map(|arg| match arg { NewArg::Value(v) => NewArg::Value(/* recursive rewrite of v */), NewArg::Type(t) => NewArg::Type(/* recursive rewrite of t — or t.clone() if the fn doesn't touch Types */), }).collect(), } ``` ```rust // Pattern C — bare→qualified rewrite. Used by qualify_workspace_term // ONLY. Mirrors the existing Term::Ctor arm at lib.rs:4187. Term::New { type_name, args } => { if !type_name.contains('.') && !ailang_core::primitives::is_primitive_name(type_name) && !own_local_types.contains_key(type_name) { if let Some(home) = module_types .iter() .find_map(|(m, types)| if types.contains_key(type_name) { Some(m.clone()) } else { None }) { *type_name = format!("{home}.{type_name}"); } } for arg in args { match arg { NewArg::Value(v) => qualify_workspace_term(v, own_local_types, module_types), NewArg::Type(t) => *t = qualify_workspace_types(t, own_local_types, module_types), } } } ``` ```rust // Pattern D — codegen error stub. Real codegen for Term::New lands // in the raw-buf milestone. Term::New { .. } => Err(CodegenError::Internal( "Term::New requires the type's `new` def to be desugared first; \ codegen does not yet support Term::New directly — milestone raw-buf".into() )) ``` ```rust // Pattern E — synth elaboration STUB (Task 1 only). Task 3 replaces // this with the real per-spec elaboration logic. Term::New { .. } => Err(CheckError::Internal( "Term::New elaboration not yet implemented — prep.2 Task 3".into() )) ``` ```rust // Pattern F — small descriptor (e.g. "what was here" in synth's // inner error, or the exhaustive name-match in design_schema_drift.rs's // test). Term::New { .. } => "new" ``` **Per-site assignment table:** | File | Line / fn name | Pattern | Notes | |---|---|---|---| | `crates/ailang-core/src/ast.rs` | Term enum body (~line 405) | — | ADD variant: `New { type_name: String, args: Vec }`. Carries `#[serde(rename = "type")]` on `type_name` per the spec's `"type": ""` byte shape; no rename on `args` (default snake_case matches `"args"`). | | `crates/ailang-core/src/ast.rs` | (after Term, before LoopBinder) | — | ADD `pub enum NewArg { Type(Type), Value(Term) }` with `#[derive(Debug, Clone, Serialize, Deserialize)] #[serde(tag = "kind", content = "value", rename_all = "lowercase")]`. The `tag = "kind", content = "value"` lands the spec's `{"kind": "type", "value": ...}` shape exactly. | | `crates/ailang-core/src/ast.rs` | in-source round-trip tests (~line 920+, ~line 953+) | A + B (test helpers) | ADD `Term::New` round-trip test using the standard pattern (build a Term::New, serialise to JSON, assert deserialise round-trips). The exhaustive matches inside test helpers also need arms. | | `crates/ailang-core/src/desugar.rs` | `collect_used_in_term` (~line 283) | A | recurse over NewArg::Value with the function's collector | | `crates/ailang-core/src/desugar.rs` | `Desugarer::desugar_term` (~line 467) | B | reconstruct Term::New; desugar each NewArg::Value | | `crates/ailang-core/src/desugar.rs` | `free_vars_in_term` (~line 1136) | A | union free vars over NewArg::Value | | `crates/ailang-core/src/desugar.rs` | `subst_var` (~line 1263) | B | substitute through each NewArg::Value | | `crates/ailang-core/src/desugar.rs` | peel walker (~line 1414) | A | walker semantics — recurse over NewArg::Value | | `crates/ailang-core/src/desugar.rs` | `subst_call_with_extras` (~line 1432) | B | substitute, reconstruct | | `crates/ailang-core/src/desugar.rs` | `find_non_callee_use` (~line 1557) | A | binder-use walker — recurse over NewArg::Value | | `crates/ailang-core/src/desugar.rs` | `any_nested_ctor` (~line 1599) | A | recurse, return `false` for NewArg::Type | | `crates/ailang-core/src/desugar.rs` | `any_let_rec` (~line 1657) | A | recurse | | `crates/ailang-core/src/desugar.rs` | `any_lit_pattern` or similar (~line 2783) | A | recurse | | `crates/ailang-core/src/workspace.rs` | `walk_term_embedded_types` (~line 1205) | A | walk each NewArg::Type via `walk_type`; recurse into NewArg::Value | | `crates/ailang-core/src/workspace.rs` | `walk_term` (~line 1337) | A | recurse over NewArg::Value | | `crates/ailang-check/src/lib.rs` | `substitute_rigids_in_term` (~line 181) | B | substitute through NewArg::Value; apply `substitute_rigids` to NewArg::Type | | `crates/ailang-check/src/lib.rs` | `verify_tail_positions` (~line 2749) | A | recurse over NewArg::Value with non-tail semantics | | `crates/ailang-check/src/lib.rs` | `verify_loop_body` (~line 2862) | A | recurse with `in_loop_tail=false` for arg subterms | | `crates/ailang-check/src/lib.rs` | `synth` Term match (~line 3005) | E (stub) | Task 3 replaces with real logic | | `crates/ailang-check/src/lib.rs` | "what was here" descriptor (~line 3886) | F | `Term::New { .. } => "new"` | | `crates/ailang-check/src/lib.rs` | `qualify_workspace_term` (line 4155) | C | THE prep.1 pre-pass partner — full bare→qualified arm | | `crates/ailang-check/src/lift.rs` | 3 exhaustive matches | A | recurse over NewArg::Value | | `crates/ailang-check/src/linearity.rs` | `walk` (~line 427) | A | walk(NewArg::Value, Position::Consume) for each value arg | | `crates/ailang-check/src/linearity.rs` | `any_sub_binder_consumed_for` (~line 880) | A | recurse | | `crates/ailang-check/src/linearity.rs` | `ctor_uses_any_binder` (~line 1046) | A | recurse | | `crates/ailang-check/src/linearity.rs` | `term_mentions_any_binder` (~line 1098) | A | recurse | | `crates/ailang-check/src/linearity.rs` | joined pattern at ~line 1102 | A — separate arm | If the existing joined pattern (`Term::Ctor | Term::Do | Term::Recur`) covers Term::New's semantics, add to the joined arm; otherwise separate. Default: separate arm with recurse-over-args. | | `crates/ailang-check/src/mono.rs` | walker at ~line 1123 | A | recurse | | `crates/ailang-check/src/mono.rs` | rewrite at ~line 1520 | B | reconstruct | | `crates/ailang-check/src/pre_desugar_validation.rs` | exhaustive match (~line 71) | A | recurse | | `crates/ailang-check/src/reuse_shape.rs` | walker (~line 127) | A | recurse | | `crates/ailang-check/src/reuse_shape.rs` | rewrite (~line 466) | B | reconstruct | | `crates/ailang-check/src/uniqueness.rs` | walker (~line 153) | A | recurse over NewArg::Value with App-like ownership semantics | | `crates/ailang-check/src/uniqueness.rs` | walker (~line 233) | A | recurse | | `crates/ailang-codegen/src/lib.rs` | `lower_term` (~line 1525-2068) | D | error | | `crates/ailang-codegen/src/lib.rs` | `synth_with_extras` (~line 3415-3546) | D | error | | `crates/ailang-codegen/src/escape.rs` | 3 sites | A | recurse over NewArg::Value (escape analysis) | | `crates/ailang-codegen/src/lambda.rs` | 1 site (~line 460-510) | A | recurse | | `crates/ailang-prose/src/lib.rs` | walker / printer (~line 927) | A or Form-B printer | walker arms recurse; Form-B printer emits `new T(args...)` | | `crates/ailang-prose/src/lib.rs` | (~line 1127) | A | recurse | | `crates/ailang-prose/src/lib.rs` | (~line 1274) | A | recurse | | `crates/ail/src/main.rs` | `walk_term` (~line 1430) | A | recurse | | `crates/ail/src/main.rs` | rewrite_term inner (~line 2676) | A | recurse | | `crates/ail/tests/codegen_import_map_fallback_pin.rs` | `contains_xmod_show_var` (~line 62) | A | recurse | | `crates/ailang-core/tests/design_schema_drift.rs` | exhaustive Term match arm (~line 166) | F | `Term::New { .. } => "new"` | | `crates/ailang-core/tests/schema_coverage.rs` | `VariantTag` enum (~line 29) | — | ADD `TermNew` discriminant | | `crates/ailang-core/tests/schema_coverage.rs` | `EXPECTED_TAGS` array (~line 84-98) | — | ADD `VariantTag::TermNew` | | `crates/ailang-core/tests/schema_coverage.rs` | `visit_term` exhaustive match | A — variant | `Term::New { args, .. } => { tags.insert(VariantTag::TermNew); for a in args { match a { NewArg::Type(t) => visit_type(t, tags), NewArg::Value(v) => visit_term(v, tags) } } }` | | `crates/ailang-core/tests/spec_drift.rs` | exemplar list (~line 90-158) | — | ADD exemplar row for Term::New (asserting `"(new"` anchor in form_a.md) | | `crates/ailang-core/tests/spec_drift.rs` | exhaustive Term match (~line 135-151) | F | `Term::New { .. } => /* anchor literal */` | - [ ] **Step 1: Add the `Term::New` variant and `NewArg` enum** In `crates/ailang-core/src/ast.rs`, add the variant inside the `Term` enum (insert before the closing `}` of the enum at the end; or alphabetically near `Recur` — Boss judgement on ordering, but past-convention is "last-added is at the end"): ```rust /// Functional construction: `(new T arg+)` calls the `new` def in /// `T`'s home module with the supplied args. Each arg is either a /// Type or a Value (see [`NewArg`]). Resolution: type-scoped /// lookup of `type_name` → home module → find `new` def → check /// arg-count and arg-kind. See prep.2 of the /// kernel-extension-mechanics milestone. New { #[serde(rename = "type")] type_name: String, args: Vec, }, ``` After the `Term` enum closing brace, before the next enum/struct (or near `LoopBinder` at ~line 586), add: ```rust /// One positional arg to a `(new T args...)` call. Either a `Type` /// (e.g. `(new Series (con Float) 3)` — first arg is `NewArg::Type`) /// or a `Value` (e.g. the literal `3` in the same example, a /// `Term`). Disambiguation at parse-time is by syntactic form: a /// Type starts with one of the Type-production heads (`con`, /// `fn-type`, `borrow`, `own`); anything else is a Term. #[derive(Debug, Clone, Serialize, Deserialize)] #[serde(tag = "kind", content = "value", rename_all = "lowercase")] pub enum NewArg { Type(Type), Value(Term), } ``` - [ ] **Step 2: Run the workspace compile-gate** Run: `cargo build --workspace 2>&1 | tail -60` Expected: a cluster of `error[E0004]: non-exhaustive patterns: \`Term::New { .. }\` not covered` errors across the per-site table above. This is the EXPECTED RED state for Task 1. - [ ] **Step 3: Add the `Term::New` arm to every exhaustive Term match (per-site table)** For each entry in the per-site table above, edit the file and add the listed Pattern's arm. The patterns are inline in this task; the per-site table assigns one to each. Notes: - Apply Pattern E (stub) to `synth`'s big Term-match in `lib.rs` — Task 3 replaces with the real elaboration. - Apply Pattern C (qualify-workspace-term) ONLY to `qualify_workspace_term`. Other sites use Pattern A or B. - For test files (`schema_coverage.rs`, `spec_drift.rs`), update both the enum/exemplar data AND the exhaustive match arm — they go together. - [ ] **Step 4: Run the workspace compile-gate again** Run: `cargo build --workspace 2>&1 | tail -15` Expected: 0 errors. The variant addition + per-site arms compile cleanly. - [ ] **Step 5: Run the workspace test suite for regressions** Run: `cargo test --workspace 2>&1 | tail -30` Expected: All tests pass. The variant is additive — no existing fixture emits `"t": "new"`, so byte-shapes are unchanged. `schema_coverage.rs` passes because EXPECTED_TAGS gained the new entry AND `visit_term` emits it. If any test fails, it's because a Pattern was applied incorrectly (e.g. uniqueness.rs arm not properly recursing into NewArg::Value, causing a test that exercises ownership analysis to break). Fix per-site, re-run. --- ## Task 2: Form-A surface — lex/parse + print + round-trip fixture **Files:** - Modify: `crates/ailang-surface/src/parse.rs:1227-1257` — head-keyword dispatcher - Modify: `crates/ailang-surface/src/parse.rs:1610-1631` — `is_term_head_kw` helper - Modify: `crates/ailang-surface/src/parse.rs` — new `parse_new` method (after `parse_recur` at line ~1687) - Modify: `crates/ailang-surface/src/print.rs:420-597` — `write_term` Term::New arm - Modify: `crates/ailang-surface/tests/round_trip.rs` — new fixture exercising `(new T )` - [ ] **Step 1: Write the failing round-trip test** Add to `crates/ailang-surface/tests/round_trip.rs` (find the existing fixture pattern; one new fn following the convention): ```rust #[test] fn round_trip_term_new_mixed_args() { // (new T (con Float) 3) — mixed type-arg + value-arg. let form_a = "(module new_demo\n (data Counter (ctor MkCounter (con Int)))\n (fn new (type (fn-type (params (con Int)) (ret (con Counter)))) (params n) (body (term-ctor Counter MkCounter n)))\n (fn main (type (fn-type (params) (ret (con Counter)))) (params) (body (new Counter 42))))\n"; let module = ailang_surface::parse_module(form_a).expect("parse OK"); let printed = ailang_surface::print_module(&module); assert_eq!(printed.trim(), form_a.trim(), "round-trip Form-A → JSON → Form-A must be bit-identical"); } ``` - [ ] **Step 2: Run the test to verify it fails** Run: `cargo test --workspace -p ailang-surface round_trip_term_new` Expected: FAIL — `parse_module` returns a `ParseError` because `new` is not a known head keyword. - [ ] **Step 3: Add `"new"` to the head-keyword dispatcher in parse.rs** At `crates/ailang-surface/src/parse.rs:1227-1257` (the match block dispatching on the head keyword of a `( …)` form), add an arm: ```rust "new" => self.parse_new()?, ``` between the existing `"recur"` arm and the `other =>` fallthrough. Update the error-message enumeration in the fallthrough at line 1249-1252 to include `new` in the list of known keywords. - [ ] **Step 4: Add `"new"` to `is_term_head_kw` helper** At `crates/ailang-surface/src/parse.rs:1610-1631`, the `is_term_head_kw` helper enumerates head keywords that introduce a Term form (used to disambiguate Term vs. Type vs. Pat in contexts like loop binders). Add `"new"` to the matches set: ```rust fn is_term_head_kw(kw: &str) -> bool { matches!(kw, "app" | "let" | "letrec" | "if" | "do" | "term-ctor" | "match" | "lam" | "seq" | "clone" | "reuse-as" | "loop" | "recur" | "new" ) } ``` (Adjust the existing list to match — this template assumes the exact set; verify against the function body before editing.) - [ ] **Step 5: Add the `parse_new` method** After `parse_recur` (line ~1687), add: ```rust fn parse_new(&mut self) -> Result { // Caller has consumed `(` and `new`. Read the type-name ident, // then one-or-more args. Each arg is a Type if its head ident // matches the Type-production keyword set (`con`, `fn-type`, // `borrow`, `own`); otherwise a Term. let type_name = self.expect_ident_for_type_name()?; let mut args: Vec = Vec::new(); loop { // Closing paren = end of args. if self.peek_close_paren() { self.expect_close_paren()?; break; } // Look at the next token: if `(`, peek the head ident to // disambiguate Type vs Term. Otherwise (bare token), it's // a Term (a literal or var). if self.peek_open_paren() { // Save state, peek the head ident, restore. let head = self.peek_head_ident_after_lparen(); match head.as_deref() { Some("con") | Some("fn-type") | Some("borrow") | Some("own") => { let t = self.parse_type()?; args.push(NewArg::Type(t)); } _ => { let v = self.parse_term()?; args.push(NewArg::Value(v)); } } } else { // Bare token — must be a Term (literal or var). let v = self.parse_term()?; args.push(NewArg::Value(v)); } } if args.is_empty() { return Err(self.error_at_cursor("`(new T ...)` requires at least one arg")); } Ok(Term::New { type_name, args }) } ``` (The helper names `expect_ident_for_type_name`, `peek_close_paren`, `peek_open_paren`, `peek_head_ident_after_lparen` may not exist verbatim; use the existing parser conventions in `parse.rs`. The implementer adjusts the spelling.) - [ ] **Step 6: Add the `write_term` arm in print.rs** At `crates/ailang-surface/src/print.rs:420-597` (`fn write_term`), add an arm before the closing `}`: ```rust Term::New { type_name, args } => { buf.push_str("(new "); buf.push_str(type_name); for arg in args { buf.push(' '); match arg { NewArg::Type(t) => write_type(buf, t), NewArg::Value(v) => write_term(buf, v), } } buf.push(')'); } ``` - [ ] **Step 7: Run the round-trip test to verify it passes** Run: `cargo test --workspace -p ailang-surface round_trip_term_new` Expected: PASS. - [ ] **Step 8: Run the full surface test suite for regressions** Run: `cargo test --workspace -p ailang-surface 2>&1 | tail -15` Expected: 0 failures. The `new` keyword does not collide with any existing keyword (per spec §351 verification). --- ## Task 3: Checker — synth Term::New + 2 new diagnostics + 3 in-source tests **Files:** - Modify: `crates/ailang-check/src/lib.rs:~705` — add `CheckError::NewTypeNotConstructible` + `NewArgKindMismatch` variants (alongside prep.1's two type-scoped variants) - Modify: `crates/ailang-check/src/lib.rs:~759` — `code()` arms - Modify: `crates/ailang-check/src/lib.rs:~837` — `ctx()` arms (note: this match has a `_ =>` catch-all so adding arms is for explicit structured diagnostics, not compile-forced) - Modify: `crates/ailang-check/src/lib.rs:~3005` — replace Task 1's Pattern-E stub in `synth`'s Term match with the real elaboration - Test (in-source): `crates/ailang-check/src/lib.rs` `#[cfg(test)] mod tests` — three new 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 new_resolves_via_type_scope() { // The prep.2 spec's worked example. (module new_demo // (data Counter (ctor MkCounter (con Int))) // (fn new ... (body (term-ctor Counter MkCounter n))) // (fn main ... (body (let c (new Counter 42) ...)))) let module = serde_json::from_value::(serde_json::json!({ "schema": ailang_core::SCHEMA, "name": "new_demo", "imports": [], "defs": [ {"kind": "data", "name": "Counter", "vars": [], "ctors": [ {"name": "MkCounter", "args": [{"k": "con", "name": "Int"}]} ]}, {"kind": "fn", "name": "new", "type": {"k": "fn", "params": [{"k": "con", "name": "Int"}], "ret": {"k": "con", "name": "Counter"}, "effects": []}, "params": ["n"], "body": {"t": "term-ctor", "type": "Counter", "ctor": "MkCounter", "args": [{"t": "var", "name": "n"}]}}, {"kind": "fn", "name": "main", "type": {"k": "fn", "params": [], "ret": {"k": "con", "name": "Counter"}, "effects": []}, "params": [], "body": {"t": "new", "type": "Counter", "args": [{"kind": "value", "value": {"t": "lit", "lit": {"kind": "int", "value": 42}}}]}} ] })).unwrap(); let mut modules = std::collections::BTreeMap::new(); modules.insert("new_demo".to_string(), module); let workspace = ailang_core::workspace::build_workspace(&modules, &["prelude"]) .expect("workspace builds"); let res = check_workspace(&workspace); assert!(res.is_empty(), "(new Counter 42) must check cleanly; got {res:?}"); } #[test] fn new_type_not_constructible() { // (new T 42) where T has NO `new` def in its home module. let module = serde_json::from_value::(serde_json::json!({ "schema": ailang_core::SCHEMA, "name": "no_new", "imports": [], "defs": [ {"kind": "data", "name": "T", "vars": [], "ctors": [ {"name": "MkT", "args": []} ]}, // No `new` def for T. {"kind": "fn", "name": "main", "type": {"k": "fn", "params": [], "ret": {"k": "con", "name": "T"}, "effects": []}, "params": [], "body": {"t": "new", "type": "T", "args": [{"kind": "value", "value": {"t": "lit", "lit": {"kind": "int", "value": 42}}}]}} ] })).unwrap(); let mut modules = std::collections::BTreeMap::new(); modules.insert("no_new".to_string(), module); let workspace = ailang_core::workspace::build_workspace(&modules, &["prelude"]) .expect("workspace builds"); let diagnostics = check_workspace(&workspace); assert!(diagnostics.iter().any(|d| d.code == "new-type-not-constructible"), "expected new-type-not-constructible diagnostic; got {diagnostics:?}"); } #[test] fn new_arg_kind_mismatch_value_where_type() { // (new T arg) where `new` expects a Type arg in position 0 but // a Value was supplied (or vice versa). // Construct T with a `new` fn whose first param is a Type (i.e. // a forall-bound type variable supplied as a Type at the new-site). // Provide a Value where the Type was expected. let module = serde_json::from_value::(serde_json::json!({ "schema": ailang_core::SCHEMA, "name": "kind_mismatch", "imports": [], "defs": [ {"kind": "data", "name": "T", "vars": ["a"], "ctors": [ {"name": "MkT", "args": [{"k": "var", "name": "a"}]} ]}, // `new` declared as `forall a. (a) -> T a`. The new-site // supplies the type-arg via a NewArg::Type, then the value- // arg via a NewArg::Value. Below the new-site mistakenly // supplies NewArg::Value for both positions. {"kind": "fn", "name": "new", "type": {"k": "forall", "vars": ["a"], "constraints": [], "body": {"k": "fn", "params": [{"k": "var", "name": "a"}], "ret": {"k": "con", "name": "T", "args": [{"k": "var", "name": "a"}]}, "effects": []}}, "params": ["x"], "body": {"t": "term-ctor", "type": "T", "ctor": "MkT", "args": [{"t": "var", "name": "x"}]}}, {"kind": "fn", "name": "main", "type": {"k": "fn", "params": [], "ret": {"k": "con", "name": "T", "args": [{"k": "con", "name": "Int"}]}, "effects": []}, "params": [], "body": {"t": "new", "type": "T", "args": [ // WRONG: should be `{kind: "type", value: }` for position 0 {"kind": "value", "value": {"t": "lit", "lit": {"kind": "int", "value": 42}}} ]}} ] })).unwrap(); let mut modules = std::collections::BTreeMap::new(); modules.insert("kind_mismatch".to_string(), module); let workspace = ailang_core::workspace::build_workspace(&modules, &["prelude"]) .expect("workspace builds"); let diagnostics = check_workspace(&workspace); assert!(diagnostics.iter().any(|d| d.code == "new-arg-kind-mismatch"), "expected new-arg-kind-mismatch diagnostic; got {diagnostics:?}"); } ``` - [ ] **Step 2: Run the three tests to verify they fail** Run: `cargo test --workspace -p ailang-check new_resolves_via_type_scope new_type_not_constructible new_arg_kind_mismatch` Expected: FAIL — 1st test fails because Task 1's stub returns `CheckError::Internal`; 2nd + 3rd fail because the variants `NewTypeNotConstructible` / `NewArgKindMismatch` don't exist yet. - [ ] **Step 3: Add the two new `CheckError` variants** In `crates/ailang-check/src/lib.rs`, after `TypeScopedReceiverNotAType { name: String }` at ~line 705 (Task 1's prep.1 variants), add: ```rust /// prep.2 (kernel-extension-mechanics): a `(new T args...)` call /// where `T`'s home module has no `new` def. Code: /// `new-type-not-constructible`. #[error("type `{type_name}` is not constructible: home module `{home_module}` declares no `new` def")] NewTypeNotConstructible { type_name: String, home_module: String, }, /// prep.2 (kernel-extension-mechanics): a `(new T args...)` call /// where the arg at `position` has kind `got` (Type / Value) but /// the `new` def's signature expects `expected`. Code: /// `new-arg-kind-mismatch`. #[error("`(new {type_name} …)` arg at position {position}: expected {expected}, got {got}")] NewArgKindMismatch { type_name: String, position: usize, expected: &'static str, got: &'static str, }, ``` Add the two arms to `CheckError::code()` (the match at ~line 759), right after prep.1's two new arms: ```rust CheckError::NewTypeNotConstructible { .. } => "new-type-not-constructible", CheckError::NewArgKindMismatch { .. } => "new-arg-kind-mismatch", ``` Add the two arms to `CheckError::ctx()` (the match at ~line 837, which has a `_ =>` catch-all — add explicit arms for richer structured diagnostics): ```rust CheckError::NewTypeNotConstructible { type_name, home_module } => { serde_json::json!({"type": type_name, "home_module": home_module}) } CheckError::NewArgKindMismatch { type_name, position, expected, got } => { serde_json::json!({"type": type_name, "position": position, "expected": expected, "actual": got}) } ``` - [ ] **Step 4: Implement the real `synth` Term::New arm** In `crates/ailang-check/src/lib.rs`, replace the Pattern-E stub in `synth`'s Term match (at ~line 3005, the arm added in Task 1) with the real elaboration per spec §318-330. Insert before the existing `Term::Recur` arm: ```rust Term::New { type_name, args } => { // prep.2 §318-330. After prep.1's pre-pass, `type_name` is // already qualified to `.` form (or stays // local if `T` is defined in this module). Resolve to // home module: let (home_module, bare_type) = if let Some((m, t)) = type_name.split_once('.') { (m.to_string(), t.to_string()) } else { // Local — find own home. let owning = env.module_name.clone(); (owning, type_name.clone()) }; // Step 2: find `new` def in home module's globals. let home_globals = env.module_globals.get(&home_module).ok_or_else(|| { CheckError::TypeScopedReceiverNotAType { name: type_name.clone() } })?; let new_ty = home_globals.get("new").cloned().ok_or_else(|| { CheckError::NewTypeNotConstructible { type_name: bare_type.clone(), home_module: home_module.clone(), } })?; // Qualify any bare type-cons in `new`'s signature against // the home module's owner-types (mirror the existing // module-as-receiver path). let owner_types = env .module_types .get(&home_module) .cloned() .unwrap_or_default(); let qualified = qualify_local_types(&new_ty, &home_module, &owner_types); // Step 3: arg count. If `new`'s sig is Forall, first peel // it; the params/ret on the inner Fn type is what we count // against, with the type-vars filled by Type-positional args. let (vars, param_tys, ret_ty, effects) = match &qualified { Type::Forall { vars, body, .. } => match body.as_ref() { Type::Fn { params, ret, effects, .. } => { (vars.clone(), params.clone(), (**ret).clone(), effects.clone()) } _ => return Err(CheckError::FnTypeRequired("new".into())), }, Type::Fn { params, ret, effects, .. } => { (Vec::new(), params.clone(), (**ret).clone(), effects.clone()) } _ => return Err(CheckError::FnTypeRequired("new".into())), }; // Count Type-positional args (these instantiate `vars`) // and Value-positional args (these are checked against // `param_tys`). let type_arg_count = args.iter().filter(|a| matches!(a, NewArg::Type(_))).count(); let value_arg_count = args.iter().filter(|a| matches!(a, NewArg::Value(_))).count(); if type_arg_count != vars.len() { return Err(CheckError::NewArgKindMismatch { type_name: bare_type.clone(), position: 0, expected: if vars.is_empty() { "value-arg" } else { "type-arg" }, got: if type_arg_count > vars.len() { "type-arg" } else { "value-arg" }, }); } if value_arg_count != param_tys.len() { return Err(CheckError::ArityMismatch { callee: format!("new {bare_type}"), expected: param_tys.len(), got: value_arg_count, }); } // Step 4: build the var-binding map from Type-args (in order). let mut var_mapping: BTreeMap = BTreeMap::new(); let mut value_args_iter: Vec<&Term> = Vec::new(); let mut type_vars_iter = vars.iter(); for (i, a) in args.iter().enumerate() { match a { NewArg::Type(t) => { let var = type_vars_iter.next().ok_or_else(|| { CheckError::NewArgKindMismatch { type_name: bare_type.clone(), position: i, expected: "value-arg", got: "type-arg", } })?; var_mapping.insert(var.clone(), t.clone()); } NewArg::Value(v) => value_args_iter.push(v), } } // Step 5: substitute the type-vars into param_tys + ret_ty, // then synth each value-arg against the corresponding // (substituted) param-type. let mut substituted_params: Vec = param_tys .iter() .map(|p| substitute_rigids(p, &var_mapping)) .collect(); let substituted_ret = substitute_rigids(&ret_ty, &var_mapping); for (i, (arg, expected)) in value_args_iter.iter().zip(substituted_params.iter()).enumerate() { let arg_ty = synth(arg, env, counter, residuals)?; unify(&arg_ty, expected).map_err(|_| CheckError::TypeMismatch { expected: expected.clone(), got: arg_ty, })?; } // Effects are inherited from `new`'s signature. for e in &effects { if !env.declared_effects.contains(e) { return Err(CheckError::UndeclaredEffect(e.clone())); } } Ok(substituted_ret) } ``` (The implementer reconciles any helper-name spellings — `unify` may be `unify_types`; `env.module_name` may be `env.owning_module`; `Diagnostic` field shapes follow the existing convention. Adjust to compile.) - [ ] **Step 5: Run the three tests to verify they pass** Run: `cargo test --workspace -p ailang-check new_resolves_via_type_scope new_type_not_constructible new_arg_kind_mismatch` 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 -20` Expected: 0 new failures. No existing fixture uses `Term::New`, so the synth elaboration cannot break pre-existing paths. - [ ] **Step 7: Run the full workspace test suite** Run: `cargo test --workspace 2>&1 | tail -25` Expected: 0 new failures. --- ## Task 4: Schema drift + spec / contract anchors **Files:** - Modify: `crates/ailang-core/tests/design_schema_drift.rs:130-189` — add the `term_new_round_trips` test pin AND the exemplar row (the match arm was already added in Task 1) - Modify: `crates/ailang-core/tests/spec_drift.rs` — add the exemplar row asserting the `(new` anchor in form_a.md - Modify: `crates/ailang-core/specs/form_a.md` — add `(new TYPE-NAME ARG*)` to the surface-keyword cheatsheet - Modify: `design/contracts/0002-data-model.md` — add `{ "t": "new", "type": "", "args": [NewArg...] }` to the JSON-tag block + add the `NewArg` shape definition - [ ] **Step 1: Add the `term_new_round_trips` schema-drift test** In `crates/ailang-core/tests/design_schema_drift.rs`, add a new test fn (place near the other Term-round-trip pins, e.g. after `term_recur_round_trips` if it exists, or alongside the exemplars list): ```rust #[test] fn term_new_round_trips() { // Pin Term::New's JSON shape: `t: "new"`, `type: ""`, // `args: [{kind, value}]`. Each NewArg uses tag = "kind", // content = "value", lowercase ("type" / "value"). let t = Term::New { type_name: "Counter".into(), args: vec![ NewArg::Value(Term::Lit { lit: Literal::Int { value: 42 } }), ], }; let json = serde_json::to_value(&t).expect("serialise"); assert_eq!(json["t"], "new"); assert_eq!(json["type"], "Counter"); let args = json["args"].as_array().expect("args is array"); assert_eq!(args.len(), 1); assert_eq!(args[0]["kind"], "value"); assert!(args[0]["value"].is_object(), "value is the inlined Term JSON"); // Round-trip back through Deserialize. let recovered: Term = serde_json::from_value(json).expect("deserialise"); assert!(matches!(recovered, Term::New { type_name, .. } if type_name == "Counter")); } #[test] fn term_new_type_arg_round_trips() { // Pin: NewArg::Type serializes with kind: "type", value: . let t = Term::New { type_name: "Series".into(), args: vec![ NewArg::Type(Type::Con { name: "Float".into(), args: vec![] }), NewArg::Value(Term::Lit { lit: Literal::Int { value: 3 } }), ], }; let json = serde_json::to_value(&t).expect("serialise"); let args = json["args"].as_array().expect("args is array"); assert_eq!(args[0]["kind"], "type"); assert_eq!(args[0]["value"]["k"], "con"); assert_eq!(args[0]["value"]["name"], "Float"); assert_eq!(args[1]["kind"], "value"); } ``` - [ ] **Step 2: Add the form_a.md anchor for the `new` keyword** In `crates/ailang-core/specs/form_a.md`, locate the surface-keyword cheatsheet (around lines 289-298 per recon; verify by `grep -n "term-ctor" specs/form_a.md`). Add a new line in the keyword-list block: ``` - `(new TYPE-NAME ARG*)` — functional construction; calls `TYPE-NAME`'s home-module `new` def with the supplied args. Each arg is a Type (e.g. `(con Float)`) or a Term. Disambiguation is by syntactic form. ``` - [ ] **Step 3: Add the `Term::New` row to spec_drift.rs's exemplars list** In `crates/ailang-core/tests/spec_drift.rs`, locate the exemplars list (around lines 90-158 per recon). Add a row asserting the `(new` literal appears in `form_a.md`: ```rust ( Term::New { type_name: "T".into(), args: vec![NewArg::Value(Term::Lit { lit: Literal::Int { value: 0 } })], }, "(new", // anchor expected in form_a.md per Step 2 ), ``` (The exact tuple shape depends on the existing exemplars-list format; mirror the prior rows.) - [ ] **Step 4: Add the JSON-tag block to data-model.md** In `design/contracts/0002-data-model.md`, locate the JSON-tag block listing existing Term variants (around lines 107-178 per recon; the block contains entries like `lit`, `var`, `app`, `let`, …). Add a new entry for `new` plus a `NewArg` shape: ```markdown - `{ "t": "new", "type": "", "args": [NewArg, ...] }` — functional construction `(new T args...)`. Resolution: the `type` is looked up via type-scoped resolution to its home module; the home module's `new` def is invoked with the args. Each arg is a `NewArg`. See prep.2 of the kernel-extension-mechanics milestone. `NewArg` shape: - `{ "kind": "type", "value": }` — a Type-positional arg. - `{ "kind": "value", "value": }` — a Value-positional arg. ``` - [ ] **Step 5: Run the schema-drift + spec-drift tests** Run: `cargo test --workspace -p ailang-core --test design_schema_drift && cargo test --workspace -p ailang-core --test spec_drift` Expected: PASS — both new pin functions land green, plus the existing pin tests stay green (no byte-shift on existing fixtures). - [ ] **Step 6: Run the full workspace test suite** Run: `cargo test --workspace 2>&1 | tail -25` Expected: 0 new failures. The iter is complete. --- ## Self-review (planner Step 5) 1. **Spec coverage:** every prep.2 spec subsection has a task — - AST schema (Term::New + NewArg) → Task 1 - Surface (lex/parse/print + round-trip) → Task 2 - Checker (synth elaboration + 2 diagnostics) → Task 3 - Drift / round-trip / spec anchors → Task 4 - Out-of-scope (codegen): Task 1 ships Pattern-D error arms; no real codegen logic. - Pre-pass extension (prep.1 partner) → Task 1, Pattern C arm in `qualify_workspace_term` 2. **Placeholder scan:** grepped for "TBD", "TODO", "implement later", "similar to Task", "add appropriate error handling". Pattern E (the synth stub) explicitly names "Task 3 replaces with the real logic" which is a structured forward-reference within the plan, not a placeholder. The 44+ arm-site table uses "Pattern A/B/…" shorthand but the patterns are inlined in the same task body. No literal placeholder strings. 3. **Type consistency:** `Term::New { type_name, args }` is spelled identically across the AST addition (Task 1 Step 1), the 44+ arm-templates (Task 1 Step 3), the Form-A printer arm (Task 2), the synth arm (Task 3), the drift pin (Task 4), and the in-source tests (Task 3). `NewArg::Type(Type)` and `NewArg::Value(Term)` similarly. `NewTypeNotConstructible { type_name, home_module }` and `NewArgKindMismatch { type_name, position, expected, got }` use the same field names everywhere. 4. **Step granularity:** Task 1's per-site sweep is the longest single step (~30-45 minutes across 44 sites with mechanical patterns). It's mechanical — each site takes 1-2 minutes. The OTHER steps are 2-5 minutes each. The Task-1 sweep is intentionally one step rather than 44 steps because each site is so mechanical that splitting would obscure the rhythm; the explicit per-site table keeps it tractable. 5. **No commit steps:** zero `git commit` instructions appear. The implementer leaves work in the working tree; the Boss commits at iter close. 6. **Pin/replacement substring contiguity:** N/A — this plan does not contain `contains("...")` assertions paired with verbatim text replacements. The drift-test pins (`assert_eq!(json["t"], "new")` etc.) are checked against the JSON-tag derivation, not against a separate verbatim file. Spec anchor strings (`"(new"` in form_a.md) are short identifiers; no line-wrap risk. 7. **Compile-gate vs. deferred-caller ordering:** Task 1's variant addition is the canonical signature change that makes the WHOLE workspace fail to compile until all 44+ callers are updated. Task 1's Step 3 explicitly walks every caller in the same step; the compile-gate at Step 4 verifies `cargo build --workspace 2>&1 | tail -15` shows 0 errors. The synth arm uses Pattern-E STUB in Task 1 (compiles cleanly because `CheckError::Internal(String)` exists); Task 3 replaces with real logic. No caller-threading is deferred past Task 1's compile gate. 8. **Verification-command filter strings:** - `cargo test --workspace -p ailang-surface round_trip_term_new` — Task 2 Steps 2/7 — filter resolves to the new test `round_trip_term_new_mixed_args` (the `round_trip_term_new` prefix matches it). - `cargo test --workspace -p ailang-check new_resolves_via_type_scope new_type_not_constructible new_arg_kind_mismatch` — Task 3 Steps 2/5 — three filters; each matches a NEW test added in Step 1. After Step 1 lands, all three resolve. - `cargo test --workspace -p ailang-core --test design_schema_drift` — Task 4 Step 5 — `--test design_schema_drift` resolves to `crates/ailang-core/tests/design_schema_drift.rs` (verified file exists). - `cargo test --workspace -p ailang-core --test spec_drift` — Task 4 Step 5 — `--test spec_drift` resolves to `crates/ailang-core/tests/spec_drift.rs` (verified file exists). - `cargo build --workspace 2>&1 | tail -15` — Task 1 Steps 2/4 — unfiltered build; count-based assessment via tail. - `cargo test --workspace 2>&1 | tail -25` (and `-30`) — multiple steps — unfiltered suite; count-based assessment. All filter strings resolve to ≥1 named target in the current tree post-Step-1 additions, or to unfiltered count-based outputs. ## Handoff Plan sits in the working tree at `docs/plans/0102-prep.2-term-new-construct.md`. Hand off to `skills/implement` with: path to this plan; no task-range focus (run all 4 tasks in sequence). Iter-completion commit body closes #32.