# raw-buf.2 — Kernel family-crate rename — 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 the crate `ailang-kernel-stub` → `ailang-kernel`
and reshape it into a family-crate (a re-export hub `src/lib.rs`
plus one submodule per kernel-tier module, here just
`src/kernel_stub/{mod.rs, source.ail}`), with ZERO behavioural
change and NO `raw_buf` submodule (that is raw-buf.3).

**Architecture:** A pure crate rename. Task 1 does the atomic,
build-breaking work: `git mv` the crate dir, carve the embedded
`STUB_AIL` Form-A text verbatim into `src/kernel_stub/source.ail`,
add the `mod.rs` + `lib.rs` hub, and thread every compile site
(Cargo package name, workspace member + dep-alias, `ailang-surface`
dep + `loader.rs` use-paths) — ending with `cargo build` +
`cargo test` green. Task 2 fixes the in-tree doc/ledger crate-path
references the honesty-rule requires (no build impact). The
public symbol `STUB_AIL` is preserved (re-exported from the new
submodule) so `ailang-surface` and the bijection test bind to it
unchanged.

**Tech Stack:** Rust (Cargo workspace), `crates/ailang-kernel/`
(renamed), `crates/ailang-surface/` (dep + parse hop), root
`Cargo.toml`, `design/INDEX.md`, `design/models/0007-kernel-extensions.md`,
`CLAUDE.md`.

---

**Files this plan creates or modifies:**

- Create: `crates/ailang-kernel/src/kernel_stub/source.ail` — the Form-A `kernel_stub` module text, carved verbatim from the current `STUB_AIL` raw string (incl. the `answer` `(intrinsic)` fn).
- Create: `crates/ailang-kernel/src/kernel_stub/mod.rs` — the `SOURCE` const via `include_str!("source.ail")`.
- Modify (rewrite): `crates/ailang-kernel/src/lib.rs` — becomes the family-crate hub (`mod kernel_stub; pub use kernel_stub::SOURCE as STUB_AIL;`); replaces the carved-out single-file crate body. (Path arrives via `git mv` from `crates/ailang-kernel-stub/src/lib.rs`.)
- Modify: `crates/ailang-kernel/Cargo.toml:2` — package `name` (arrives via `git mv`).
- Modify: `Cargo.toml:7` — workspace member entry.
- Modify: `Cargo.toml:37` — workspace dep-alias entry.
- Modify: `crates/ailang-surface/Cargo.toml:9` — dep entry.
- Modify: `crates/ailang-surface/src/loader.rs:48,55,56` — `ailang_kernel_stub` → `ailang_kernel` (rustdoc, call, expect-message) in `parse_kernel_stub`.
- Modify: `design/INDEX.md:112` — kernel-extensions Models row crate-path string.
- Modify: `CLAUDE.md:52` — Code-layout table row (path + role description).
- Modify: `CLAUDE.md:312` — lockstep-invariant-pairs row, markers-source path string.
- Modify: `design/models/0007-kernel-extensions.md:8,235` — crate-path strings (path-only; the retirement narrative stays for raw-buf.4).

---

### Task 1: Crate rename + family-crate reshape + all compile sites

This task is atomic: the crate rename breaks the build at 6 files
until every site is threaded, so all compile-breaking edits live
here and the task ends with a green workspace build + test. The
`STUB_AIL` carve must be byte-verbatim — a single perturbed byte
shifts the `kernel_stub`-derived codegen symbols in the `.ll`
snapshots and the `kernel_stub_module_round_trips` round-trip,
both of which then fail `cargo test` (the carve's ratification).

**Files:**
- Move: `crates/ailang-kernel-stub/` → `crates/ailang-kernel/`
- Create: `crates/ailang-kernel/src/kernel_stub/source.ail`
- Create: `crates/ailang-kernel/src/kernel_stub/mod.rs`
- Modify (rewrite): `crates/ailang-kernel/src/lib.rs`
- Modify: `crates/ailang-kernel/Cargo.toml:2`
- Modify: `Cargo.toml:7`, `Cargo.toml:37`
- Modify: `crates/ailang-surface/Cargo.toml:9`
- Modify: `crates/ailang-surface/src/loader.rs:48,55,56`

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

Run: `git mv crates/ailang-kernel-stub crates/ailang-kernel`
Expected: the folder rename succeeds; `git status` shows
`renamed: crates/ailang-kernel-stub/Cargo.toml -> crates/ailang-kernel/Cargo.toml`
and the same for `src/lib.rs`.

- [ ] **Step 2: Carve the `STUB_AIL` body verbatim into `source.ail`.**

The current `crates/ailang-kernel/src/lib.rs` (just moved) holds
the Form-A text as a raw string at lines 27-41 (line 27 carries
the `pub const STUB_AIL: &str = r#"` prefix; the string closes
with `"#;` on line 42). Carve the body — byte-preserving, do NOT
retype — with:

Run:
```
mkdir -p crates/ailang-kernel/src/kernel_stub
sed -n '27,41p' crates/ailang-kernel/src/lib.rs | sed '1s/^pub const STUB_AIL: &str = r#"//' > crates/ailang-kernel/src/kernel_stub/source.ail
wc -c crates/ailang-kernel/src/kernel_stub/source.ail
```
Expected: `500 crates/ailang-kernel/src/kernel_stub/source.ail`.
The file content is exactly (for verification — the carve, not a
retype, is authoritative; this block is fenced `text` because the
module name `kernel_stub` is a reserved built-in and cannot be
`ail check`-ed standalone — `reserved-module-name` — so the
parse-gate is N/A; ratification is the verbatim carve + the
`kernel_stub_module_round_trips` test + `cargo test`):

```text
(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)))
  (fn answer
    (doc "Ratifies the intrinsic mechanism end-to-end: codegen intercept answer emits ret i64 42.")
    (type (fn-type (params) (ret (con Int))))
    (params)
    (intrinsic)))
```

The file ends with a single trailing newline after `(intrinsic)))`.

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

Write exactly:

```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. Retired when the `raw-buf` milestone lands
//! its real kernel-tier consumer (raw-buf.4); 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)`
/// (Term::New end-to-end, per prep.3 fieldtest F4) and an `answer`
/// `(intrinsic)` fn whose `INTERCEPTS` entry the bijection test pins.
pub const SOURCE: &str = include_str!("source.ail");
```

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

Replace the entire file contents with exactly:

```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`, …) so this
//! crate carries zero parser code.

mod kernel_stub;

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

- [ ] **Step 5: Rename the Cargo package.**

Edit `crates/ailang-kernel/Cargo.toml`. Change line 2:

old: `name = "ailang-kernel-stub"`
new: `name = "ailang-kernel"`

Leave every other line unchanged (the `[dependencies]` section
stays empty).

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

Edit `Cargo.toml` line 7:

old: `    "crates/ailang-kernel-stub",`
new: `    "crates/ailang-kernel",`

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

Edit `Cargo.toml` line 37:

old: `ailang-kernel-stub = { path = "crates/ailang-kernel-stub" }`
new: `ailang-kernel = { path = "crates/ailang-kernel" }`

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

Edit `crates/ailang-surface/Cargo.toml` line 9:

old: `ailang-kernel-stub.workspace = true`
new: `ailang-kernel.workspace = true`

- [ ] **Step 9: Update `crates/ailang-surface/src/loader.rs` use-paths in `parse_kernel_stub`.**

Three edits in the `parse_kernel_stub` fn (the module name
`kernel_stub` and the fn name stay — only the crate identifier
`ailang_kernel_stub` → `ailang_kernel` changes):

(a) Line 48 (rustdoc):
old: `/// Source-of-truth: \`ailang_kernel_stub::STUB_AIL\`. The stub`
new: `/// Source-of-truth: \`ailang_kernel::STUB_AIL\`. The stub`

(b) Line 55 (call):
old: `    crate::parse(ailang_kernel_stub::STUB_AIL)`
new: `    crate::parse(ailang_kernel::STUB_AIL)`

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

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

Run: `cargo build --workspace 2>&1 | tail -8`
Expected: build succeeds; zero errors. `Cargo.lock` is
regenerated automatically (the `ailang-kernel-stub` entries become
`ailang-kernel`) — do not hand-edit it. No reference to
`ailang-kernel-stub` / `ailang_kernel_stub` remains in any
compiled crate (a dangling ref would be a hard compile error
here).

- [ ] **Step 11: Run the full workspace test suite — 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: 669  failed: 0  ignored: 2` — the post-intrinsic-bodies baseline (measured this session), unchanged (this iteration is a pure rename; no test is added or removed). In particular `kernel_stub_module_round_trips` (design_schema_drift), `intercepts_bijection_with_intrinsic_markers` (codegen), `workspace_pin`, and the `.ll` snapshot tests all stay green — they reach `STUB_AIL` through the preserved re-export and the verbatim-carved source, so the crate rename is invisible to them.

---

### Task 2: Doc/ledger crate-path honesty updates

No build or test impact — these are in-tree, present-tense
references to the old crate path that the rename makes stale. Per
the honesty-rule (`design/contracts/0007-honesty-rule.md`), a
rename that leaves half its present-state paths stale is an
incomplete rename. Path-only edits; the retirement narrative in
`design/INDEX.md` / `design/models/0007` stays untouched (that is
raw-buf.4 territory).

**Files:**
- Modify: `design/INDEX.md:112`
- Modify: `CLAUDE.md:52`, `CLAUDE.md:312`
- Modify: `design/models/0007-kernel-extensions.md:8,235`

- [ ] **Step 1: Update `design/INDEX.md:112` crate-path.**

Edit `design/INDEX.md` line 112. Change the single occurrence of
the crate path:

old substring: ``ratified end-to-end by the `ailang-kernel-stub` fixture``
new substring: ``ratified end-to-end by the `ailang-kernel/src/kernel_stub` fixture``

Leave the rest of the row (retirement language, milestone status)
unchanged.

- [ ] **Step 2: Rewrite the `CLAUDE.md:52` Code-layout row.**

Edit `CLAUDE.md` line 52. Replace the entire row:

old:
```
| `crates/ailang-kernel-stub/` | Zero-dependency leaf crate carrying only the Form-A source of the `kernel_stub` ratifying-fixture module (`pub const STUB_AIL: &str`). The parse hop (`parse_kernel_stub`) lives in `ailang-surface` to keep the crate-dependency graph acyclic. Injected into every workspace load alongside `prelude`; may be retired when the `raw-buf` milestone lands a real second kernel-tier consumer. |
```

new:
```
| `crates/ailang-kernel/` | Family-crate hosting the Form-A source of every kernel-tier `.ail` module, one Rust submodule per module under `src/` (today: `kernel_stub`), each exposing a `pub const SOURCE` re-exported from `src/lib.rs` (`STUB_AIL`). Zero-dependency leaf; parse hops (`parse_kernel_stub`) live in `ailang-surface` to keep the graph acyclic (`ailang-surface → ailang-kernel → ailang-core`). The `kernel_stub` submodule is injected alongside `prelude` and is retired in raw-buf.4 once `raw_buf` becomes the real kernel-tier consumer. |
```

- [ ] **Step 3: Update the `CLAUDE.md:312` lockstep-pair markers-source path.**

Edit `CLAUDE.md` line 312 (the `INTERCEPTS` ↔ `(intrinsic)`
markers row). Change only the kernel-stub markers-source path:

old substring: `crates/ailang-kernel-stub/src/lib.rs::STUB_AIL`
new substring: `crates/ailang-kernel/src/kernel_stub/source.ail`

Leave the rest of the row (the `examples/prelude.ail` reference,
the bijection mechanics, the allowlist language) unchanged.

- [ ] **Step 4: Update `design/models/0007-kernel-extensions.md:8` crate-path.**

Edit line 8. Change:

old substring: ``ratified by the stub kernel crate\n(`crates/ailang-kernel-stub/`)``
new substring: ``ratified by the stub kernel module\n(`crates/ailang-kernel/src/kernel_stub/`)``

(The path string `crates/ailang-kernel-stub/` → `crates/ailang-kernel/src/kernel_stub/`; "crate" → "module" because the stub is now a submodule, not its own crate. This is the only edit on this line; the surrounding milestone-status prose stays.)

- [ ] **Step 5: Update `design/models/0007-kernel-extensions.md:235` crate-path.**

Edit line 235. Change:

old substring: ``The ratifying stub kernel module\n(`crates/ailang-kernel-stub/`)``
new substring: ``The ratifying stub kernel module\n(`crates/ailang-kernel/src/kernel_stub/`)``

(Path-only; the line already says "module".)

- [ ] **Step 6: Confirm no stale crate-path references remain in-tree.**

Run: `git grep -nE 'ailang-kernel-stub|ailang_kernel_stub' -- ':!docs/plans' ':!docs/specs' ':!Cargo.lock'`
Expected: no output (exit 1). All present-tense, in-tree
references are updated; history under `docs/plans/` and
`docs/specs/` (completed plans/specs) and the auto-regenerated
`Cargo.lock` are deliberately excluded — historical artefacts are
not retro-edited per the honesty-rule.

- [ ] **Step 7: Final build + test sanity.**

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` (doc edits do not
touch compiled code or tests; this confirms Task 2 introduced no
accidental source change).

---

## Self-review

1. **Spec coverage.**
   - § Architecture point 2 ("Rename … reshape it as a
     family-crate", "carries `src/kernel_stub/{mod.rs,
     source.ail}`", "`src/lib.rs` re-exports … `STUB_AIL`",
     "parse hop `parse_kernel_stub` stays in `ailang-surface`",
     "No `raw_buf` submodule yet"): Task 1 Steps 1-9.
   - § Components "Kernel family-crate rename" row (git mv,
     reshape, Cargo package + member + dep-alias, ailang-surface
     dep + loader.rs, design/INDEX.md, CLAUDE.md): Task 1 (code)
     + Task 2 (docs).
   - § Testing-strategy raw-buf.2 bullet ("All existing tests
     pass unchanged … zero test-count change … cargo build +
     cargo test"): Task 1 Steps 10-11.

2. **Placeholder scan.** No "TBD", "TODO", "implement later",
   "similar to Task", "add appropriate error handling". None
   present.

3. **Type consistency.** Symbols across tasks: `STUB_AIL` (the
   preserved re-exported const), `SOURCE` (submodule const),
   `kernel_stub` (module name + submodule name, unchanged),
   `parse_kernel_stub` (fn name, unchanged), `ailang_kernel`
   (new crate identifier), `ailang-kernel` (new package name).
   All consistent. The module name `kernel_stub` (string) is
   deliberately NOT renamed — only the crate is.

4. **Step granularity.** Each step is one file edit, one carve,
   or one command. Task 1 is the largest (11 steps) but must be
   atomic — the crate rename cannot be half-landed (the build
   breaks until all 6 compile sites are threaded).

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

6. **Pin/replacement substring contiguity.** The only presence
   assertions are: `git grep` for absence of the old crate name
   (Task 2 Step 6 — asserts NO match, satisfied by the edits in
   Tasks 1+2) and the `wc -c` 500-byte pin on the carved
   `source.ail` (Task 1 Step 2). The 500-byte pin is satisfied by
   the byte-preserving `sed` carve, not by a retyped body (the
   `text` reference block is for human verification only, not the
   carve source). No substring is split across a soft-wrap in any
   verbatim replacement body.

7. **Compile-gate vs. deferred-caller ordering.** The crate
   rename's full compile-breaking site set (Cargo package name,
   workspace member, workspace dep-alias, `ailang-surface` dep,
   `loader.rs` use-path) is enumerated by recon as 8 sites across
   6 files; ALL are threaded inside Task 1 before its
   `cargo build --workspace` gate (Step 10). No caller is
   deferred past the gate. `Cargo.lock` is the only other
   build-affected file and is auto-regenerated, not hand-threaded.

8. **Verification-command filter strings.** Task 1 Step 11 and
   Task 2 Step 7 use the unfiltered `cargo test --workspace` with
   an explicit pass/fail/ignored count assertion (the awk
   pipeline), so "0 tests ran" cannot masquerade as success. The
   `git grep` in Task 2 Step 6 asserts absence (empty output);
   its pattern matched the real sites at recon time, so a
   regression that reintroduced the old name would re-trigger a
   match. No bare feature-word test filter is used.

9. **Parse-the-bytes gate.** The one surface-language body the
   plan inlines (`source.ail`, Task 1 Step 2) is the `kernel_stub`
   kernel module, whose name is a reserved built-in — `ail check`
   on it standalone returns `reserved-module-name` (verified this
   session), so the configured `ail` parser cannot validate it in
   isolation; the block is fenced `text` (gate-skipped, reason
   noted in-step). Its ratification is the byte-verbatim carve
   from the live, already-building tree plus the
   `kernel_stub_module_round_trips` round-trip and the `.ll`
   snapshot tests under `cargo test` (Task 1 Step 11). All other
   inlined bodies are Rust (`mod.rs`, `lib.rs`) — caught by the
   `implement` compile gate, not the parse gate.