Brummel
a29700cc9e
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.
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# iter effect-doc-honesty — effect-system documentation-honesty tidy
|
|
|
|
**Date:** 2026-05-16
|
|
**Started from:** c41e0e5a9e48fd0099eda8c286f10ec7a30e8e8a
|
|
**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
|