diff --git a/AGENTS.md b/AGENTS.md index ba4f51a..d3f2ade 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,50 @@ Working conventions for this repo, learned from the maintainer (Dennis K. Paulsden) over prior sessions. This is about *how* to work here, not *what the code does* — read the source and `docs/` for that. +## Resolve the issue; a note about it is not a resolution + +**The default response to a defect is to fix its cause.** Not to describe +it, not to route around it, not to pin it as a known gap. If you find +yourself reaching for prose where a fix belongs, that is the signal to stop +and go fix it. + +None of these count as resolving anything: a paragraph in `CHANGELOG.md` or +a docstring saying the thing is broken; a comment explaining the symptom; a +retry loop, a widened timeout or tolerance; an `except` that turns a failure +into a pass; a skipped or loosened test, or an assertion weakened to match +what the code does today. + +**Two shapes this takes here.** A test that fails only against the libei +version CI pins is a *compatibility* bug in this binding — fix the binding, +or guard on the capability rather than on the version, and never skip the +test to make the run green; the older version is as real as the newer one, +and reproducing it locally needs no box (see the extracted-debs recipe). And +a fix must not rest on an unverified premise about what the C library does: +check the behaviour — a `GError` that is or is not set, an fd list that is +or is not empty — against the library itself before building a guard on top +of your reading of it. A guard for a condition that never occurs is worse +than none: it looks like the bug is handled. + +**Phrases to treat as alarms in your own output.** "Left open and +characterised", "reported rather than changed", "recorded here rather than +fixed", "awaits a future round", "documented upstream", "out of scope for +this change", "pre-existing, so not mine". When one appears, either fix the +thing or ask. + +**Diagnose to the cause, not the symptom.** Keep going until you can say +*why*, then fix that. A nondeterministic result is a race to find, not a +flake to retry around. + +**The only acceptable reasons to leave something unfixed**, and both end in +asking rather than writing: the fix is the maintainer's call, because it +changes this binding's public API or how it presents a protocol object; or +you are genuinely blocked — the cause is upstream in libei or in a +compositor, and then the resolution is a reduced reproducer and a report +there, not a note here. + +**Documentation's job is to record a resolved thing** — the measurement +that proves the fix. + ## Git workflow - **AI will never commit.** Never run `git commit` (or `git add` in diff --git a/README.md b/README.md index 2aa3eea..63eef04 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,39 @@ asserted. Exactly what was run, when, and against which versions: [docs/developers/verification.md](docs/developers/verification.md). +### What the API raises + +Three independent exception families, by the layer that raises them, so a +caller can catch at the granularity they need — plus one that sits before +all of them: + +- **`LibraryNotFoundError`** (a `RuntimeError`, exported by `libei.ei`, + `libei.eis` and `libei.oeffis` alike) — the native library could not be + loaded. Importing never raises it; the first call that needs the library + does, and every later call after that. `is_available()` asks the same + question without raising. +- **`libei.ei.Error`** (and `libei.eis.Error`) — the native library reported + a failure through its own return codes. One base class per module; + subclasses are added as distinct failure modes earn them rather than up + front. +- **`libei.oeffis.DisconnectedError`**, with `SessionClosedError` under it — + the EIS connection is gone. `dispatch()` raises the subclass when the + portal closed the session and the base class when the connection dropped + or the fd could not be obtained; `eis_fd` raises the base class whenever + no connection is up yet, so it is `dispatch()` that tells the two apart. +- **`libei.portal.PortalError`**, with `PortalVersionError`, + `PortalTimeoutError`, `PortalDeniedError`, `PortalProtocolError` and + `PortalSessionClosedError` under it — each a *different* thing the portal + round trip can do, kept separate on purpose: a timeout (no answer), a + denial (answered no), a protocol surprise (answered malformed) and a + version mismatch are not interchangeable, and collapsing them would make a + caller guess. These are the ones worth catching individually. + +Argument mistakes that are the caller's and not the desktop's — +no capabilities, the wrong value kind — raise the stock `ValueError` / +`TypeError`, never a library exception. The hierarchy is stable in shape; as +with the rest of the API, names may still change before 1.0. + ## Alternatives | Instead of this | Why you might |