# raw-buf.2 — RawBuf kernel-tier manifest + checker side — Implementation Plan

> **Parent spec:** `docs/specs/0054-raw-buf.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use the
> `implement` skill to run this plan. Steps use `- [ ]`
> checkboxes for tracking.

**Goal:** Rename `crates/ailang-kernel-stub/` → `crates/ailang-kernel/`, reshape as a family-crate (one Cargo crate hosting all kernel-tier modules as sibling submodules under `src/`), add the new `raw_buf` submodule with the spec's Form-A source, wire `parse_raw_buf` + workspace injection through `ailang-surface`, and ratify the checker-visible surface via four new tests (round-trip + 3 E2E).

**Architecture:** Three concerns layered into seven tasks. Task 1 does the wholesale crate-rename + reshape (kernel_stub re-housed under `src/kernel_stub/`, public-symbol surface preserved via `pub use kernel_stub::SOURCE as STUB_AIL;`). Task 2 adds the `raw_buf` submodule + `RAW_BUF_AIL` re-export. Task 3 wires raw_buf into `ailang-surface` (parse fn + re-export + workspace injection + workspace_pin bump). Tasks 4-7 land the four tests. The codegen path stays *unchanged* — the iter raw-buf.2 acceptance is the existing Term::New-deferral diagnostic firing precisely on `(new RawBuf …)` consumer code (a new `intercept-not-registered` diagnostic was hedged in the spec but rejected at plan time as disposable infra; the existing deferral already names "milestone raw-buf" and is self-describing).

**Tech Stack:** Rust 1.x (stable), `crates/ailang-kernel/` (new family-crate), `crates/ailang-surface/` (parse + workspace injection), `crates/ailang-core/tests/` (round-trip + workspace_pin), `crates/ail/tests/` (three E2E), `examples/` (three fixtures).

---

**Files this plan creates or modifies:**

- Create: `crates/ailang-kernel/Cargo.toml` — renamed manifest, package name `ailang-kernel`.
- Create: `crates/ailang-kernel/src/lib.rs` — family-crate hub with `mod` declarations and re-exports.
- Create: `crates/ailang-kernel/src/kernel_stub/mod.rs` — `pub const SOURCE: &str = include_str!("source.ail");` + the rustdoc lifted from the old `STUB_AIL` rustdoc.
- Create: `crates/ailang-kernel/src/kernel_stub/source.ail` — the Form-A text currently embedded in `crates/ailang-kernel-stub/src/lib.rs:27-37` (the `r#"…"#` body), now an `.ail` file.
- Create: `crates/ailang-kernel/src/raw_buf/mod.rs` — same shape as `kernel_stub/mod.rs`.
- Create: `crates/ailang-kernel/src/raw_buf/source.ail` — the new Form-A text per spec § Concrete code shapes "Primary — the raw-buf kernel-tier module" (lines 158-201 of the spec).
- Delete: `crates/ailang-kernel-stub/Cargo.toml` — replaced by the renamed file at `crates/ailang-kernel/Cargo.toml`.
- Delete: `crates/ailang-kernel-stub/src/lib.rs` — content fans out into the new `lib.rs` (re-exports) + `kernel_stub/{mod.rs, source.ail}`.
- Delete: `crates/ailang-kernel-stub/` (whole folder, after contents are evacuated by the above).
- Modify: `Cargo.toml:7` — workspace member rename.
- Modify: `Cargo.toml:37` — workspace dep alias rename.
- Modify: `crates/ailang-surface/Cargo.toml:9` — dep name rename.
- Modify: `crates/ailang-surface/src/loader.rs:45-57` — rename references `ailang_kernel_stub::STUB_AIL` → `ailang_kernel::STUB_AIL` (rustdoc L48, call L55, expect-message L56) AND add `parse_raw_buf` fn after `parse_kernel_stub`.
- Modify: `crates/ailang-surface/src/loader.rs:123-138` — extend the workspace injection in `load_workspace` to also inject `raw_buf`.
- Modify: `crates/ailang-surface/src/lib.rs:39` — extend the re-export to also include `parse_raw_buf`.
- Modify: `crates/ailang-core/tests/workspace_pin.rs:52-58` — bump count `4 → 5`, extend the auto-injects comment, add `contains_key("raw_buf")` assertion.
- Modify: `design/INDEX.md:112` — update the path-ref in the kernel-extensions Models row (`ailang-kernel-stub` → `ailang-kernel/src/kernel_stub`). Retire-language stays for raw-buf.3.
- Modify: `CLAUDE.md` — update the "Code layout" table row for the renamed crate (path + one-line role description; the role transitions from "carries STUB_AIL only" to "family-crate hosting all kernel-tier modules").
- Test: `crates/ailang-core/tests/design_schema_drift.rs:765+` — add `raw_buf_module_round_trips` after the existing `kernel_stub_module_round_trips` test.
- Test: `examples/raw_buf_consumer_int.ail` — fixture for the check-passes E2E.
- Test: `examples/raw_buf_consumer_str_reject.ail` — fixture for the param-in reject E2E.
- Test: `examples/raw_buf_consumer_build_defer.ail` — fixture for the Term::New-deferral E2E.
- Test: `crates/ail/tests/raw_buf_check_e2e.rs` — `raw_buf_check_e2e_consumer_passes` — `ail check` exit 0 on the int-element consumer.
- Test: `crates/ail/tests/raw_buf_param_in_reject_e2e.rs` — `raw_buf_param_in_reject_consumer_fails_at_check` — `ail check` exits non-zero with `param-not-in-restricted-set` substring.
- Test: `crates/ail/tests/raw_buf_build_intercept_missing_e2e.rs` — `raw_buf_build_term_new_defers_to_raw_buf_3` — `ail build` exits non-zero with `Term::New requires the type's` substring.

---

### Task 1: Crate rename + family-crate reshape — kernel_stub re-housed, public-symbol surface preserved

**Files:**
- Move: `crates/ailang-kernel-stub/` → `crates/ailang-kernel/` (and reshape `src/` inside)
- Modify: `Cargo.toml:7`, `Cargo.toml:37`
- Modify: `crates/ailang-surface/Cargo.toml:9`
- Modify: `crates/ailang-surface/src/loader.rs:45-57`
- Modify: `design/INDEX.md:112`
- Modify: `CLAUDE.md` (Code-layout table row)

- [ ] **Step 1: Move the crate folder.**

Run: `git mv crates/ailang-kernel-stub crates/ailang-kernel`
Expected: folder rename succeeds; `git status` shows the renames.

- [ ] **Step 2: Rewrite `crates/ailang-kernel/Cargo.toml` package name.**

Edit `crates/ailang-kernel/Cargo.toml`. Change the `name = "ailang-kernel-stub"` line to `name = "ailang-kernel"`. Leave all other lines (edition, version, dependencies — currently empty `[dependencies]`) unchanged. The package description (if any) may stay verbatim or get an inline updated phrase: "Family-crate hosting the embedded Form-A sources of every kernel-tier module."

- [ ] **Step 3: Carve out `kernel_stub/source.ail` from the current `lib.rs` body.**

Create the new file `crates/ailang-kernel/src/kernel_stub/source.ail` with the exact Form-A text currently embedded between the `r#"` and `"#` markers in `crates/ailang-kernel/src/lib.rs` at lines 27-37 (the `STUB_AIL` const body). Verbatim — preserve every newline, indent, and trailing newline. The expected content is:

```
(module kernel_stub
  (kernel)
  (data StubT (vars a)
    (ctor Stub a)
    (param-in (a Int Float)))
  (fn new
    (doc "Construct StubT<Int> from an Int. Exercises Term::New end-to-end.")
    (type (fn-type (params (con Int)) (ret (con StubT (con Int)))))
    (params x)
    (body (term-ctor StubT Stub x))))
```

(Verify against the source bytes before writing — the implementer must `git show HEAD:crates/ailang-kernel-stub/src/lib.rs` if the current `lib.rs` body diverges; the source is authoritative.)

- [ ] **Step 4: Create `crates/ailang-kernel/src/kernel_stub/mod.rs`.**

Write the following exact content:

```rust
//! Kernel-stub submodule — minimal ratifying fixture for the
//! kernel-extension-mechanics milestone (prep.3). The Form-A
//! text lives in the sibling `source.ail`.
//!
//! No domain content. The stub may be retired or repositioned
//! when a real second kernel-tier consumer (the `raw-buf`
//! milestone) lands; until then it stays as the
//! ratifying-fixture anchor.

/// Source-of-truth Form-A text for the stub kernel module. Parsed
/// by `ailang_surface::parse_kernel_stub` (and round-trip-pinned by
/// `kernel_stub_module_round_trips` in `design_schema_drift.rs`).
///
/// Ships a `(fn new ...)` def so consumers can spell `(new StubT 42)`,
/// the worked-consumer example from prep.3 of the spec — without it,
/// the stub's `Term::New` end-to-end ratification story is broken
/// (per fieldtest F4, 2026-05-28).
pub const SOURCE: &str = include_str!("source.ail");
```

- [ ] **Step 5: Rewrite `crates/ailang-kernel/src/lib.rs` as the family-crate hub.**

Replace the entire contents of `crates/ailang-kernel/src/lib.rs` with:

```rust
//! Kernel-tier modules — family-crate hosting the Form-A source
//! of every kernel-tier `.ail` module the AILang workspace
//! auto-injects. One Cargo crate, one Rust submodule per
//! kernel-tier module, one `pub const SOURCE` per submodule.
//!
//! The acyclic dependency chain is preserved:
//! `ailang-surface → ailang-kernel → ailang-core`. Per-module
//! parse hops live in `ailang-surface` (`parse_kernel_stub`,
//! `parse_raw_buf`, …) so this crate carries zero parser code.

mod kernel_stub;

pub use kernel_stub::SOURCE as STUB_AIL;
```

(Task 2 will add a `mod raw_buf;` line and a matching re-export — leave them out of this task; the kernel_stub submodule alone must build clean here so the rename can land as a strict refactor.)

- [ ] **Step 6: Update `Cargo.toml:7` workspace member.**

Edit the workspace `Cargo.toml`. Find line 7 (the member entry currently reading `"crates/ailang-kernel-stub",`) and change it to `"crates/ailang-kernel",`. Preserve the trailing comma and surrounding whitespace.

- [ ] **Step 7: Update `Cargo.toml:37` workspace dep alias.**

Edit the workspace `Cargo.toml`. Find line 37 (the dep alias currently reading `ailang-kernel-stub = { path = "crates/ailang-kernel-stub" }`) and change it to `ailang-kernel = { path = "crates/ailang-kernel" }`.

- [ ] **Step 8: Update `crates/ailang-surface/Cargo.toml:9` dep name.**

Edit `crates/ailang-surface/Cargo.toml`. Find line 9 (`ailang-kernel-stub.workspace = true`) and change to `ailang-kernel.workspace = true`.

- [ ] **Step 9: Update `crates/ailang-surface/src/loader.rs` use-paths + rustdoc + expect-message.**

Three edits in this file:

  (a) Line 48 (rustdoc): change `Source-of-truth: \`ailang_kernel_stub::STUB_AIL\`.` to `Source-of-truth: \`ailang_kernel::STUB_AIL\`.`

  (b) Line 55 (call): change `crate::parse(ailang_kernel_stub::STUB_AIL)` to `crate::parse(ailang_kernel::STUB_AIL)`.

  (c) Line 56 (expect-message): change `"ailang_kernel_stub::STUB_AIL must parse as a Module"` to `"ailang_kernel::STUB_AIL must parse as a Module"`.

- [ ] **Step 10: Update `design/INDEX.md:112`.**

Edit `design/INDEX.md`. The Models-section row for `kernel-extensions` (line 112) currently contains the literal `ailang-kernel-stub` referring to the crate path. Change every `ailang-kernel-stub` occurrence in that row to `ailang-kernel/src/kernel_stub` (the new submodule path). The retire-language ("planned for retirement when raw-buf lands a real second consumer") stays — raw-buf.3 close updates that sentence.

- [ ] **Step 11: Update `CLAUDE.md` "Code layout" table row for the renamed crate.**

Edit `CLAUDE.md`. Locate the "Code layout" table; find the row that currently reads `crates/ailang-kernel-stub/` in the path column. Change the path to `crates/ailang-kernel/`. Update the role-description column to:

> Family-crate hosting the Form-A source of every kernel-tier `.ail` module. Sub-modules under `src/` carry one `pub const SOURCE` each (`kernel_stub`, `raw_buf` from raw-buf.2 onwards). Parse hops live in `ailang-surface`; this crate is the zero-dependency leaf that lets `ailang-surface → ailang-kernel → ailang-core` stay acyclic.

The "Zero-dependency leaf … `kernel_stub` ratifying-fixture" language is retired now that the crate hosts more than one submodule. The `raw-buf` milestone retire-language stays in raw-buf.3 close.

- [ ] **Step 12: Build the workspace.**

Run: `cargo build --workspace 2>&1 | tail -8`
Expected: build succeeds; zero errors, zero warnings about `ailang-kernel-stub` (the crate is fully renamed; no dangling refs).

- [ ] **Step 13: Run the full workspace test suite to confirm zero behavioural change.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 667  failed: 0  ignored: 2` (same as the post-raw-buf.1 baseline; the rename is pure refactor, no test count change yet).

---

### Task 2: Add raw_buf submodule + RAW_BUF_AIL re-export

**Files:**
- Create: `crates/ailang-kernel/src/raw_buf/mod.rs`
- Create: `crates/ailang-kernel/src/raw_buf/source.ail`
- Modify: `crates/ailang-kernel/src/lib.rs` (add `mod raw_buf;` + re-export)

- [ ] **Step 1: Create `crates/ailang-kernel/src/raw_buf/source.ail`.**

Write the Form-A source verbatim per spec § "Primary — the raw-buf kernel-tier module" (spec lines 158-201). The content is:

```
(module raw_buf
  (kernel)
  (data RawBuf (vars a)
    (ctor B (storage-tag))
    (param-in (a Int Float Bool)))

  (fn new
    (doc "Allocate uninitialised RawBuf of capacity n. Codegen
          intercept new__RawBuf__<T> emits @ailang_rc_alloc + the
          size header. Element bytes are uninitialised — caller
          must (set …) before (get …).")
    (type (fn-type (params (con Int)) (ret (own (RawBuf a)))))
    (params n)
    (body (term-ctor RawBuf B n)))

  (fn get
    (doc "Indexed read. UB if i >= (size b); caller checks
          bounds. Codegen intercept RawBuf_get__<T> emits
          getelementptr + load.")
    (type (fn-type
            (params (borrow (RawBuf a)) (con Int))
            (ret (con a))))
    (params b i)
    (body (term-ctor RawBuf B 0)))

  (fn set
    (doc "Indexed write. Linear: own in, own out. Under
          uniqueness, in-place; under shared, copy-on-write
          (Issue #22 territory). Codegen intercept
          RawBuf_set__<T> emits getelementptr + store.")
    (type (fn-type
            (params (own (RawBuf a)) (con Int) (con a))
            (ret (own (RawBuf a)))))
    (params b i v)
    (body b))

  (fn size
    (doc "Element count. Codegen intercept RawBuf_size__<T>
          emits a single i64 load from the slab header.")
    (type (fn-type (params (borrow (RawBuf a))) (ret (con Int))))
    (params b)
    (body 0)))
```

End the file with a single newline (no trailing blank lines). The placeholder bodies (`(term-ctor RawBuf B n)`, `(term-ctor RawBuf B 0)`, `b`, `0`) match the existing convention from `examples/prelude.ail` — codegen never executes them (the intercept registry will override in raw-buf.3); they exist solely to satisfy the round-trip invariant.

- [ ] **Step 2: Create `crates/ailang-kernel/src/raw_buf/mod.rs`.**

Write:

```rust
//! Raw-buf submodule — embeds the Form-A source of the `raw_buf`
//! kernel-tier module. Parsed by `ailang_surface::parse_raw_buf`
//! (and round-trip-pinned by `raw_buf_module_round_trips` in
//! `design_schema_drift.rs`).

/// Source-of-truth Form-A text for the `raw_buf` kernel module.
///
/// Declares `(data RawBuf (vars a) (ctor B …) (param-in (a Int Float Bool)))`
/// plus `new`, `get`, `set`, `size` fns with placeholder bodies.
/// The codegen intercept entries that replace the placeholder
/// bodies at lowering time ship in raw-buf.3.
pub const SOURCE: &str = include_str!("source.ail");
```

- [ ] **Step 3: Extend `crates/ailang-kernel/src/lib.rs` to register the new submodule + re-export its `SOURCE`.**

Edit `crates/ailang-kernel/src/lib.rs`. After the existing `mod kernel_stub;` line, add `mod raw_buf;`. After the existing `pub use kernel_stub::SOURCE as STUB_AIL;` line, add `pub use raw_buf::SOURCE as RAW_BUF_AIL;`. The final file content is:

```rust
//! Kernel-tier modules — family-crate hosting the Form-A source
//! of every kernel-tier `.ail` module the AILang workspace
//! auto-injects. One Cargo crate, one Rust submodule per
//! kernel-tier module, one `pub const SOURCE` per submodule.
//!
//! The acyclic dependency chain is preserved:
//! `ailang-surface → ailang-kernel → ailang-core`. Per-module
//! parse hops live in `ailang-surface` (`parse_kernel_stub`,
//! `parse_raw_buf`, …) so this crate carries zero parser code.

mod kernel_stub;
mod raw_buf;

pub use kernel_stub::SOURCE as STUB_AIL;
pub use raw_buf::SOURCE as RAW_BUF_AIL;
```

- [ ] **Step 4: Build the workspace.**

Run: `cargo build --workspace 2>&1 | tail -8`
Expected: build succeeds. A dead-code warning on `RAW_BUF_AIL` may fire (the re-export is consumed only after Task 3 wires it through `ailang-surface`); accept it.

- [ ] **Step 5: Full workspace test run — no test count change yet.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 667  failed: 0  ignored: 2`. Same as Task 1 (the raw_buf submodule exists but no test consumes it).

---

### Task 3: Wire raw_buf into ailang-surface — parse fn + re-export + workspace injection + workspace_pin bump

**Files:**
- Modify: `crates/ailang-surface/src/loader.rs` (add `parse_raw_buf` after `parse_kernel_stub`; extend `load_workspace` injection)
- Modify: `crates/ailang-surface/src/lib.rs:39` (extend re-export)
- Modify: `crates/ailang-core/tests/workspace_pin.rs:52-58` (count bump + comment + new assertion)

- [ ] **Step 1: Add `parse_raw_buf` in `crates/ailang-surface/src/loader.rs`.**

Insert the following block immediately after the existing `parse_kernel_stub` fn (which currently ends at line 57). Place it before the `fn is_ail_source(path: &Path) -> bool {` line at L59:

```rust
/// raw-buf.2 (raw-buf milestone): parse the embedded raw_buf
/// kernel-tier module bytes into a `Module`. Mirror of
/// [`parse_kernel_stub`].
///
/// Source-of-truth: `ailang_kernel::RAW_BUF_AIL`. Declares the
/// `RawBuf` TypeDef with `param-in (a Int Float Bool)` plus the
/// four operation signatures (`new`, `get`, `set`, `size`) with
/// placeholder bodies that codegen replaces via the intercept
/// registry (raw-buf.3).
///
/// Panics on parse failure — the source is build-time-validated
/// by every drift test run.
pub fn parse_raw_buf() -> Module {
    crate::parse(ailang_kernel::RAW_BUF_AIL)
        .expect("ailang_kernel::RAW_BUF_AIL must parse as a Module")
}
```

- [ ] **Step 2: Extend the workspace injection in `load_workspace` (loader.rs).**

The current injection block at lines 123-132 reserves the name `kernel_stub` and inserts `parse_kernel_stub()` into the modules map. Insert an analogous block for `raw_buf` immediately AFTER the kernel_stub block (after line 132, before the existing `// Derive the implicit-imports list …` comment at L134):

```rust
    // parse_raw_buf() injects the raw_buf kernel-tier base
    // extension — declares the `RawBuf` TypeDef with the
    // `param-in (a Int Float Bool)` element-type restriction and
    // the four operation signatures. Carries `(kernel)`, so the
    // kernel-flag filter below picks it up automatically. Per
    // raw-buf milestone (Gitea #7); codegen intercepts ship in
    // raw-buf.3.
    if modules.contains_key("raw_buf") {
        return Err(WorkspaceLoadError::ReservedModuleName {
            name: "raw_buf".to_string(),
        });
    }
    modules.insert("raw_buf".to_string(), parse_raw_buf());
```

- [ ] **Step 3: Extend the re-export in `crates/ailang-surface/src/lib.rs:39`.**

Edit `crates/ailang-surface/src/lib.rs`. Locate line 39 — the `pub use loader::{load_module, load_workspace, parse_kernel_stub, parse_prelude, PRELUDE_AIL};` block. Insert `parse_raw_buf` into the list (alphabetically between `parse_prelude` and `PRELUDE_AIL`, or anywhere in the brace-list — the order does not matter functionally). Result:

```rust
pub use loader::{load_module, load_workspace, parse_kernel_stub, parse_prelude, parse_raw_buf, PRELUDE_AIL};
```

- [ ] **Step 4: Bump `workspace_pin.rs:52-58` — count, comment, and the new `contains_key` assertion.**

Edit `crates/ailang-core/tests/workspace_pin.rs`. Lines 52-58 currently read:

```rust
    // the loader auto-injects two built-in kernel-tier modules
    // (`prelude` and `kernel_stub` — see prep.3 of the
    // kernel-extension-mechanics milestone), so the count is the
    // user's two modules plus those two.
    assert_eq!(ws.modules.len(), 4);
    assert!(ws.modules.contains_key("prelude"));
    assert!(ws.modules.contains_key("kernel_stub"));
```

Replace with:

```rust
    // the loader auto-injects three built-in kernel-tier modules
    // (`prelude`, `kernel_stub`, and `raw_buf` — the last added
    // in raw-buf.2 of the raw-buf milestone), so the count is
    // the user's two modules plus those three. raw-buf.3 will
    // retire `kernel_stub`, dropping the count back to 4.
    assert_eq!(ws.modules.len(), 5);
    assert!(ws.modules.contains_key("prelude"));
    assert!(ws.modules.contains_key("kernel_stub"));
    assert!(ws.modules.contains_key("raw_buf"));
```

- [ ] **Step 5: Build the workspace.**

Run: `cargo build --workspace 2>&1 | tail -8`
Expected: build succeeds; the `RAW_BUF_AIL` dead-code warning (from Task 2) is gone (the re-export is now consumed by `parse_raw_buf`).

- [ ] **Step 6: Run the workspace_pin test specifically to confirm the count assertion.**

Run: `cargo test -p ailang-core --test workspace_pin loads_example_workspace_happy_path`
Expected: PASS — `ws.modules.len()` is now 5, all three contains_key assertions hold.

- [ ] **Step 7: Full workspace test run.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 667  failed: 0  ignored: 2`. No test count change yet (the bump is a 4→5 edit on an existing assertion, not a new test).

---

### Task 4: Round-trip test `raw_buf_module_round_trips`

**Files:**
- Modify: `crates/ailang-core/tests/design_schema_drift.rs:765+` (append after the existing kernel_stub round-trip test which ends at L764)

- [ ] **Step 1: Append `raw_buf_module_round_trips` after L764.**

Edit `crates/ailang-core/tests/design_schema_drift.rs`. After the closing `}` of `kernel_stub_module_round_trips` at line 764, insert the following test:

```rust

/// raw-buf.2 (raw-buf milestone): pin the JSON byte-shape of the
/// raw_buf kernel-tier base-extension module. Mirror of
/// `kernel_stub_module_round_trips`. Catches regressions in
/// `Module.kernel`, `TypeDef.param-in` (with three elements:
/// Int / Float / Bool), and the ctor + four-fn manifest shape
/// the spec lists in § Concrete code shapes lines 158-201.
#[test]
fn raw_buf_module_round_trips() {
    let m = ailang_surface::parse_raw_buf();
    assert!(m.kernel, "raw_buf module is kernel-tier");
    assert_eq!(m.name, "raw_buf");

    let json = serde_json::to_value(&m).expect("serialise raw_buf module");
    assert_eq!(json["kernel"], true);
    assert_eq!(json["name"], "raw_buf");

    let recovered: Module =
        serde_json::from_value(json).expect("raw_buf module round-trips through serde");
    assert!(recovered.kernel);
    assert_eq!(recovered.name, "raw_buf");

    // Locate the RawBuf TypeDef and confirm param_in is intact
    // for all three element types Int / Float / Bool (spec §
    // Concrete code shapes line 163: `(param-in (a Int Float Bool))`).
    let td = recovered.defs.iter().find_map(|d| match d {
        Def::Type(t) if t.name == "RawBuf" => Some(t),
        _ => None,
    }).expect("RawBuf TypeDef present in raw_buf module");
    let allowed = td.param_in.get("a").expect("RawBuf.a restricted");
    assert!(allowed.contains("Int"));
    assert!(allowed.contains("Float"));
    assert!(allowed.contains("Bool"));
}
```

- [ ] **Step 2: Run the new round-trip test.**

Run: `cargo test -p ailang-core --test design_schema_drift raw_buf_module_round_trips`
Expected: PASS — the parsed raw_buf module serialises to JSON, round-trips through serde, and the `param_in` for `a` contains all three element types.

- [ ] **Step 3: Full workspace test run — count goes up by one.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 668  failed: 0  ignored: 2` (+1 from the new round-trip).

---

### Task 5: E2E `raw_buf_check_e2e` — consumer with `(con RawBuf (con Int))` checks clean

**Files:**
- Create: `examples/raw_buf_consumer_int.ail`
- Create: `crates/ail/tests/raw_buf_check_e2e.rs`

- [ ] **Step 1: Create `examples/raw_buf_consumer_int.ail`.**

Write:

```
(module raw_buf_consumer_int
  (fn read_first
    (doc "Consumer demonstrating (con RawBuf (con Int)) in a type slot. Kernel-tier auto-import (prep.3) makes RawBuf visible without an explicit (import raw_buf). The body calls RawBuf.get via the type-scoped namespacing landed in prep.1.")
    (type (fn-type (params (borrow (RawBuf (con Int)))) (ret (con Int))))
    (params buf)
    (body (app RawBuf.get buf 0))))
```

- [ ] **Step 2: Create `crates/ail/tests/raw_buf_check_e2e.rs`.**

Write:

```rust
//! E2E: a consumer fixture that mentions `(con RawBuf (con Int))`
//! in a type signature and calls `RawBuf.get` must type-check
//! clean. raw-buf.2 ratification — the kernel-tier auto-import
//! path (prep.3) makes `RawBuf` visible without an explicit
//! `(import raw_buf)`, and type-scoped namespacing (prep.1)
//! resolves `RawBuf.get` to the kernel-tier fn.

use std::path::PathBuf;
use std::process::Command;

#[test]
fn raw_buf_check_e2e_consumer_passes() {
    let manifest_dir = env!("CARGO_MANIFEST_DIR");
    let repo_root = PathBuf::from(manifest_dir).join("../..");
    let fixture = repo_root.join("examples/raw_buf_consumer_int.ail");

    let check = Command::new(env!("CARGO_BIN_EXE_ail"))
        .arg("check")
        .arg(&fixture)
        .output()
        .expect("ail check failed to spawn");
    assert!(
        check.status.success(),
        "ail check failed: stdout={} stderr={}",
        String::from_utf8_lossy(&check.stdout),
        String::from_utf8_lossy(&check.stderr)
    );
}
```

- [ ] **Step 3: Run the new test.**

Run: `cargo test -p ail --test raw_buf_check_e2e raw_buf_check_e2e_consumer_passes`
Expected: PASS — `ail check` exits 0 on the consumer fixture.

- [ ] **Step 4: Full workspace test run — count goes up by one.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 669  failed: 0  ignored: 2` (+1 from this E2E).

---

### Task 6: E2E `raw_buf_param_in_reject_e2e` — consumer with `(con RawBuf (con Str))` rejected at check

**Files:**
- Create: `examples/raw_buf_consumer_str_reject.ail`
- Create: `crates/ail/tests/raw_buf_param_in_reject_e2e.rs`

- [ ] **Step 1: Create `examples/raw_buf_consumer_str_reject.ail`.**

Write:

```
(module raw_buf_consumer_str_reject
  (fn cant_str_raw
    (doc "Must-fail fixture. RawBuf's TypeDef ships `(param-in (a Int Float Bool))` — instantiating with Str must be rejected by the checker with the prep.3 `param-not-in-restricted-set` diagnostic. Mirrors fieldtest F8 on the prep.3 stub.")
    (type (fn-type (params (borrow (RawBuf (con Str)))) (ret (con Str))))
    (params buf)
    (body (app RawBuf.get buf 0))))
```

- [ ] **Step 2: Create `crates/ail/tests/raw_buf_param_in_reject_e2e.rs`.**

Write:

```rust
//! E2E: a consumer fixture that instantiates `(con RawBuf (con Str))`
//! in any type slot must be rejected by `ail check`, because
//! RawBuf's TypeDef declares `(param-in (a Int Float Bool))` —
//! Str is outside the restricted set. raw-buf.2 ratification of
//! the param-in mechanism on a real-payload extension (the
//! prep.3 stub fixture exercised it only on the StubT type).

use std::path::PathBuf;
use std::process::Command;

#[test]
fn raw_buf_param_in_reject_consumer_fails_at_check() {
    let manifest_dir = env!("CARGO_MANIFEST_DIR");
    let repo_root = PathBuf::from(manifest_dir).join("../..");
    let fixture = repo_root.join("examples/raw_buf_consumer_str_reject.ail");

    let check = Command::new(env!("CARGO_BIN_EXE_ail"))
        .arg("check")
        .arg(&fixture)
        .output()
        .expect("ail check failed to spawn");
    assert!(
        !check.status.success(),
        "ail check unexpectedly succeeded: stdout={} stderr={}",
        String::from_utf8_lossy(&check.stdout),
        String::from_utf8_lossy(&check.stderr)
    );
    let stderr = String::from_utf8_lossy(&check.stderr);
    assert!(
        stderr.contains("param-not-in-restricted-set"),
        "expected `param-not-in-restricted-set` substring in stderr; got: {stderr}"
    );
}
```

- [ ] **Step 3: Run the new test.**

Run: `cargo test -p ail --test raw_buf_param_in_reject_e2e raw_buf_param_in_reject_consumer_fails_at_check`
Expected: PASS — `ail check` exits non-zero with the `param-not-in-restricted-set` diagnostic code in stderr.

(If the diagnostic format wraps the code (e.g. `[param-not-in-restricted-set]` with brackets, or `error[param-not-in-restricted-set]:`), the substring assertion still hits — the test asserts on the bare code string. If the actual diagnostic uses a different code spelling (e.g. underscore-separated), update the assertion substring to match the reality; the prep.3 fieldtest F8 verified the code as written above.)

- [ ] **Step 4: Full workspace test run — count goes up by one.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 670  failed: 0  ignored: 2`.

---

### Task 7: E2E `raw_buf_build_intercept_missing_e2e` — Term::New deferral at build

**Files:**
- Create: `examples/raw_buf_consumer_build_defer.ail`
- Create: `crates/ail/tests/raw_buf_build_intercept_missing_e2e.rs`

- [ ] **Step 1: Create `examples/raw_buf_consumer_build_defer.ail`.**

Write:

```
(module raw_buf_consumer_build_defer
  (fn main
    (doc "Term::New invocation: the checker accepts (new RawBuf …) because raw_buf ships (fn new …), but the codegen defers Term::New until raw-buf.3 ships the desugar pass. `ail check` clean; `ail build` fails with the existing deferral message naming `milestone raw-buf`. raw-buf.3 inverts this test to PASS once the desugar lands.")
    (type (fn-type (params) (ret (con Int))))
    (params)
    (body
      (let buf (new RawBuf (con Int) 3)
        (app RawBuf.get buf 0)))))
```

- [ ] **Step 2: Create `crates/ail/tests/raw_buf_build_intercept_missing_e2e.rs`.**

Write:

```rust
//! E2E: a consumer fixture that invokes `(new RawBuf (con Int) 3)`
//! type-checks clean (RawBuf has a `(fn new …)` def, satisfying
//! prep.2's checker) but fails at `ail build` because the
//! codegen Term::New arm still emits the deferral diagnostic
//! that prep.2 introduced and raw-buf.3 will retire. This test
//! pins the manifest/codegen separation that is raw-buf.2's
//! load-bearing acceptance: the checker accepts but the binary
//! does not yet build. raw-buf.3 inverts this test to PASS
//! (delete + replace with an end-to-end build-and-run variant).

use std::path::PathBuf;
use std::process::Command;

#[test]
fn raw_buf_build_term_new_defers_to_raw_buf_3() {
    let manifest_dir = env!("CARGO_MANIFEST_DIR");
    let repo_root = PathBuf::from(manifest_dir).join("../..");
    let fixture = repo_root.join("examples/raw_buf_consumer_build_defer.ail");
    let bin = repo_root.join("target/debug/raw_buf_consumer_build_defer_test_bin");

    let build = Command::new(env!("CARGO_BIN_EXE_ail"))
        .arg("build")
        .arg(&fixture)
        .arg("-o")
        .arg(&bin)
        .output()
        .expect("ail build failed to spawn");
    assert!(
        !build.status.success(),
        "ail build unexpectedly succeeded: stdout={} stderr={}",
        String::from_utf8_lossy(&build.stdout),
        String::from_utf8_lossy(&build.stderr)
    );
    let stderr = String::from_utf8_lossy(&build.stderr);
    assert!(
        stderr.contains("Term::New requires the type's"),
        "expected Term::New deferral message; got: {stderr}"
    );
}
```

- [ ] **Step 3: Run the new test.**

Run: `cargo test -p ail --test raw_buf_build_intercept_missing_e2e raw_buf_build_term_new_defers_to_raw_buf_3`
Expected: PASS — `ail check` accepts the fixture, then `ail build` errors with the Term::New deferral substring.

- [ ] **Step 4: Final full workspace test run.**

Run: `cargo test --workspace 2>&1 | grep -E "^test result:" | awk -F"[: ;]+" '{p+=$4; f+=$6; i+=$8} END{print "passed:",p," failed:",f," ignored:",i}'`
Expected: `passed: 671  failed: 0  ignored: 2` — baseline 667 + 4 new tests (round-trip in Task 4 + three E2E in Tasks 5/6/7).

---

## Self-review

1. **Spec coverage.**
   - § Architecture point 2 ("Rename `crates/ailang-kernel-stub/` to `crates/ailang-kernel/` and re-shape it as a family-crate"): Task 1.
   - § Architecture point 2 ("the renamed crate carries `src/kernel_stub/{mod.rs, source.ail}` and gains `src/raw_buf/{mod.rs, source.ail}`"): Tasks 1 + 2.
   - § Architecture point 2 ("`src/lib.rs` re-exports each submodule's `SOURCE` const under a stable name"): Tasks 1 + 2.
   - § Architecture point 2 ("`parse_kernel_stub` joined by `parse_raw_buf` in `ailang-surface`"): Task 3.
   - § Architecture point 2 ("Checker accepts a consumer-fixture `(con RawBuf (con Int))` in a type slot; `ail check` passes"): Task 5.
   - § Architecture point 2 ("`ail build` fails precisely with `intercept-not-registered: new__RawBuf__Int` (or the existing Term::New-deferral diagnostic)"): Task 7 (resolves the spec's "or" hedge by picking the Term::New-deferral path — no new diagnostic code; the existing message ships).
   - § Components row 2: covered by Tasks 1 + 2 + 3.
   - § Testing strategy raw-buf.2 bullet 1 (raw_buf_check_e2e): Task 5.
   - § Testing strategy raw-buf.2 bullet 2 (raw_buf_param_in_reject_e2e): Task 6.
   - § Testing strategy raw-buf.2 bullet 3 (raw_buf_build_intercept_missing_e2e): Task 7.
   - § Testing strategy raw-buf.2 bullet 4 (round-trip): Task 4.
   - § Testing strategy raw-buf.2 bullet 5 (workspace_pin 4→5): Task 3.

2. **Placeholder scan.** No "TBD", no "TODO", no "implement later", no "similar to Task". The Task 6 Step 3 parenthetical ("If the diagnostic format wraps the code …") is a real fallback the implementer may need; it names the concrete adjustment, not a placeholder.

3. **Type consistency.** Symbols used across tasks: `STUB_AIL`, `RAW_BUF_AIL`, `SOURCE` (per submodule), `kernel_stub`, `raw_buf`, `parse_kernel_stub`, `parse_raw_buf`, `kernel_stub_module_round_trips`, `raw_buf_module_round_trips`, `ailang-kernel-stub` (legacy), `ailang-kernel` (new). All consistent.

4. **Step granularity.** Task 1 has 13 steps; each is one file edit or one command. Task 2: 5 steps. Task 3: 7 steps. Tasks 4-7: 3-4 steps each. All steps 2-5 min. Task 1 is the largest, but it must be atomic (the crate rename can't be half-done).

5. **No commit steps.** None.

6. **Pin/replacement substring contiguity.** Three substrings are asserted by tests against expected file content / stderr:
   - `param-not-in-restricted-set` — asserted by Task 6's test against `ail check` stderr. Not generated by any file content this plan ships; sourced from the existing checker diagnostic. No contiguity risk within plan-shipped text.
   - `Term::New requires the type's` — asserted by Task 7's test against `ail build` stderr. Sourced from the existing codegen deferral at `crates/ailang-codegen/src/lib.rs:2075-2078`. No contiguity risk.
   - The `workspace_pin.rs` `assert_eq!(ws.modules.len(), 5);` substring — the bumped value. The replacement-body text in Task 3 Step 4 contains this assertion verbatim and contiguously (no soft-wrap split).

7. **Compile-gate vs. deferred-caller ordering.**
   - Task 1 changes the dep name `ailang-kernel-stub` → `ailang-kernel`. The compile-driven set is 8 sites across 6 files; ALL are threaded inside Task 1. No deferred caller. Task 1 ends with `cargo build --workspace` + `cargo test --workspace` green.
   - Task 3 changes the workspace count (injection adds raw_buf — `workspace_pin` count assertion goes from 4 to 5). The bump is bundled into Task 3 Step 4 — no deferred fix across the compile gate.
   - Task 5 / 6 / 7 introduce new tests; no signature changes elsewhere.

8. **Verification-command filter strings must resolve.** Every `cargo test … <filter>` invocation uses a fn name THIS PLAN ships (Tasks 4-7) or an existing fn confirmed by recon (`loads_example_workspace_happy_path` in Task 3 Step 6). Zero filter-zero-match risk: the new tests are written in the same task that runs them, and the `loads_example_workspace_happy_path` test exists at `crates/ailang-core/tests/workspace_pin.rs:46` per recon. Unfiltered `cargo test --workspace` at the end of each task uses a counter-based assertion (the awk pipeline), so "zero tests ran" cannot masquerade as success.
