Files

T

Brummel a29700cc9e iter effect-doc-honesty: make the effect-system documentation true

Standalone documentation-honesty tidy (no language/checker/codegen
change; `ail check`/`run` byte-unchanged by construction). Corrects
three false effect-system claims the effect-subsystem recon surfaced,
plus two satellite mentions, guarded by a new doc-presence pin:

- DESIGN.md Decision 3: removed the "row-polymorphic (`![IO | r]`)"
  claim (no EffectRow / row variable exists in any crate — effect
  sets are a flat, unordered, closed set unified by set-equality);
  reconciled "`IO` and `Diverge` are wired up" to IO-only +
  `Diverge` reserved/unimplemented (zero code in any crate),
  modelled on Decision 4's reserved-refinements precedent.
- DESIGN.md "What is not (yet) supported": "IO and Diverge ops"
  bullet -> IO-only + Diverge-reserved.
- ast.rs Term::Do doc-comment: "resolved against the effect-handler
  table at link time" -> the real mechanism (typecheck lookup in
  Env::effect_ops + literal lower_effect_op codegen match; no
  handler table, no link-time resolution).
- form_a.md:226 + rule 3, and main.rs merge-prose CONTRACT example:
  Diverge mentions reconciled in lockstep.
- new crates/ailang-core/tests/effect_doc_honesty_pin.rs: 4 tests,
  fiction-absent + corrected-anchor-present, single-line wrap-robust
  substrings.

cargo test --workspace 600 -> 604 (4 new pin tests, 0 regressions);
design_schema_drift / spec_drift / schema_coverage stay green,
empirically confirming none scans the effect-prose region.

2026-05-16 13:25:49 +02:00

3.8 KiB

Raw Blame History

iter effect-doc-honesty — effect-system documentation-honesty tidy

Date: 2026-05-16 Started from: c41e0e5a9e Status: DONE Tasks completed: 6 of 6

Summary

Documentation-honesty tidy: corrected three false effect-system claims plus their two satellite mentions across the project docs, guarded by one new doc-presence regression pin. No language, checker, or codegen code changed — only a doc-comment, two markdown spec files, an internal CLI guidance string, and a new integration test. ail check/ail run behaviour is byte-unchanged by construction; cargo test --workspace 600 → 604 (the four new pin tests, zero regressions), cargo build --workspace clean. The three sentinel drift/coverage tests (design_schema_drift, spec_drift, schema_coverage) stay green, empirically confirming none scans the effect-prose region.

Per-task notes

iter effect-doc-honesty.1: new pin crates/ailang-core/tests/effect_doc_honesty_pin.rs (4 tests asserting fiction strings absent + corrected anchors present across the 4 edited files); authored first, ran RED 0/4 for the right reason (TDD: RED before corrections).
iter effect-doc-honesty.2: docs/DESIGN.md Decision 3 row-polymorphic block → flat/unordered/closed set-equality + Diverge-reserved wording; line-2722 "IO and Diverge ops" bullet → IO-only + Diverge-reserved bullet. design_md_effect_prose_is_true GREEN.
iter effect-doc-honesty.3: crates/ailang-core/src/ast.rs Term::Do doc-comment effect-handler-table-at-link-time fiction → real mechanism (typecheck against Env::effect_ops, lower_effect_op literal-match codegen). term_do_doc_comment_is_true GREEN.
iter effect-doc-honesty.4: crates/ailang-core/specs/form_a.md line-226 "currently IO and Diverge" → IO-built-in-op / Diverge-reserved; rule-3 "Diverge for diverge/*" → io/print_str-is-the-only-built-in-op. form_a_spec_effect_names_are_true GREEN.
iter effect-doc-honesty.5: crates/ail/src/main.rs merge-prose CONTRACT effect-annotation bullet dropped the non-existent (effects Diverge) example. Whole pin 4/4 GREEN.
iter effect-doc-honesty.6: full verification — whole pin 4/4, cargo test --workspace 604/0 (600 prior + 4), drift/coverage trio green, cargo build --workspace clean.

Concerns

Task 2: the plan's verbatim Task-2 replacement body soft-wrapped the phrase "flat, unordered,\nclosed set of effect names" mid-phrase, which contradicts Task-1's single-line pin substring "flat, unordered, closed set of effect names" AND the plan's own self-review item 6 ("every pin substring is single-line — the documented iter-revert grep-wrap failure mode is avoided"). The two authoritative artefacts (exact replacement text vs. exact pin) could not both be applied verbatim. Resolved by preserving the exact corrected wording (byte-identical to the plan's intent) and the exact pin (Task 1, unchanged), moving only the soft-wrap column so the asserted phrase stays contiguous on one line. No wording added/dropped/changed. This is a planner self-review-item-3 cross-check gap (the asserted-substring vs. replacement-body check did not account for the replacement body's own line wrap) — orchestrator may want to tighten the planner's pin/replacement-body wrap cross-check.

Known debt

(none) — the tidy is self-contained; no deferred follow-up.

Files touched

crates/ailang-core/tests/effect_doc_honesty_pin.rs (new — the pin)
docs/DESIGN.md (Decision 3 + "What is not supported" bullet)
crates/ailang-core/src/ast.rs (Term::Do doc-comment)
crates/ailang-core/specs/form_a.md (line 226 + rule 3)
crates/ail/src/main.rs (merge-prose CONTRACT string)

Stats

bench/orchestrator-stats/2026-05-16-iter-effect-doc-honesty.json

3.8 KiB Raw Blame History