plan: embedding-abi-m2.tidy — DESIGN.md '(M1)'->'Embedding ABI' lockstep rename (5 live sites: header+:2354 xref+pin comment/msg+form_a.md:89; pinned :135 substring rename-immune, untouched)
This commit is contained in:
@@ -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": "<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. ✓
|
||||
Reference in New Issue
Block a user