AILang/docs/plans/0088-embedding-abi-m3.tidy.md

Embedding ABI — M3.tidy — Implementation Plan

Parent spec: docs/specs/0043-embedding-abi-m3.md (the milestone whose §"Embedding ABI" surface this reconciles); scoping source-of-truth: docs/journals/2026-05-18-audit-embedding-abi-m3.md.

For agentic workers: REQUIRED SUB-SKILL: use skills/implement to run this plan. Steps use - [ ] checkboxes for tracking.

Goal: Reconcile the two M3-audit doc-honesty DRIFT items — a self-contradicting M1-era parenthetical in DESIGN.md §"Embedding ABI" and a stale forwarder-body comment — to present-tense current state, pin-safe, with zero language/checker/codegen behaviour change.

Architecture: Two independent, surgical text edits. (1) docs/DESIGN.md:2300-2301 — replace only the parenthetical (modes apply only to heap-shaped types, which the scalar-only rule above forbids at an export boundary anyway), which now contradicts the M3 frozen-layout SSOT (a single-ctor record IS an accepted export type) and the (own/borrow (con T)) mode contract; the docs_honesty_pin.rs:135-pinned sentence words on :2299-2300 (norm()-whitespace-collapsed) are kept verbatim-present. (2) crates/ailang-codegen/src/lib.rs:608-610 — a comment-only honesty fix (no test pins it; the IR byte-pins assert generated code, not source comments). The four standing pins bracket both edits green.

Tech Stack: docs/DESIGN.md, crates/ailang-codegen/src/lib.rs (comment only); regression gates in ailang-core (docs_honesty_pin, design_schema_drift) and ailang-codegen (embed_record_layout_pin, embed_staticlib_lowering).

---

Files this plan creates or modifies

• Modify: docs/DESIGN.md:2300-2301 — replace the contradicted M1-era parenthetical only (pinned sentence words on :2299-2300 untouched; :2302 kept)
• Modify: crates/ailang-codegen/src/lib.rs:608-610 — forwarder-body comment honesty (comment-only, no IR change)
• Test (gate, unmodified): crates/ailang-core/tests/docs_honesty_pin.rs — form_a_scalar_param_carveout_present_and_old_rule_absent stays GREEN (pinned sentence words survive)
• Test (gate, unmodified): crates/ailang-core/tests/design_schema_drift.rs — stays GREEN (no schema-drift anchor moves)
• Test (gate, unmodified): crates/ailang-codegen/tests/embed_record_layout_pin.rs + embed_staticlib_lowering.rs — stay GREEN (comment edit changes no IR)

---

Task 1: Reconcile the contradicted DESIGN.md parenthetical ([medium])

The stale clause is strictly the parenthetical spanning the back of :2300 and the front of :2301. The pinned sentence ("Export parameters are written bare: a scalar type carries no own/borrow mode", docs_honesty_pin.rs:135, norm()-collapsed) occupies :2299 + the front of :2300 and MUST keep all its words (planner Step-5 item-6: presence-pin vs. verbatim-edit collision — the M2.tidy discipline). The edit replaces only the parenthetical's words; it does not touch :2299, the pinned-sentence words on :2300, the . The connective, or :2302.

Files:

• Modify: docs/DESIGN.md:2300-2301

• Test: crates/ailang-core/tests/docs_honesty_pin.rs (gate, unmodified)

• Step 1: Baseline — the pin is GREEN before the edit

Run: cargo test -p ailang-core --test docs_honesty_pin form_a_scalar_param_carveout_present_and_old_rule_absent -- --exact Expected: PASS, 1 passed (the pinned "written bare" sentence present; baseline before the edit).

Run: grep -n 'modes apply only to heap-shaped types' docs/DESIGN.md Expected: one hit on line 2300 (confirms the stale clause is present and located exactly where recon mapped it; if the line number differs, re-locate before editing — the edit is by verbatim string, not line number, so a shift is non-fatal but must be noted).

• Step 2: Replace only the parenthetical (verbatim edit)

In docs/DESIGN.md, the current text of lines :2300-2301 is exactly (two lines, soft-wrapped):

`own`/`borrow` mode (modes apply only to heap-shaped types, which the
scalar-only rule above forbids at an export boundary anyway). The

Replace that exact two-line block with:

`own`/`borrow` mode (a single-constructor record export parameter,
by contrast, carries `own`/`borrow` — the ownership contract the
frozen value layout below specifies). The

This (a) keeps the pinned-sentence words own/borrow modecontiguous with:2299's Export parameters are written bare: a scalar type carries no(thenorm()pin only needs the *words* present, in any wrapping — verified:docs_honesty_pin.rs:21-26); (b) removes exactly the false clause (post-M3 the export boundary *accepts* a single-ctor record — a heap-shaped type — so "the scalar-only rule above forbids" is no longer true and contradicted :2280-2284+ the mode contract at:2345-2351); (c) replaces it with the present-tense truth that points at the new SSOT; (d) preserves the . Theconnective and:2302 canonical M1 export shape:untouched (audit did not flag:2302`; scope discipline — fix only the flagged contradiction).

• Step 3: The stale clause is gone, the pin still GREEN

Run: grep -n 'scalar-only rule above forbids' docs/DESIGN.md Expected: no output (the contradicted clause is removed).

Run: cargo test -p ailang-core --test docs_honesty_pin Expected: PASS, 5 passed — in particular form_a_scalar_param_carveout_present_and_old_rule_absent stays GREEN (the pinned sentence's words survived the edit). If RED: STOP, restore the file (git checkout -- docs/DESIGN.md), and re-scope the edit to leave every pinned-sentence word in place — do not push past a RED pin (planner Step-5 item-6).

• Step 4: No schema-drift anchor moved

Run: cargo test -p ailang-core --test design_schema_drift Expected: PASS, 8 passed — the parenthetical is prose, not a JSON-schema-drift anchor; the count is byte-unchanged from the recon-confirmed baseline.

---

Task 2: Honesty-fix the stale forwarder-body comment ([low])

crates/ailang-codegen/src/lib.rs:608-610 is a comment-only block inside the Target::StaticLib arm asserting the gate guarantees Int/Float-only — false post-M3 (a gate-guaranteed single-ctor record lowers to ptr). Recon tree-wide-grep-confirmed no test pins this comment text; the byte-pin and forwarder-IR pin assert emitted IR, not source comments, so this edit changes no generated code. First code/IR line is :618 — :608-610 are comment-only.

Files:

• Modify: crates/ailang-codegen/src/lib.rs:608-610

• Test: crates/ailang-codegen/tests/embed_record_layout_pin.rs + embed_staticlib_lowering.rs (gate, unmodified)

• Step 1: Baseline — the IR pins are GREEN before the edit

Run: cargo test -p ailang-codegen --test embed_record_layout_pin --test embed_staticlib_lowering Expected: PASS, 1 passed + 3 passed (the byte-pin heap_box_layout_is_frozen_8_plus_n_times_8_tag_at_0_fields_from_8 and the forwarder-IR pins staticlib_emits_forwarder_no_main / staticlib_record_forwarder_is_ptr_passthrough / executable_target_still_emits_main — the guard that generated code is untouched by a comment edit).

• Step 2: Replace the stale comment (verbatim edit)

In crates/ailang-codegen/src/lib.rs, the current text of lines :608-610 is exactly:

            // The check-side gate (Task 4) guarantees every param
            // and the ret are `Int`/`Float`; map Int→i64,
            // Float→double. M1 scalar fns have no captured env, so

Replace that exact three-line block with:

            // The check-side export gate guarantees every param and
            // the ret are `Int`/`Float` or a single-constructor
            // record of those (M3); map Int→i64, Float→double, a
            // record → ptr. Scalar fns have no captured env, so

(Honesty-only: the gate now accepts a single-ctor scalar record → ptr; the trailing "…have no captured env, so" continuation on :610's tail is preserved as a clause start for the unchanged following line. Removed the stale M1 qualifier on the env clause in passing — it is the same sentence the gate-rule fix rewrites, so it is in-scope contiguous text, not scope creep.)

• Step 3: Generated code is byte-unchanged (IR pins GREEN)

Run: cargo test -p ailang-codegen --test embed_record_layout_pin --test embed_staticlib_lowering Expected: PASS, 1 passed + 3 passed — identical to Step 1; a comment edit emits no IR delta. If any IR pin goes RED the edit touched code, not just a comment — STOP and restore (git checkout -- crates/ailang-codegen/src/lib.rs).

• Step 4: The crate still builds + full codegen suite GREEN

Run: cargo test -p ailang-codegen 2>&1 | tail -1 Expected: the final line shows test result: ok with 0 failed (comment-only change; the whole codegen crate is unaffected).

---

Task 3: Milestone-close verification gate

Not a code change — the consolidated proof that the tidy removed the drift and moved nothing else.

Files: none (verification only).

• Step 1: Both stale phrases are gone tree-wide

Run: grep -rn 'scalar-only rule above forbids' docs/DESIGN.md ; grep -n 'guarantees every param' crates/ailang-codegen/src/lib.rs Expected: no output from either grep (both audit-flagged stale fragments removed).

• Step 2: The four standing pins + workspace GREEN

Run: cargo test -p ailang-core --test docs_honesty_pin --test design_schema_drift -p ailang-codegen --test embed_record_layout_pin --test embed_staticlib_lowering Expected: PASS — docs_honesty_pin 5, design_schema_drift 8, embed_record_layout_pin 1, embed_staticlib_lowering 3 (every count identical to the recon-confirmed baseline; the tidy moved no pin).

Run: cargo test --workspace 2>&1 | grep -oE '[0-9]+ passed' | awk '{s+=$1} END{print s" passed across "NR" suites"}' Expected: 639 passed across 77 suites (the M3-DONE baseline, byte-unchanged — a docs/comment tidy adds no tests and regresses none; if the number differs from 639 the tidy had an unintended behaviour effect — STOP and investigate).

• Step 3: The diff is exactly two files, no behaviour change

Run: git diff --stat Expected: exactly docs/DESIGN.md (a few lines) and crates/ailang-codegen/src/lib.rs (3 comment lines) changed — no .ail, no fixture, no test, no schema, no other source. (The journal + INDEX line are Boss-added at commit, not implement-tree.)

---

Notes for the implement orchestrator

• No audit/fieldtest gate after this tidy. The four pins ARE the regression coverage (the M2.tidy precedent: a docs/test-string tidy's guard is the docs_honesty_pin + the IR pins, Boss-verified before and after — no fresh architect/bench). Record in the per-iter journal that this closes the M3 audit's [medium]+[low] drift and that bench was already carry-on (causally exonerated at the audit, NO ratify).
• Pin-safety is the whole point of Task 1. The pinned sentence shares a physical line with the stale clause; the only safe edit is replace the parenthetical, keep every pinned word. A free-rewrite of the :2299-2302 line range is a plan violation — Step 3's RED→STOP→restore is mandatory, not advisory.
• Boss-only-commits / main-sacrosanct. Leave both edits + the per-iter journal + stats uncommitted in the working tree; the Boss inspects git diff, commits the tidy, flips roadmap M3 [~]→[x], and adds the INDEX.md line.