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

embedding-abi-m5.tidy — milestone-close doc-honesty drift — Implementation Plan

Parent spec: docs/journals/2026-05-19-audit-embedding-abi-m5.md (the M5 milestone-close audit; this tidy resolves its DRIFT items).

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

Goal: Reconcile the three doc-honesty drift items the M5 milestone-close audit found — DOC/COMMENT-ONLY, pin-safe, zero language/checker/codegen/schema/runtime-behaviour change.

Architecture: Two docs/DESIGN.md prose edits (drop the retired-M4 forward-reference; reconcile the "no shared mutable runtime state" claim with the now-atomic global RC-stats fallback) and one runtime/rc.c comment-only honesty fix (the stale "two unconditional ++" performance aside). All three sites are recon- verified OUTSIDE every pinned/hashed region; the existing pin tests staying green before AND after is the mechanical proof the edits move no pinned byte. Mirrors the M2.tidy a80d495 / M3.tidy 63d7d60 precedent: pin-safe doc/comment-only, single cohesive commit, pins are the coverage (no RED test, no audit/fieldtest gate).

Tech Stack: Markdown (docs/DESIGN.md), C comments (runtime/rc.c). Verification: cargo test -p ailang-core (design_schema_drift, docs_honesty_pin, effect_doc_honesty_pin)

• cargo test -p ailang-codegen --test embed_record_layout_pin.

---

Files this plan creates or modifies:

• Modify: docs/DESIGN.md:2287-2298 — §"Embedding ABI": reconcile the "no shared mutable runtime state … data-race-free, sanitiser-verified" parenthetical with the now-atomic global RC-stats fallback (edit-2)
• Modify: docs/DESIGN.md:2354-2360 — §"Free (host side)": drop the retired-M4 forward-reference (edit-1)
• Modify: runtime/rc.c:88 — the 18g.0-block "two unconditional ++" performance aside, comment-text only (edit-3)

Recon-verified pin verdicts (do not re-derive):

• DESIGN.md:2354-2360 — OUTSIDE: ends at line 2360, before the ## Data model boundary (line 2362) that is the only region crates/ailang-core/tests/design_schema_drift.rs:28-37 scans; no honesty-pin substring matches it.
• DESIGN.md:2287-2298 — OUTSIDE: far above the line-2362 data-model boundary; the one §"Embedding ABI" honesty-pin (docs_honesty_pin.rs:135) pins the line-2299 bare-scalar sentence — adjacent but distinct; this edit must not disturb line 2299.
• runtime/rc.c:88 — pin-inert: the frozen-IR pin (crates/ailang-codegen/tests/embed_record_layout_pin.rs) asserts generated LLVM IR, never rc.c comment text (M3.tidy 63d7d60 precedent: comment-only rc-runtime edit, IR pins byte-identical before/after).

---

Task 1: docs/DESIGN.md doc-honesty (edit-1 + edit-2)

Both edits are in the same file on the same doc-honesty axis and change together → one task.

Files:

• Modify: docs/DESIGN.md:2287-2298 (edit-2)

• Modify: docs/DESIGN.md:2354-2360 (edit-1)

• Step 1: Read the two edit regions to get exact wrapped bytes

Run: sed -n '2287,2300p;2354,2361p' docs/DESIGN.md Expected: the §"Embedding ABI" M2-ctx paragraph (incl. the no shared mutable runtime state — the swarm artefact is data-race-free, sanitiser-verified parenthetical, and the following line 2299 beginning Export parameters are written **bare**:) and the §"Free (host side)" paragraph ending … an additive M4 concern, not a contradiction of this freeze. This is the exact hard-wrapped text the Edit old_string must match.

• Step 2: Apply edit-1 — drop the retired-M4 forward-reference

In docs/DESIGN.md §"Free (host side)" (~:2354-2360), replace the exact sentence (it is hard-wrapped across ~2 lines in the file; match the file's wrapping):

OLD (semantic content to locate; match the file's exact wrap):

A record with boxed fields (Str/List/nested record) is not an M3 type (rejected by the export gate); a recursive typed-free for that shape is an additive M4 concern, not a contradiction of this freeze.

NEW (M4 is retired 2026-05-18 — present-tense current fact, no dead forward-reference; re-wrap to DESIGN.md's ~70-col hard-wrap):

A record with boxed fields (Str/List/nested record) is not an M3 embedding type — the export gate rejects it, so the boundary never crosses a value that would need a recursive typed-free. The freeze covers exactly the all-scalar single-constructor record.

• Step 3: Apply edit-2 — reconcile the concurrency claim

In docs/DESIGN.md §"Embedding ABI" (~:2287-2298), replace the exact sentence (hard-wrapped in the file; match its wrap). The edit is confined to this sentence and must NOT touch line 2299 (Export parameters are written **bare**: …, separately pinned by docs_honesty_pin.rs:135):

OLD (semantic content to locate; match the file's exact wrap):

The host links one ailang_ctx_t per OS worker thread and the runtime accounts RC alloc/free into it (no shared mutable runtime state — the swarm artefact is data-race-free, sanitiser-verified).

NEW (accurate present-tense; the per-ctx hot path is unshared, the one shared datum is the atomic global stats fallback — re-wrap to ~70-col):

The host links one ailang_ctx_t per OS worker thread and the runtime accounts RC alloc/free into it: the per-allocation hot path (the per-ctx counters and the per-object refcount header) is non-atomic by design and never shared — a box never crosses a thread (Ctx: !Send) and each ailang_ctx_t is single-thread-per-ctx. The one datum a multi-threaded host shares is the global RC-stats fallback counter (used when no ctx is bound); it is atomic-relaxed so the swarm's leak accounting is exact. The swarm artefact is data-race-free, sanitiser-verified.

• Step 4: Verify DESIGN.md pins still green (pin-safety proof)

Run: cargo test -p ailang-core --test design_schema_drift --test docs_honesty_pin --test effect_doc_honesty_pin 2>&1 | grep 'test result:' Expected: every line test result: ok. … 0 failed (≥3 result lines). GREEN here is the mechanical proof both DESIGN.md edits are outside every hashed/pinned byte (the data-model slice + the line-2299 bare-scalar honesty pin are untouched). A FAIL means a pinned byte moved — hard stop, the edit strayed into a pinned region.

• Step 5: Verify line 2299 (the adjacent pinned sentence) is byte-unchanged

Run: grep -n 'Export parameters are written \*\*bare\*\*' docs/DESIGN.md Expected: exactly one hit; its line content is byte-identical to its pre-edit form (the recon-pinned docs_honesty_pin.rs:135 substring). Confirms edit-2 stayed within the M2-ctx paragraph and did not disturb the adjacent separately-pinned line.

---

Task 2: runtime/rc.c:88 comment-only honesty fix

Separate file, comment-text only, same honesty axis → its own task.

Files:

• Modify: runtime/rc.c:88

• Step 1: Read the 18g.0 comment block for exact bytes

Run: sed -n '80,106p' runtime/rc.c Expected: the 18g.0 stats-counter comment block, incl. line 88 * and adds only two unconditional \++` operations to the hot path —` and the adjacent already-corrected "Atomic (relaxed): …" paragraph (~:93-106) the new wording must stay consistent with.

• Step 2: Apply edit-3 — fix the stale "two unconditional ++" aside

In runtime/rc.c replace the exact comment fragment (lines ~88):

OLD:

* and adds only two unconditional \++` operations to the hot path — * negligible relative to the libc malloc/free already on each path,`

NEW (accurate: one counter bump per op; relaxed-atomic on the global null-ctx fallback, plain ++ on the per-ctx path — consistent with the adjacent :93-106 block):

* and adds only one counter bump per alloc/free on the hot path — * a relaxed atomic add on the global null-ctx fallback, a plain * \++` on the per-ctx path — negligible relative to the libc * malloc/free already on each path,`

Comment-text only. Do NOT touch any code line, the adjacent :93-106 atomic paragraph, or the :45-55 file-header "Threading:" paragraph (both already correct from bugfix-rc-global-stats-race).

• Step 3: Verify rc.c change is comment-only + IR pin green

Run: git diff -U0 runtime/rc.c | grep -E '^[+-]' | grep -vE '^(\+\+\+|---)' | grep -vE '^[+-]\s*\*' | grep -vE '^[+-]\s*$' Expected: empty output — every changed line is a *-prefixed C comment line (no code line changed).

Run: cargo test -p ailang-codegen --test embed_record_layout_pin 2>&1 | grep 'test result:' Expected: test result: ok. … 0 failed — the frozen-IR pin is byte-identical (it asserts generated IR, not rc.c comments; M3.tidy precedent).

---

Task 3: Consolidated doc-only + scope gate

Files: (none — verification only)

• Step 1: Whole doc-only gate green (all pins, both crates)

Run: cargo test -p ailang-core --test design_schema_drift --test docs_honesty_pin --test effect_doc_honesty_pin 2>&1 | grep -c 'test result: ok' then cargo test -p ailang-codegen --test embed_record_layout_pin 2>&1 | grep 'test result:' Expected: the first prints 3 (three ok result lines, 0 failed across the three ailang-core pin suites); the second test result: ok. … 0 failed. Together: every pin that reads DESIGN.md or the frozen IR is green → the prose/comment edits moved no pinned byte (the M2.tidy/M3.tidy "pins are the coverage" gate).

• Step 2: Diff scope is exactly the three content sites + iter artefacts

Run: git status --porcelain Expected: modified docs/DESIGN.md + runtime/rc.c only as content changes, plus the (untracked) iter journal docs/journals/2026-05-19-iter-embedding-abi-m5.tidy.md and stats bench/orchestrator-stats/2026-05-19-iter-embedding-abi-m5.tidy.json. Zero change to any crates/** source, examples/**, ail-embed/**, Cargo.toml, bench/baseline.json, or any *.ail/*.rs file. Mechanically confirms doc/comment-only.

• Step 3: No behaviour change — workspace still builds

Run: cargo build --workspace 2>&1 | tail -1 Expected: Finished \dev` profile …` (a comment-only rc.c change + markdown edits cannot affect compilation; this confirms it).

---

Self-review (planner Step 5)

1. Spec coverage. Audit DRIFT item [medium] DESIGN.md:2358-2360 stale-M4 → Task 1 edit-1. [medium] DESIGN.md §"Embedding ABI" concurrency-claim silence → Task 1 edit-2. [low] rc.c:88 "two unconditional ++" → Task 2 edit-3. The architect's "one tidy, same honesty axis, do not split" → one plan, one cohesive commit (Task 1+2 are the content; Task 3 is the gate). All three charter items covered; nothing else in scope (doc-only).
2. Placeholder scan. No "TBD/TODO/implement later/similar to/add appropriate". The OLD/NEW prose blocks are exact verbatim content, not placeholders.
3. Type/name consistency. Paths (docs/DESIGN.md, runtime/rc.c), test targets (design_schema_drift, docs_honesty_pin, effect_doc_honesty_pin, embed_record_layout_pin), line anchors (2287-2298, 2354-2360, rc.c:88, line 2299) — identical across tasks and verification.
4. Step granularity. Each step is one read / one edit / one command; all 2-5 min.
5. No commit steps. None. Work stays in the working tree; Boss commits the cohesive tidy.
6. Pin/replacement substring contiguity. The verification greps (grep 'Export parameters are written **bare**', grep 'test result:', the comment-only git diff filter) assert over file/command output, NOT over a verbatim replacement body this plan writes. Recon explicitly verified the pinned substrings (docs_honesty_pin.rs:135 line-2299 bare-scalar; the data-model-slice schema anchors; the IR-byte pins) are NOT inside either NEW prose block — no presence-pin/verbatim-edit collision. Task 1 Step 5 explicitly guards the one adjacency risk (line 2299 must stay byte-identical).
7. Compile-gate vs deferred-caller. No signature/code change at all (doc + C-comment only). Task 3 Step 3's cargo build --workspace gate is trivially satisfiable (no code touched); not a deferred-caller hazard.
8. Verification filter strings resolve. --test design_schema_drift / --test docs_honesty_pin / --test effect_doc_honesty_pin / --test embed_record_layout_pin are recon-verified existing runnable targets (recon built them --no-run); grep -c 'test result: ok' expects the explicit count 3 (not "≥0"), and the bare-scalar / comment-only greps assert explicit non-empty / empty output, so "nothing ran" cannot masquerade as success. No filter resolves to zero tests.