diff --git a/docs/journals/2026-05-18-audit-embedding-abi-m1.md b/docs/journals/2026-05-18-audit-embedding-abi-m1.md new file mode 100644 index 0000000..74e2b59 --- /dev/null +++ b/docs/journals/2026-05-18-audit-embedding-abi-m1.md @@ -0,0 +1,155 @@ +# audit embedding-abi-m1 — milestone close (CLEAN — carry-on, NO ratify) + +**Date:** 2026-05-18 +**Scope:** `064599e..e406d07` +**Verdict:** Milestone audit **CLEAN**. Architect `clean` (one +`[low]` evidence-adjudicated to carry-on); bench `check.py` exit 1 +**decisively causally exonerated** (21/21 byte-identical bench +binaries vs pre-milestone), `compile_check.py` / `cross_lang.py` +exit 0. No fix iteration, **no baseline ratify**. + +## Commit map + +- `064599e` — pre-milestone HEAD (bench/architect diff baseline). +- `51160e9` spec, `b0bd7ef` plan — docs only. +- `123ae1b` — USER-authored roadmap-P2 ("DESIGN.md → `design/` + role-split"), `docs/roadmap.md` only, path-disjoint — explicitly + out of M1 audit scope (Boss roadmap maintenance, architect told + to skip it; it is not M1 code/doc work). +- `818177d` — iter partial (Tasks 1–3) + a Boss plan Repair + (Design-decision 6, the module≠stem fixture defect). +- `e406d07` — iter completion (Tasks 4–7) + INDEX line. + +## Step 1 — Architect drift review + +**Status: `clean`.** All four focus areas + standing concerns +verified against the `064599e..e406d07` diff: + +- **Invariant 1 (clean core) holds semantically.** No + finance/`data-server` vocabulary, logic, or dependency entered + `ailang-core` / `ailang-codegen` / `runtime/`. `backtest_step` + is an opaque author-chosen string flowing through generic + `FnDef.export`; the only "backtest" occurrences in core/codegen + are test-fixture filenames + mangled-symbol assertions in test + files, not domain knowledge. AILang↔host meeting point correctly + deferred (no `ail-embed`, no runtime lifecycle API) — M1 scope + respected. +- **DESIGN.md honesty rule satisfied.** New §"Embedding ABI (M1)" + + fn-JSON `"export"` line + `FnDef.export` rustdoc are + present-tense current state; "provisional until M3" / "M2 will + change this C signature" are correctly *labelled* reserved- + unimplemented, not stated as present fact, no + post-mortem/Wunschdenken. Sweep hits (DESIGN.md:50/:2060/:62) + all pre-existing, out of M1 range. +- **Lockstep intact.** `FnDef` ↔ DESIGN.md §Data-model fn-JSON ↔ + `design_schema_drift.rs`/`spec_drift.rs` all carry the field. + The `@` forwarder is additive raw-IR emission *beside* the + unchanged `@ail__` mangling — does not route through + `lower_app`, so the `lower_app`/`is_static_callee` and + `Pattern::Lit` lockstep pairs are not engaged. Schema stays + exhaustively-constructed (~85 sites uniform `export: None`, no + `_ =>` / `..Default::default()` — plan Design-decision 1 + honoured). In-source `missing_entry_main_is_error` pin (now + L3411) behaviourally byte-unchanged (only the mandatory field + added). `_adapter`/`_clos` closure pair untouched (spec "Out of + scope"). +- **Design-decision 6 confirmed correct, not re-flagged.** The + gate/headline fixtures' `(module embed_*)` == file-stem; the + divergence from the spec's *illustrative* `(module backtest)` / + `(module bad)` blocks is expected under the loader's + module==stem invariant + spec Decision 2 (C symbol + `backtest_step` decoupled via `(export …)`). The fixtures + *demonstrate* the decoupling rather than violate the spec. + +**Drift / debt — one item, adjudicated:** + +- `[low]` ~85 inserted `export: None,` lines indented to the + struct-literal brace column rather than the field column + (`rustfmt`-divergent struct literals; compiles 611/0, semantics + unaffected). **Orchestrator adjudication → carry-on (NOT a fix, + NOT pending).** Evidence: `cargo fmt --all --check` reports + **1137 fmt-divergent locations tree-wide** (pre-existing + `builtins.rs` / `diagnostic.rs` / dozens of `lib.rs` sites + predating M1). rustfmt is demonstrably **not** a project + convention — the hand-formatted codebase tolerates 1137 + divergences. The architect's premise ("a `cargo fmt` pass would + churn later") is therefore moot: no such gate exists or is + coming, and selectively rustfmt-aligning 85 of 1137 sites would + *impose* a standard the project does not hold, which is noise, + not tidy. This is an evidence-based adjudication of the + architect's finding (premise falsified), not "trivial, ignore + it". If AILang ever adopts a fmt gate that is a tree-wide + decision (1137 sites), unrelated to M1. + +## Step 2 — Bench-regression check + +| Script | Exit | Result | +|---|---|---| +| `bench/check.py` | **1** | 63 metrics; 7 regressed, 2 improved, 54 stable | +| `bench/compile_check.py` | 0 | 24 metrics; 0 regressed | +| `bench/cross_lang.py` | 0 | 25 metrics; 0 regressed | + +**The 7 `check.py` firings:** +`throughput.bench_list_sum.bump_s` +12.27%, +`throughput.bench_hof_pipeline.bump_s` +12.67%, +`throughput.bench_list_sum_explicit.bump_s` +13.74%, +`latency.explicit_at_rc.p99_9_us` +36.13%, +`latency.explicit_at_rc.max_us` +101.43%, +`latency.implicit_at_rc.p99_9_us` +67.32%, +`latency.implicit_at_rc.max_us` +123.57%. + +**Decisive causal exoneration (bencher localisation).** Hypothesis: +M1's `Target::Executable` default leaves the entire bench corpus's +emitted machine code byte-unchanged; the firings are pre-existing +environmental/sampling noise, not M1. + +- **21/21 bench binaries `cmp`-byte-identical** between `064599e` + and `e406d07` (`bench_list_sum_bump` sha `dce18c288904c9f0` at + both commits; every one of the 6 fixtures × 3 modes + 3 latency + arms IDENTICAL, 0 DIFFER). `ail` self-hash differs (expected — + Rust source changed for the embedding ABI) but the *emitted + machine code* for every bench fixture is identical because every + fixture builds an executable via the unchanged `Target::Executable` + default. **Zero codegen/runtime causal mechanism exists.** +- The RC-latency tails reproduce *on the byte-identical oracle + binary itself*, swinging 3× run-to-run (`explicit_at_rc.max_us` + per-run 376→1200 us; `implicit_at_rc.max_us` 562→1742 us) while + median/p99 hold steady — the documented `-n 5` single-sample- + jitter signature. +- Fresh `check.py` re-run: the `*.bump_s` trio → ok, 4 of 7 + original firings → ok, only `explicit_at_rc.max_us` still trips + (+26%, byte-oracle-proven environmental). +- Both firing families map (confirmed, not assumed) onto the two + pre-existing **roadmap-P2** tracked items: `*.bump_s` baseline- + vs-current-hardware staleness, and the RC-latency `*.max_us` / + `*.p99_9_us` `-n 5` structural false-positive (this is the ~4th + zero-runtime-change milestone close on which they fire and + collapse on identical-code re-run). + +**Classification: carry-on, NO baseline ratify.** Per the audit +Iron Law a baseline update requires a paired JOURNAL ratify entry +naming an iter that *intentionally* moved the metric; M1 by +construction moved **zero** default-path bytes (21/21 binaries +identical), so a ratify would bake noise into `baseline.json` — +forbidden. The spec forecloses a zero-codegen baseline bump. The +residual flapping is pre-existing, already roadmap-P2-tracked; the +genuinely next-best action (re-capture `baseline.json` on current +hardware at higher N, or widen single-sample tail tolerances) is a +separate bench-harness iteration, **not** an M1 concern — the two +P2 items remain orchestrator-owned and are NOT bundled into this +close (bencher recommendation honoured, consistent with the +remove-mut-var-assign / docs-honesty-lint closes). + +## Step 3/4 — Resolution + +**carry-on (clean).** No fix iteration, no ratify, no commit beyond +this journal + its INDEX line. Architect clean; the sole `[low]` is +evidence-adjudicated non-actionable; bench firings decisively +non-causal (21/21 byte-identical binaries) and mapped to existing +P2 noise. Both bench gates that can pass on the merits do +(`compile_check`/`cross_lang` exit 0; `check.py` exit 1 causally +exonerated). + +**M1 milestone audit CLEAN.** Next pipeline step: `fieldtest` — +M1 added user-visible authoring surface (`(export "")`), so +the surface-touch fieldtest gate applies before milestone close. diff --git a/docs/journals/INDEX.md b/docs/journals/INDEX.md index cb8b925..0e5385e 100644 --- a/docs/journals/INDEX.md +++ b/docs/journals/INDEX.md @@ -94,3 +94,4 @@ - 2026-05-18 — iter docs-honesty-lint.1 (single-iteration milestone, DONE): canonical docs made present-tense-honest. Stripped Wunschdenken (forward intent stated as fact) + non-citation post-mortem/doc-archaeology from `docs/DESIGN.md` (14 corrections: L484 iter-anchor, L503/L1318/L1504/L2027/L2065/L2135 post-mortem, L650 malformed-Wunschdenken, L655 dated-heading, L1513/L1837/L2046/L2519 Wunschdenken, + the Task-4-Step-14 procedural-catch-all FIX at the Form-B prose-projection bullet "was deferred from milestone 22 entirely … A future iter ships" — a soft-wrapped site the spec's illustrative regex would have missed, the procedural enumeration working exactly as designed) + `docs/PROSE_ROUNDTRIP.md` (tool-use/MCP paragraph); genuine forward intent (LLM tool-use/MCP/LSP) relocated to roadmap P3. Codified the two-pronged tense+modality discriminator as a present-tense `### What this document is — and the honesty rule it holds itself to` meta-subsection in DESIGN.md §"Project ecosystem". Anti-regrowth two ways: wrap-robust enumerated absent/present pin `crates/ailang-core/tests/docs_honesty_pin.rs` (a `norm()` whitespace-collapse helper structurally discharges the recurring grep/contains line-wrap failure family — strictly better than the effect-doc-honesty "keep-on-one-line" precedent; resolves spec Testing-item 0 + planner self-review item 6 at once) + wrap-robust advisory Sweep 5 in `bench/architect_sweeps.sh` (contiguous-fragment regex, since DESIGN.md is hard-wrapped ~70col) with full sweep-count lockstep (header + "All four"→"All five" tail + `ailang-architect.md` "four"→"five sweeps") + a new `ailang-architect.md` "DESIGN.md honesty drift" bullet citing the meta-subsection. Protected-exception KEEPs preserved + pinned-present (Diverge-reserved, regions-considered-and-rejected, the self-labelled "tiebreaker, not a rationale"); `form_a.md` correctly left untouched/unpinned. One plan-internal DONE_WITH_CONCERNS (Task-1 pin string omitted a `**…**` bold the Task-3 body added; resolved by dropping the non-load-bearing emphasis, pin is the contract) — planner self-review-item-3 calibration note. Independent Boss verification: pin 4/4 GREEN, full `cargo test --workspace` 0 failures (delta = +4 pin tests only), sentinel trio (`design_schema_drift`/`spec_drift`/`schema_coverage`) green, `cargo build --workspace` clean, scope = ONLY THE PIN in `crates/` (zero language/checker/codegen/runtime change, `ail check`/`run`/`build` byte-unchanged by construction). Post-iter sweep residue = only the 3 documented deliberate KEEPs (Sweep-1 L50 doc-roles-pointer date + L2060 true `(iter str-concat)` provenance; Sweep-5 L62 self-referential discriminator-catalogue), EXIT=1 architect-adjudicated-expected. Milestone-close `audit` is the next pipeline step (no fieldtest — zero authoring-surface change). spec `docs/specs/2026-05-18-docs-honesty-lint.md` (grounding-check PASS 10/10), plan `docs/plans/docs-honesty-lint.1.md` → 2026-05-18-iter-docs-honesty-lint.1.md - 2026-05-18 — audit docs-honesty-lint (milestone close, CLEAN — carry-on, NO ratify): scope `928e1c0..e50b400`. Architect `clean`: scope claim exact (zero `crates/**/src/**` + `runtime/`; sole crates/ change the additive RED-first-now-GREEN `docs_honesty_pin.rs`; lockstep pairs untouched), all 14 DESIGN.md corrections genuinely present-tense with the 4 protected KEEPs (`Diverge`-reserved/`Regions`-rejected/`tiebreaker`/`No deriving`) un-stripped, agent-def "four→five" lockstep complete, sweep residue exactly the 3 documented deliberate KEEPs. One `[medium]` standing advisory wart — Sweep 5's regex self-matches the discriminator subsection's own forbidden-phrasing catalogue (DESIGN.md L62) forever (architect-flagged; orchestrator-adjudicated → filed as a P3 todo, NOT a fix iteration — not a new failure mode since the script is advisory-with-residue by design). Bench: `compile_check.py` 0/24 + `cross_lang.py` 0/25 EXIT 0 (cross_lang independently reads the same `bench_list_sum` bump path +5.95% within tol); `check.py` EXIT 1, 3 firings (`bench_list_sum.bump_s` +13.42%, `latency.implicit_at_rc.{p99_9,max}_us` +37.65%/+134.70%). Bencher causal exoneration **decisive**: HEAD vs `5bb7211` vs `de66eb7` — all 5 firing bench binaries `cmp`-byte-identical, `ail` sha256 identical at all three commits ⇒ zero causal mechanism; `*.max_us` = tracked-P2 `-n 5` tail-jitter (4th occurrence on a zero-runtime-change milestone, median/p99 rock-steady), `*.bump_s` = tracked-P2 environmental-anchor-staleness (persistent ~+15%, stale 0.046s anchor). **EXONERATED, NO baseline ratify** (Iron Law forbids ratifying noise; spec forecloses a zero-codegen baseline bump). Two pre-existing standing P2 items kept orchestrator-owned, explicitly NOT bundled into this close (bencher recommendation honoured). Milestone audit **CLEAN**; no fieldtest (zero authoring-surface change — the wrap-robust pin + Sweep 5 ARE the regression coverage). **docs-honesty-lint fully ratified and CLOSED**: spec (grounding-check PASS 10/10) + plan + single iter + audit clean; roadmap P0 flipped `[~]`→`[x]`, WhatsNew.md user-facing entry appended → 2026-05-18-audit-docs-honesty-lint.md - 2026-05-18 — iter embedding-abi-m1.1 (Embedding-ABI M1, DONE across 2 dispatches + a Boss plan Repair): a compiled AILang scalar `fn` is now callable in-process from a C/Rust host. Five pipeline layers shipped: additive `FnDef.export: Option` (serde `default`+`skip_serializing_if`, modelled on `FnDef.doc`, ~85-site compile-driven thread incl. all in-source `#[cfg(test)]`/drift/hash literals, hash-stable golden `b4662aa70839f60b`); Form-A `(export "")` modifier (parse/print/`form_a.md` lockstep, byte-identical round-trip); check-side scalar-only+effect-free export gate — two new `CheckError` Error variants `export-non-scalar-signature`/`export-has-effects`, params→ret→effects first-violation-wins, unconditional on `f.export.is_some()` (the feature-acceptance clause-3 discriminator *in code*); codegen `Target::StaticLib` (suppresses `@main`+`MissingEntryMain`, emits one external `@` forwarder per export to `@ail__`); CLI `ail build --emit=staticlib` (`build_staticlib`: `libembed_backtest_step.a` program-only + separate `libailang_rt.a`). Coherent stop PROVEN: `embed_e2e.rs` `cc`-links both archives, `backtest_step(0,3)=9`/`(9,4)=25`, `s==25`, exit 0. Task 1 (fixed-first CLI `MissingEntryMain` baseline pin) green before any staticlib code. Process: Task 4 BLOCKED on the first dispatch — a Boss plan-defect (gate/headline fixtures declared `module ≠ file-stem`; the loader hard-enforces `module==stem` at `workspace.rs:438`, so `ail check` panicked on load before the gate). Boss verified, chose **Option 2 over the orchestrator-recommended Option 1** (keep descriptive `embed_*` filenames, rename fixture *modules* to their stems — the C symbol `backtest_step` stays via `(export …)`, *demonstrating* spec Decision 2's mangling-decoupling rather than violating it; archive→`libembed_backtest_step.a`, internal→`@ail_embed_backtest_step_step`, `host.c` unchanged), Repaired the plan (Design-decision 6 + Task-4 module==stem + Task-5/6/7 dependent strings + folded the no-`*.`-Float-head and `content_hash_fn`→`def_hash` concerns), committed Tasks 1–3 as a verified known-good partial (`818177d`), re-dispatched [4,7]. Independent Boss verification post-completion: E2E 1/1, gate 6/6, lowering 2/2, CLI 2/2, full `cargo test --workspace` 0 failures, `roundtrip_cli`+`design_schema_drift`+`spec_drift` green, Invariant 1 holds (no new dep in `ailang-core`/`ailang-codegen`/`runtime`). 3 behaviour-neutral plan pseudo-vs-reality concerns recorded (`emit_ir` routes via `lower_workspace`; dead `Path` import dropped; `##` vs `###` heading). Bench: `compile_check.py`/`cross_lang.py` exit 0; `check.py` exit 1 = tracked-P2 `*.bump_s`/`*.max_us` known-noise (default-exe codegen/runtime byte-unchanged — audit-adjudicated, not a plan gate). spec `docs/specs/2026-05-18-embedding-abi-m1.md` (grounding-check PASS) → plan `docs/plans/embedding-abi-m1.1.md` (Repaired) → commits `818177d` (partial 1–3) + this completion. Milestone-close `audit` then `fieldtest` (surface-touching — `(export …)` is new authoring surface) are the next pipeline steps. → 2026-05-18-iter-embedding-abi-m1.1.md +- 2026-05-18 — audit embedding-abi-m1 (milestone close, CLEAN — carry-on, NO ratify): scope `064599e..e406d07`. Architect `clean` — Invariant 1 (clean core) holds semantically (no finance/`data-server` vocab/logic/dep in `ailang-core`/`ailang-codegen`/`runtime`; `backtest_step` is an opaque author string through generic `FnDef.export`; AILang↔host meeting point correctly M5-deferred), DESIGN.md honesty satisfied (§"Embedding ABI (M1)" + fn-JSON `"export"` + field rustdoc present-tense; "provisional until M3"/"M2 changes the C sig" correctly *labelled* reserved-unimplemented), lockstep intact (`FnDef`↔fn-JSON↔drift/spec-drift carry the field; `@` forwarder additive raw-IR *beside* unchanged `@ail__` mangling — not through `lower_app`; schema exhaustively-constructed, no `_=>`/`..Default`; in-source `missing_entry_main_is_error` byte-unchanged; `_adapter`/`_clos` untouched), Design-decision 6 confirmed correct (fixture module==stem differs from the spec's *illustrative* `(module backtest)`/`(module bad)` by the loader invariant + spec Decision 2 — the fixtures *demonstrate* the C-symbol decoupling, not violate the spec). One `[low]` — ~85 `export: None,` lines brace-column-indented (rustfmt-divergent) — **orchestrator-adjudicated carry-on on evidence** (not pending, not ignored): `cargo fmt --all --check` shows **1137 fmt-divergent locations tree-wide predating M1**, so rustfmt is demonstrably not a project convention and the architect's "cargo fmt would churn later" premise is moot; selectively aligning 85/1137 would impose an absent standard (noise, not tidy). Bench: `compile_check.py` 0/24 + `cross_lang.py` 0/25 EXIT 0; `check.py` EXIT 1, 7 firings (`*.bump_s` trio +12–14%; `explicit_at_rc`/`implicit_at_rc` `p99_9`/`max_us` +36–124%). Bencher causal exoneration **decisive**: 21/21 bench binaries `cmp`-byte-identical `064599e`↔`e406d07` (`bench_list_sum_bump` sha `dce18c288904c9f0` both) — M1's `Target::Executable` default leaves every bench fixture's emitted machine code unchanged ⇒ zero causal mechanism; RC-latency tails reproduce *on the byte-identical oracle itself* (3× run-to-run swing, median/p99 steady = `-n 5` single-sample jitter); fresh re-run collapsed 6/7 firings to ok. Both families map (confirmed) onto the two pre-existing roadmap-P2 tracked items (~4th zero-runtime-change milestone they fire+collapse on). **EXONERATED, NO baseline ratify** (Iron Law forbids ratifying noise against a zero-default-path-byte iter; spec forecloses a zero-codegen baseline bump); the two P2 bench-harness-recalibration items stay orchestrator-owned, NOT bundled (bencher recommendation honoured). M1 milestone audit **CLEAN**; `fieldtest` (surface-touching — `(export "")` is new authoring surface) is the next pipeline step before close → 2026-05-18-audit-embedding-abi-m1.md