AILang/docs/plans/0086-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:

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

Replace with:

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

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

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

Replace with:

        "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. ✓