Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
33 changes: 33 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Loading