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.
This commit is contained in:
2026-05-16 13:25:49 +02:00
parent c41e0e5a9e
commit a29700cc9e
8 changed files with 179 additions and 11 deletions
+3 -3
View File
@@ -285,9 +285,9 @@ details unless the prose explicitly contradicts them. Specifically:
These are hard contracts (memory model). The prose shows them
as `own T` / `borrow T`; the Form-A wraps them. If the prose is
ambiguous, default to the original.
- Effect annotations on return types (`(effects IO)`,
`(effects Diverge)`). Prose shows these as `with IO` etc.; if
uncertain, keep what the original had.
- Effect annotations on return types (e.g. `(effects IO)`).
Prose shows these as `with IO` etc.; if uncertain, keep what
the original had.
- `tail` flags on calls. The prose prints `tail f(x)`; the Form-A
keyword is `(tail-app f x)`. If the edit moved a call, decide
whether the new position is still in tail position.