From d1241b12c759765f12713584ce2aab21e2a74f74 Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 18 May 2026 17:47:35 +0200 Subject: [PATCH] =?UTF-8?q?plan:=20embedding-abi-m2.tidy=20=E2=80=94=20DES?= =?UTF-8?q?IGN.md=20'(M1)'->'Embedding=20ABI'=20lockstep=20rename=20(5=20l?= =?UTF-8?q?ive=20sites:=20header+:2354=20xref+pin=20comment/msg+form=5Fa.m?= =?UTF-8?q?d:89;=20pinned=20:135=20substring=20rename-immune,=20untouched)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/embedding-abi-m2.tidy.md | 230 ++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 docs/plans/embedding-abi-m2.tidy.md diff --git a/docs/plans/embedding-abi-m2.tidy.md b/docs/plans/embedding-abi-m2.tidy.md new file mode 100644 index 0000000..3e9c325 --- /dev/null +++ b/docs/plans/embedding-abi-m2.tidy.md @@ -0,0 +1,230 @@ +# 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": "", // omitted when absent (hash-stable when omitted); see §"Embedding ABI (M1)" +``` + +Replace the trailing `see §"Embedding ABI (M1)"` so the line reads: + +``` + "export": "", // 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. ✓