AILang/docs/plans/0108-raw-buf.2-kernel-rename.md

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):

(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:

//! 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:

//! 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 stubnew:/// 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.