docs(affine): capture the AffineScript interface constraints durably

[hyperpolymath]

Summary

The three AffineScript compiler constraints that shaped src/ui/tea/*.affine (#64) only existed as a line in a STATE.a2ml session-log entry. This PR lifts them into discoverable source docs and adds an in-context guardrail, so a future contributor doesn't rediscover them the hard way or try to "simplify" code that is the way it is on purpose.

This is the follow-up cleanup I flagged after closing out the completion roadmap. It is docs/comments only — the .affine logic is unchanged.

Changes

• src/ui/tea/README.adoc (new) — what the TEA interface is (pure init/update/view/subs core + the cmd_* / IO effect layer), how to typecheck it (module resolution is cwd-relative → just affine-check from src/ui/tea), the symbol-contract guard (just affine-contract / affine-ffi-contract-check.sh, also in CI), and the three language constraints with rationale.
• gsa_gui.affine — an in-context "AffineScript constraints (read before editing)" header block: handle is reserved (use server_handle); record-spread does not typecheck on nominal structs, so every update arm restating all 13 Model fields is deliberate, not oversight — do not DRY it with a spread; module resolution is cwd-relative.
• gsa_ffi.affine — a one-line pointer to the server_handle naming convention and the README.

Why no code refactor

The obvious "cleanup" would be with* updater helpers to collapse the ~15 longhand update arms. I deliberately did not do that: AffineScript has no compiler in this environment and CI only checks the FFI symbol contract, not a typecheck, so the files currently compile but a refactor could not be verified here — a bad trade against working code. The docs instead make the constraint explicit and point the next editor (who can run just affine-check) at where a real refactor would belong if the compiler ever gains record spread.

RSR Quality Checklist

Required

• No banned language patterns / functions
• SPDX headers present (CC-BY-SA-4.0 on the new doc; existing AGPL headers on the .affine files unchanged)
• No secrets/credentials included

As Applicable

• Documentation updated (this PR is documentation)
• Verified: just affine-check / affine-contract recipes exist and affine-contract is wired into just quality; Model has exactly the 13 fields the docs cite

Testing

Docs/comments only — no build or test surface changes. Facts were verified against the repo: the two just recipes exist, affine-contract is part of just quality, and the Model field count (13) matches the text. The .affine sources' logic is byte-for-byte unchanged apart from added comment lines.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TaWWedv6VQqeZaPvc94keN

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud