AILang/docs/plans/embedding-abi-m2.tidy.md

# Embedding ABI — M2.tidy — Implementation Plan

> **Parent spec:** none — audit-driven docs-honesty tidy. Source:
> `docs/journals/2026-05-18-audit-embedding-abi-m2.md` (committed
> `ad88dec`), the M2 milestone-close audit's one actionable drift
> item (`[medium]` DESIGN.md:2266 stale `(M1)` header + coupled
> `[low]` :2354 xref), plus a Boss-added 5th live-coupling site the
> recon surfaced (`form_a.md:89`).
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Rename the DESIGN.md section `## Embedding ABI (M1)` →
`## Embedding ABI` (current-state-mirror — its body now describes the
post-M2 ctx ABI present-tense) and move every *live* coupled
reference in lockstep, completely, so no pointer dangles at a vanished
section title.

**Architecture:** Pure docs/test-string tidy. Five live-coupling edit
sites across three files (DESIGN.md header + DESIGN.md schema-block
xref comment + `docs_honesty_pin.rs` test comment + that test's
assert-message + `form_a.md` forward-xref). Zero language / checker /
codegen / schema change. The `docs_honesty_pin.rs:135` *asserted
substring* (the DESIGN.md body sentence "Export parameters are written
**bare**…", `DESIGN.md:2297–2299`) is rename-immune and stays
byte-verbatim untouched — recon proved it lives 31 lines below the
header, is section-name-free, and is matched file-wide via
`d.contains`, so a header rename cannot affect it.

**Tech Stack:** `docs/DESIGN.md`, `crates/ailang-core/tests/docs_honesty_pin.rs`,
`crates/ailang-core/specs/form_a.md` (the latter is compiled in via
`ailang_core::FORM_A_SPEC` `include_str!`). Verification:
`cargo test -p ailang-core`.

---

## Files this plan modifies

- Modify: `docs/DESIGN.md:2266` — section header `## Embedding ABI (M1)` → `## Embedding ABI`.
- Modify: `docs/DESIGN.md:2354` — schema-block xref comment `see §"Embedding ABI (M1)"` → `see §"Embedding ABI"` (inside the `## Data model` window `:2319–2558`, but NOT a `design_schema_drift.rs` anchor — its anchors are JSON-schema discriminator tokens, not free prose, so the drift test does not fire on this edit; recon-verified).
- Modify: `crates/ailang-core/tests/docs_honesty_pin.rs:134` — test comment `// --- PRESENT: the DESIGN.md §"Embedding ABI (M1)" mirror ---` → drop `(M1)`.
- Modify: `crates/ailang-core/tests/docs_honesty_pin.rs:136` — assert-message `"DESIGN.md §Embedding ABI (M1) must mirror …"` → drop `(M1)`.
- Modify: `crates/ailang-core/specs/form_a.md:89` — live forward-xref `DESIGN.md §"Embedding ABI (M1)".` → `DESIGN.md §"Embedding ABI".` (Boss-added 5th site: a live pointer into the renamed section in a compiled-in spec — same dangling-xref class as DESIGN.md:2354; recon-confirmed NOT a `docs_honesty_pin.rs` asserted substring, so the edit moves no test).
- DO NOT MODIFY: `crates/ailang-core/tests/docs_honesty_pin.rs:135` (the asserted substring — rename-immune, stays byte-verbatim) and every `Embedding ABI (M1)` occurrence in `docs/journals/**`, `docs/specs/**`, `docs/plans/**`, `bench/orchestrator-stats/**` (committed append-only history — correctly names the section as it was at the time; renaming history is a falsification, not a tidy).

---

## Task 1: Lockstep section rename `Embedding ABI (M1)` → `Embedding ABI`

**Files:**
- Modify: `docs/DESIGN.md:2266`, `docs/DESIGN.md:2354`
- Modify: `crates/ailang-core/tests/docs_honesty_pin.rs:134`, `:136`
- Modify: `crates/ailang-core/specs/form_a.md:89`

- [ ] **Step 1: Capture the baseline (live occurrences + pins green)**

Run: `grep -rn 'Embedding ABI (M1' docs/DESIGN.md crates/ailang-core/tests/docs_honesty_pin.rs crates/ailang-core/specs/form_a.md`
Expected: exactly 5 lines —
`docs/DESIGN.md:2266` (`## Embedding ABI (M1)`),
`docs/DESIGN.md:2354` (`… see §"Embedding ABI (M1)"`),
`crates/ailang-core/tests/docs_honesty_pin.rs:134` (comment),
`crates/ailang-core/tests/docs_honesty_pin.rs:136` (assert message),
`crates/ailang-core/specs/form_a.md:89` (`DESIGN.md §"Embedding ABI (M1)".`).
(Line 135 — the asserted substring — does NOT match this grep; it
contains no `(M1)` token. Confirm it is absent from the grep output.)

Run: `cargo test -p ailang-core --test docs_honesty_pin`
Expected: PASS — `test result: ok. 5 passed; 0 failed`.

Run: `cargo test -p ailang-core --test design_schema_drift`
Expected: PASS — `test result: ok. 8 passed; 0 failed`.

- [ ] **Step 2: Rename the DESIGN.md section header**

In `docs/DESIGN.md`, replace the header line (`:2266`):

```
## Embedding ABI (M1)
```

with:

```
## Embedding ABI
```

- [ ] **Step 3: Lockstep the DESIGN.md schema-block xref comment**

In `docs/DESIGN.md`, the schema-block line (`:2354`) currently reads:

```
  "export": "<optional C symbol>", // omitted when absent (hash-stable when omitted); see §"Embedding ABI (M1)"
```

Replace the trailing `see §"Embedding ABI (M1)"` so the line reads:

```
  "export": "<optional C symbol>", // omitted when absent (hash-stable when omitted); see §"Embedding ABI"
```

(This line is inside the `## Data model` window `:2319–2558` but the
`(M1)`→`` edit changes no `design_schema_drift.rs` anchor token —
verified Step 6.)

- [ ] **Step 4: Lockstep the docs_honesty_pin test comment + assert message**

In `crates/ailang-core/tests/docs_honesty_pin.rs`, line `:134`
currently reads:

```rust
    // --- PRESENT: the DESIGN.md §\"Embedding ABI (M1)\" mirror ---
```

Replace with:

```rust
    // --- PRESENT: the DESIGN.md §\"Embedding ABI\" mirror ---
```

And line `:136` (the assert message) currently reads:

```rust
        "DESIGN.md §Embedding ABI (M1) must mirror the canonical bare-scalar export-param rule");
```

Replace with:

```rust
        "DESIGN.md §Embedding ABI must mirror the canonical bare-scalar export-param rule");
```

**Do NOT touch line `:135`** (the `assert!(d.contains("Export
parameters are written **bare**: a scalar type carries no
\`own\`/\`borrow\` mode"),` line) — the asserted substring is the
DESIGN.md body sentence, rename-immune, must stay byte-verbatim.

- [ ] **Step 5: Lockstep the form_a.md forward-xref**

In `crates/ailang-core/specs/form_a.md`, line `:89` currently
contains the forward-xref token:

```
DESIGN.md §"Embedding ABI (M1)".
```

Replace that token (in place, leaving the rest of the line/sentence
exactly as is) so it reads:

```
DESIGN.md §"Embedding ABI".
```

(`form_a.md` is compiled into `ailang_core::FORM_A_SPEC` via
`include_str!`; recon verified this line is NOT a `docs_honesty_pin.rs`
asserted substring — the form_a carve-out pins assert the bare-scalar
sentences at `:125–132`, not this xref — so the edit moves no test.)

- [ ] **Step 6: Verify — zero live occurrences, pins green**

Run: `grep -rn 'Embedding ABI (M1' docs/DESIGN.md crates/ailang-core/tests/docs_honesty_pin.rs crates/ailang-core/specs/form_a.md`
Expected: **no output** (exit 1) — all 5 live-coupling sites renamed;
no dangling pointer at the vanished `(M1)` title.

Run: `cargo test -p ailang-core --test docs_honesty_pin`
Expected: PASS — `test result: ok. 5 passed; 0 failed`. (The asserted
`:135` substring is unchanged; the comment/message edits are not
asserted; the pin is green ⇒ the rename did not perturb it.)

Run: `cargo test -p ailang-core --test design_schema_drift`
Expected: PASS — `test result: ok. 8 passed; 0 failed`. (The `:2354`
edit changed no JSON-schema anchor token; `data_model_section_is_bounded`
unaffected — the section boundary `## Data model`/`## Pipeline` is
untouched.)

- [ ] **Step 7: Verify — committed history NOT falsified**

Run: `git diff --name-only`
Expected: exactly three files —
`docs/DESIGN.md`, `crates/ailang-core/tests/docs_honesty_pin.rs`,
`crates/ailang-core/specs/form_a.md`. **No** `docs/journals/**`,
`docs/specs/**`, `docs/plans/**`, or `bench/orchestrator-stats/**`
file in the diff (those retain `Embedding ABI (M1)` as correct
append-only history of the section's name at the time — renaming
them would falsify the record).

Run: `git diff --stat`
Expected: ~5 insertions / ~5 deletions total (one line changed per
site; the header, the xref comment, the test comment, the test
message, the form_a xref). No multi-line churn.

---

## Self-review (Step 5 — completed inline)

1. **Spec coverage:** no spec — audit-item-driven. The audit's named
   `[medium]`(header)+`[low]`(:2354 xref) plus the Boss-added 5th
   site (form_a.md:89, same dangling-xref class, recon-surfaced) and
   the two test-string lockstep sites (docs_honesty_pin :134/:136)
   are each a Step in Task 1. ✓
2. **Placeholder scan:** no "TBD/TODO/implement later/similar
   to/add appropriate". ✓
3. **Type/name consistency:** the target title `## Embedding ABI`
   and xref form `§"Embedding ABI"` / `§Embedding ABI` are used
   identically across Steps 2–6 and the file-map. ✓
4. **Step granularity:** each step is one grep / one cargo run / one
   one-line edit — 2–5 min. ✓
5. **No commit steps:** none (Boss commits at iter end). ✓
6. **Pin/replacement substring contiguity:** the ONLY presence-pin
   paired with a verbatim doc edit is `docs_honesty_pin.rs:135` ↔
   `DESIGN.md:2297–2299`. Recon proved definitively the asserted
   substring (a) contains no `(M1)`/section-name token, (b) lives
   31 lines below the renamed header, (c) is matched file-wide via
   `d.contains` not section-scoped. Step 4 explicitly forbids
   touching `:135` and Step 2/3 edit only `:2266`/`:2354` (31+ lines
   away). The pinned substring is never inside any replacement body
   ⇒ no soft-wrap split possible. ✓
7. **Compile-gate vs deferred-caller:** no Rust signature change;
   `docs_honesty_pin.rs` edits are a comment + a string literal
   (no API, no caller cascade); `form_a.md` is `include_str!` data
   (no recompile-cascade beyond `ailang-core`'s own test build,
   which Step 6 gates). N/A — no such ordering hazard. ✓
8. **Verification filter strings resolve:** `--test docs_honesty_pin`
   and `--test design_schema_drift` are recon-verified existing test
   targets (5 and 8 tests respectively, exact counts named); the
   `grep -rn 'Embedding ABI (M1'` pattern is verified by recon to
   match exactly the 5 live sites at Step 1 and (post-edit) zero at
   Step 6 — a count that flips 5→0 cannot masquerade as "nothing
   ran" (Step 1 asserts the 5 are present first). `git diff
   --name-only` asserts the exact 3-file footprint so an accidental
   history edit cannot pass silently. ✓