AILang/docs/journals/2026-05-14-iter-pd.2.md

iter pd.2 — surface owns prelude embed; pd.1 shim retired

Date: 2026-05-14 Started from: 116157a2b8 Status: DONE Tasks completed: 6 of 6

Summary

pd.2 moves the prelude embed (PRELUDE_AIL const + parse_prelude fn) and the prelude-injection step (with the ReservedModuleName reservation) out of ailang-core into ailang-surface, rewires surface::load_workspace from the 3-line shim-call into the 7-line composition (load_modules_with → reserved-name check → inject parse_prelude → build_workspace(&["prelude"])), and retires the pd.1 compatibility shim core::load_workspace_with along with load_one, load_prelude, PRELUDE_JSON, and the #[cfg(test)] use crate::load_module; import. Cross-form-identity preflight (hash-equality between parse(prelude.ail) and serde_json::from_str(prelude.ail.json)) PASSES at hash 3abe0d3fa3c11c99 — the load-bearing assumption that justifies pd.3's deletion of prelude.ail.json is verified. Production literal-"prelude" count in core/src/ is now zero. Test count: 573 green (from the pd.1 baseline of 564, +9 net = 3 new surface pins [parse + hash + injection] + 6 tempdir/fixture relocations to workspace_pin.rs minus 6 in-mod placeholders that became comments; in-mod test deletion of the pd.1 shim test is offset by the load_modules_with_custom_loader_is_called rename + 2 pd.1 tests that now use an inline test-private load_one helper). bench/cross_lang.py

• bench/compile_check.py exit 0; bench/check.py exit 1 with the 12-audit noise envelope (the bench_list_sum.bump_s + tail-latency oscillation that has been observed in audits since audit-cma; pd.2 is a workspace-loader refactor with zero codegen / runtime touch). pd.3 will delete examples/prelude.ail.json plus the prelude_ail_and_json_parse_to_identical_module preflight, the include_str! carve-out in crates/ail/src/main.rs:472-484, the carve_out_inventory.rs §C4(b) row, the form-a §C4(b) spec text, and the migrate-bare-cross-module-refs defensive include.

Per-task notes

• iter pd.2.1: pub const PRELUDE_AIL: &str = include_str!("../../../examples/prelude.ail");
  • pub fn parse_prelude() -> Module added near the top of crates/ailang-surface/src/loader.rs; both re-exported from ailang-surface/src/lib.rs. RED test parse_prelude_returns_module_named_prelude_with_min_defs failed with the expected unresolved-import message, then GREEN. First-shot clean.
• iter pd.2.2: crates/ailang-surface/tests/prelude_module_hash_pin.rs with prelude_ail_and_json_parse_to_identical_module (cross-form- identity preflight, load-bearing for pd.3) + prelude_parse_yields_canonical_hash (literal-hex anchor). Preflight PASSED first-run (the round-trip invariant from form-a.0 + form-a.1 was already exercising parse-then-print idempotency on every .ail fixture, so parse(prelude.ail) ≡ deserialize(prelude.ail.json) was not an accident). Hash 3abe0d3fa3c11c99 captured at pd.2 close.
• iter pd.2.3: surface::load_workspace rewritten 3-line → 7-line composition; imports updated load_workspace_with → bare Workspace, WorkspaceLoadError with load_modules_with / build_workspace fully-qualified inline; module rustdoc rewritten to name the new injection point + the implicit-imports list. Regression-pin tests surface_load_workspace_injects_prelude_into_every_workspace
  • surface_load_workspace_rejects_user_module_named_prelude PASS before AND after the rewrite (semantics preserved). DONE_WITH_CONCERNS: the plan's example used examples/hello.ail.json which doesn't exist post-form-a.1 (deleted in T8); switched to examples/hello.ail.
• iter pd.2.4: 10 in-mod tests RELOCATED to crates/ailang-core/tests/workspace_pin.rs rather than aliased per the plan's literal text — the dev-dep cycle (ailang-core ↔ ailang-surface via [dev-dependencies]) makes surface::load_workspace calls from ailang-core's lib-test crate structurally impossible (two distinct compilations of ailang-core appear in the test build, types don't match). The integration-test crate consumes both crates against the same ailang-core artefact, so the cycle never materialises — same pattern form-a.1 T5 used for similar relocations. The 11th test (load_workspace_with_custom_loader_is_called) renamed to load_modules_with_custom_loader_is_called with the closure adapted to wrap crate::load_module directly via the same Io/Schema mapping load_one had. The 12th test (load_workspace_with_shim_preserves_today_semantics) deleted outright with a forwarding comment to the surface-side hash pin.
• iter pd.2.5: 5 deletions (PRELUDE_JSON, load_prelude, load_workspace_with, top-level load_one, #[cfg(test)] use crate::load_module;); module rustdoc reworked to two-phase composition framing; lib.rs three rustdoc sites (lines 16-21, 50-51, 120) re-pointed at ailang_surface::load_workspace. ONE plan-vs-actual deviation: the plan didn't enumerate the 2 pd.1-introduced in-mod tests at the bottom of mod tests that consume load_one directly (load_modules_with_returns_modules_without_prelude, build_workspace_accepts_assembled_modules_and_runs_validation); preserved by adding a test-mod-private load_one helper inside mod tests (production-symbol-level deletion preserved; helper is scoped only to the test module, not exported). The build_workspace... test also called load_prelude() directly; replaced inline with serde_json::from_str(include_str!(...)) of prelude.ail.json (the same one-line code load_prelude was). Zero literal-"prelude" strings in production core/src/ confirmed by grep. cargo doc warnings: 3 (unchanged from pre-pd.2 baseline; all three are dangling [load_workspace] references in the Workspace / Registry rustdoc that pd.1 left behind when it deleted load_workspace; out of scope per the implementer's no-surrounding-cleanup discipline, recorded as known debt).
• iter pd.2.6: bench verification — cross_lang.py exit 0 (25/25 stable), compile_check.py exit 0 (24/24, "11 regressed" reported but exit code says baseline-tolerance check passes — this is the audit-form-a + clippy-sweep-named noise on the corpus's small build fixtures), check.py exit 1 with 1 regression on bench_list_sum.bump_s +13.61% (within established noise envelope; second run showed same bump_s plus a tail-latency implicit_at_rc.p99_us blip). All three are runtime/compile metrics that cannot be touched by a workspace.rs/loader.rs/lib.rs refactor (no codegen / no runtime / no typecheck path edited).

Concerns

• pd.2.3: plan's regression-pin used examples/hello.ail.json which doesn't exist post-form-a.1 T8. Switched to examples/hello.ail. Recommend a planner check: when a plan references a .ail.json fixture, verify the fixture exists post-form-a.1 (the carve-out inventory is the right reference).
• pd.2.4: plan's "alias to surface_load_workspace and stay in-mod" was structurally invalid because of the ailang-core ↔ ailang-surface dev-dep cycle inside the lib-test target. Relocated to tests/workspace_pin.rs instead — same pattern form-a.1 T5 used. Recommend: planner recon-check should detect when a planned in-mod test is meant to consume an external dev-dep cycle that the lib-test target can't resolve.
• pd.2.5: plan's "delete load_one" preserved at production-symbol level (the top-level #[cfg(test)] fn load_one is gone) by introducing a test-mod-private fn load_one helper inside mod tests for the 2 pd.1 in-mod tests that still consume it. The symbol's name is preserved for clarity; its scope is now narrower than pre-pd.2.
• pd.2.6: check.py exit 1 — established noise envelope, 13th consecutive observation pattern (audit-cma onwards). pd.2 is a workspace-loader refactor with zero codegen / runtime / typecheck touch, so cannot be the source. Baseline left pristine consistent with all prior audit decisions on this envelope.

Known debt

• 3 cargo doc warnings on [load_workspace] references in the Workspace (line 44, 49) + Registry (line 64) rustdoc — pd.1 deleted load_workspace but didn't sweep these references. Pre- pd.2 baseline already carried them; pd.2 didn't add to the count; not within pd.2 scope (no-surrounding-cleanup discipline).
• pd.3 work explicitly out of scope: deleting examples/prelude.ail.json, the prelude_ail_and_json_parse_to_identical_module preflight test (which depends on the JSON file's existence), the include_str! of prelude.ail.json in crates/ail/src/main.rs:472-484, the carve_out_inventory.rs §C4(b) row, the form-a §C4(b) spec text edits, and the migrate-bare-cross-module-refs defensive include.

Files touched

Modified:

• crates/ailang-core/src/lib.rs (3 rustdoc sites updated)
• crates/ailang-core/src/workspace.rs (5 deletions + module rustdoc reframe + 2 pd.1 in-mod test repairs + 6 in-mod test placeholders + test-mod-private load_one helper restored at narrow scope)
• crates/ailang-core/tests/workspace_pin.rs (10 relocated tests appended + helper fn write_simple_module_json + preamble extension)
• crates/ailang-surface/src/lib.rs (re-export of parse_prelude + PRELUDE_AIL)
• crates/ailang-surface/src/loader.rs (PRELUDE_AIL const + parse_prelude fn added; load_workspace body 3-line → 7-line composition rewrite; module rustdoc reframed; imports updated)

New:

• crates/ailang-surface/tests/prelude_parse_pin.rs (1 test)
• crates/ailang-surface/tests/prelude_module_hash_pin.rs (2 tests: cross-form-identity preflight + literal-hex anchor 3abe0d3fa3c11c99)
• crates/ailang-surface/tests/prelude_injection_pin.rs (2 tests: inject + reservation pin)

Stats

bench/orchestrator-stats/2026-05-14-iter-pd.2.json