refactor: switch gloss-fetch result to uniform plist shapeHEADmain

The previous shape (:ok DEFS) | (:empty :no-defs (...) :failed (...)) was malformed as a plist. The :empty tag at position 0 shifted the plist alignment. plist-get on :no-defs or :failed returned nil. Tests had to use (plist-get (cdr result) ...) as a workaround.

The new shape is a uniform plist with all three keys always present: (:defs DEFS :no-defs (SYM ...) :failed (SYM ...)). Consumers branch on whether :defs is non-empty. There is no tag. plist-get works uniformly across success and empty cases.

Updated gloss-fetch.el (rollup function and docstrings), 7 test files, and the design doc (docs/design/gloss.org § Error Handling).

Tested by `make test`. 65 tests pass in 0.36 seconds.

9 files changed, 68 insertions, 63 deletions

diff --git a/docs/design/gloss.org b/docs/design/gloss.org
index 04efc38..649eb24 100644
--- a/docs/design/gloss.org
+++ b/docs/design/gloss.org
@@ -183,21 +183,22 @@ After =gloss-drill-export-all=, the heading line gains a =:drill:= tag and the p
 
 *=:reason= strings* carry the technical detail (=timeout (5s)=, =HTTP 503=, =malformed JSON: ...=) and land in =*gloss-debug*=. They are never user-facing.
 
-*User-facing rollup.* =gloss-fetch-definitions= aggregates per-source results into:
+*User-facing rollup.* =gloss-fetch-definitions= returns a uniform plist with three keys, all always present:
 
 #+begin_src emacs-lisp
-(:ok DEFS)                                       ;; any source returned >=1 def
-(:empty :no-defs (...) :failed (...))            ;; everything else
+(:defs DEFS                       ;; possibly-empty list of definition plists
+ :no-defs (SYM ...)               ;; sources reached but returning no defs
+ :failed (SYM ...))               ;; sources that could not be reached
 #+end_src
 
-=:failed= unions =:unreachable=, =:server-error=, =:rate-limited=.
+=:failed= unions =:unreachable=, =:server-error=, =:rate-limited=. Consumers branch on whether =(plist-get result :defs)= is non-empty.
 
 | Result shape                              | Message                                                            |
 |-------------------------------------------+--------------------------------------------------------------------|
-| Every source =:no-defs=, none failed      | "No definition for X in Wiktionary."                               |
-| Every source failed, none =:no-defs=      | "Couldn't reach Wiktionary."                                       |
-| Mix of =:no-defs= and failures            | "No definition in Wiktionary; couldn't reach DictionaryAPI."       |
-| Any =:ok= with defs                       | Silent on others — picker shows what came back                     |
+| =:defs= empty, only =:no-defs= populated  | "No definition for X in Wiktionary."                               |
+| =:defs= empty, only =:failed= populated   | "Couldn't reach Wiktionary."                                       |
+| =:defs= empty, both populated             | "No definition in Wiktionary; couldn't reach DictionaryAPI."       |
+| =:defs= non-empty                         | Silent on others — picker shows what came back                     |
 
 When v2 starts surfacing =:rate-limited= regularly, the rollup wording will gain a third visible category. v1 with no-key Wiktionary doesn't need it.
 
diff --git a/gloss-fetch.el b/gloss-fetch.el
index a5aa84d..d48e4db 100644
--- a/gloss-fetch.el
+++ b/gloss-fetch.el
@@ -13,8 +13,8 @@
 ;;
 ;; Public API:
 ;;   `gloss-fetch-definitions' TERM
-;;     -> (:ok DEFS)                                ; any source returned >=1 def
-;;        | (:empty :no-defs (SYM ...) :failed (SYM ...))
+;;     -> (:defs DEFS :no-defs (SYM ...) :failed (SYM ...))
+;;        ; uniform plist; success = DEFS non-empty.
 ;;
 ;; Each definition is a plist:
 ;;   (:source SYM :text "Reference to ...")
@@ -254,32 +254,36 @@ in `gloss-fetch--sources' are silently skipped."
     (nreverse results)))
 
 (defun gloss-fetch--rollup (per-source)
-  "Roll up PER-SOURCE results into the user-facing response shape.
-Returns (:ok DEFS) when any source returned :ok with non-empty :defs.
-Otherwise returns (:empty :no-defs (...) :failed (...))."
-  (let (ok-defs no-defs failed)
+  "Roll up PER-SOURCE results into the user-facing response plist.
+Always returns (:defs DEFS :no-defs (SYM ...) :failed (SYM ...)) with
+all three keys present.  DEFS is a (possibly empty) list of definition
+plists.  :no-defs lists sources that were reached but returned no
+definitions.  :failed lists sources that could not be reached.
+Consumers branch on whether DEFS is non-empty."
+  (let (defs no-defs failed)
     (dolist (entry per-source)
       (let ((sym (plist-get entry :source))
             (status (plist-get entry :status)))
         (cond
          ((and (eq status :ok) (plist-get entry :defs))
-          (setq ok-defs (append ok-defs (plist-get entry :defs))))
+          (setq defs (append defs (plist-get entry :defs))))
          ((eq status :no-defs)
           (push sym no-defs))
          ((memq status '(:unreachable :server-error :rate-limited))
           (push sym failed)))))
-    (if ok-defs
-        (list :ok ok-defs)
-      (list :empty
-            :no-defs (nreverse no-defs)
-            :failed (nreverse failed)))))
+    (list :defs defs
+          :no-defs (nreverse no-defs)
+          :failed (nreverse failed))))
 
 (defun gloss-fetch-definitions (term)
   "Fetch candidate definitions for TERM from each source in `gloss-fetch-sources'.
-Returns (:ok DEFS) when any source returns at least one definition,
-otherwise (:empty :no-defs (SYM ...) :failed (SYM ...)).  Signals
-`user-error' the first time it runs in a session without libxml, and
-on every subsequent call in that session."
+Returns a plist with three keys, all always present:
+  :defs    — list of definition plists, possibly empty.
+  :no-defs — list of sources reached but returning no definitions.
+  :failed  — list of sources that could not be reached.
+Consumers branch on whether `(plist-get result :defs)' is non-empty.
+Signals `user-error' the first time it runs in a session without libxml,
+and on every subsequent call in that session."
   (gloss-fetch--ensure-libxml)
   (gloss-fetch--rollup (gloss-fetch--collect term)))
 
diff --git a/tests/test-gloss-fetch--definitions-200-returns-ok.el b/tests/test-gloss-fetch--definitions-200-returns-ok.el
index fee997b..7ac34b9 100644
--- a/tests/test-gloss-fetch--definitions-200-returns-ok.el
+++ b/tests/test-gloss-fetch--definitions-200-returns-ok.el
@@ -4,7 +4,7 @@
 
 ;;; Commentary:
 ;; Normal/Boundary cases: a 200 response with valid JSON returns
-;; (:ok DEFS) and each def is a plist with :source and :text.  Uses the
+;; non-empty :defs in the rollup, and each def is a plist with :source and :text.  Uses the
 ;; captured Wiktionary fixtures replayed through a mocked
 ;; `url-retrieve-synchronously'.
 
@@ -17,13 +17,13 @@
 (require 'testutil-gloss-fetch)
 
 (ert-deftest test-gloss-fetch-definitions-200-anaphora-returns-ok ()
-  "Normal: anaphora fixture (single English sense) returns (:ok DEFS)."
+  "Normal: anaphora fixture (single English sense) returns non-empty :defs."
   (let ((body (gloss-test--load-wiktionary-fixture "anaphora")))
     (gloss-fetch-test--with-mocked-url
         (lambda (_url) (gloss-fetch-test--ok-response body))
       (let* ((result (gloss-fetch-definitions "anaphora"))
-             (defs (plist-get result :ok)))
-        (should (eq (car result) :ok))
+             (defs (plist-get result :defs)))
+        (should (plist-get result :defs))
         (should (consp defs))
         (should (>= (length defs) 1))
         (let ((first (car defs)))
@@ -39,8 +39,8 @@
     (gloss-fetch-test--with-mocked-url
         (lambda (_url) (gloss-fetch-test--ok-response body))
       (let* ((result (gloss-fetch-definitions "SBIR"))
-             (defs (plist-get result :ok)))
-        (should (eq (car result) :ok))
+             (defs (plist-get result :defs)))
+        (should (plist-get result :defs))
         (should (>= (length defs) 1))
         (dolist (d defs)
           (should (eq (plist-get d :source) 'wiktionary))
diff --git a/tests/test-gloss-fetch--definitions-404-returns-no-defs.el b/tests/test-gloss-fetch--definitions-404-returns-no-defs.el
index 28587ac..1700e79 100644
--- a/tests/test-gloss-fetch--definitions-404-returns-no-defs.el
+++ b/tests/test-gloss-fetch--definitions-404-returns-no-defs.el
@@ -15,24 +15,24 @@
 (require 'testutil-gloss-fetch)
 
 (ert-deftest test-gloss-fetch-definitions-404-rolls-up-to-empty-no-defs ()
-  "Normal: a 404 from the only source rolls up to (:empty :no-defs (wiktionary) :failed nil)."
+  "Normal: a 404 from the only source rolls up with :no-defs = (wiktionary), :failed and :defs = nil."
   (gloss-fetch-test--with-mocked-url
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 404 Not Found"
                                            "{\"detail\":\"Page not found\"}"))
     (let ((result (gloss-fetch-definitions "asdf-not-a-word")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :no-defs)))
-      (should-not (plist-get (cdr result) :failed)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :no-defs)))
+      (should-not (plist-get result :failed)))))
 
 (ert-deftest test-gloss-fetch-definitions-200-empty-rolls-up-to-empty-no-defs ()
   "Boundary: a 200 with an empty JSON object also maps to :no-defs."
   (gloss-fetch-test--with-mocked-url
       (lambda (_url) (gloss-fetch-test--ok-response "{}"))
     (let ((result (gloss-fetch-definitions "term")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :no-defs)))
-      (should-not (plist-get (cdr result) :failed)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :no-defs)))
+      (should-not (plist-get result :failed)))))
 
 (ert-deftest test-gloss-fetch-definitions-200-no-english-rolls-up-to-no-defs ()
   "Boundary: a 200 response with only non-English keys maps to :no-defs."
@@ -41,8 +41,8 @@
     (gloss-fetch-test--with-mocked-url
         (lambda (_url) (gloss-fetch-test--ok-response body))
       (let ((result (gloss-fetch-definitions "term")))
-        (should (eq (car result) :empty))
-        (should (member 'wiktionary (plist-get (cdr result) :no-defs)))))))
+        (should-not (plist-get result :defs))
+        (should (member 'wiktionary (plist-get result :no-defs)))))))
 
 (provide 'test-gloss-fetch--definitions-404-returns-no-defs)
 ;;; test-gloss-fetch--definitions-404-returns-no-defs.el ends here
diff --git a/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el b/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el
index cd2d2d4..84e6f49 100644
--- a/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el
+++ b/tests/test-gloss-fetch--definitions-429-returns-rate-limited.el
@@ -20,9 +20,9 @@
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 429 Too Many Requests" ""))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed)))
-      (should-not (plist-get (cdr result) :no-defs)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed)))
+      (should-not (plist-get result :no-defs)))))
 
 (ert-deftest test-gloss-fetch-definitions-429-tracked-separately-internally ()
   "Boundary: per-source status taxonomy distinguishes :rate-limited from :server-error.
diff --git a/tests/test-gloss-fetch--definitions-500-returns-server-error.el b/tests/test-gloss-fetch--definitions-500-returns-server-error.el
index 20e988b..54664f3 100644
--- a/tests/test-gloss-fetch--definitions-500-returns-server-error.el
+++ b/tests/test-gloss-fetch--definitions-500-returns-server-error.el
@@ -21,9 +21,9 @@
         (gloss-fetch-test--status-response "HTTP/1.1 500 Internal Server Error"
                                            "Server is sad."))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed)))
-      (should-not (plist-get (cdr result) :no-defs)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed)))
+      (should-not (plist-get result :no-defs)))))
 
 (ert-deftest test-gloss-fetch-definitions-503-rolls-up-to-failed ()
   "Normal: HTTP 503 maps the source to :server-error (in :failed)."
@@ -31,16 +31,16 @@
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 503 Service Unavailable" ""))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed))))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed))))))
 
 (ert-deftest test-gloss-fetch-definitions-malformed-json-rolls-up-to-failed ()
   "Boundary: a 200 with non-JSON body also maps to :server-error."
   (gloss-fetch-test--with-mocked-url
       (lambda (_url) (gloss-fetch-test--ok-response "<html>not json</html>"))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed))))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed))))))
 
 (ert-deftest test-gloss-fetch-definitions-400-rolls-up-to-failed ()
   "Error: HTTP 400 (4xx other than 404/429) maps to :server-error (in :failed)."
@@ -48,8 +48,8 @@
       (lambda (_url)
         (gloss-fetch-test--status-response "HTTP/1.1 400 Bad Request" ""))
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed))))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed))))))
 
 (provide 'test-gloss-fetch--definitions-500-returns-server-error)
 ;;; test-gloss-fetch--definitions-500-returns-server-error.el ends here
diff --git a/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el b/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el
index 8067dde..8bd0019 100644
--- a/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el
+++ b/tests/test-gloss-fetch--definitions-timeout-returns-unreachable.el
@@ -19,9 +19,9 @@
   (gloss-fetch-test--with-mocked-url
       (lambda (_url) nil)
     (let ((result (gloss-fetch-definitions "anaphora")))
-      (should (eq (car result) :empty))
-      (should (member 'wiktionary (plist-get (cdr result) :failed)))
-      (should-not (plist-get (cdr result) :no-defs)))))
+      (should-not (plist-get result :defs))
+      (should (member 'wiktionary (plist-get result :failed)))
+      (should-not (plist-get result :no-defs)))))
 
 (ert-deftest test-gloss-fetch-definitions-timeout-marks-source-unreachable ()
   "Boundary: per-source status is :unreachable, distinct from :server-error."
diff --git a/tests/test-gloss-fetch--libxml-probe.el b/tests/test-gloss-fetch--libxml-probe.el
index 758c185..1d8b7ed 100644
--- a/tests/test-gloss-fetch--libxml-probe.el
+++ b/tests/test-gloss-fetch--libxml-probe.el
@@ -57,8 +57,8 @@
       (gloss-fetch-test--with-mocked-url
           (lambda (_url) (gloss-fetch-test--ok-response "{}"))
         (let ((result (gloss-fetch-definitions "term")))
-          (should (eq (car result) :empty))
-          (should (member 'wiktionary (plist-get (cdr result) :no-defs))))))))
+          (should-not (plist-get result :defs))
+          (should (member 'wiktionary (plist-get result :no-defs))))))))
 
 (provide 'test-gloss-fetch--libxml-probe)
 ;;; test-gloss-fetch--libxml-probe.el ends here
diff --git a/tests/test-gloss-fetch--multi-source-walks-registry.el b/tests/test-gloss-fetch--multi-source-walks-registry.el
index cb2b730..482cc40 100644
--- a/tests/test-gloss-fetch--multi-source-walks-registry.el
+++ b/tests/test-gloss-fetch--multi-source-walks-registry.el
@@ -42,12 +42,12 @@
                        (list :source 'beta :status :server-error :reason "HTTP 503")))))
          (gloss-fetch-sources '(alpha beta))
          (result (gloss-fetch-definitions "x")))
-    (should (eq (car result) :empty))
-    (should (member 'alpha (plist-get (cdr result) :no-defs)))
-    (should (member 'beta (plist-get (cdr result) :failed)))))
+    (should-not (plist-get result :defs))
+    (should (member 'alpha (plist-get result :no-defs)))
+    (should (member 'beta (plist-get result :failed)))))
 
 (ert-deftest test-gloss-fetch-rollup-any-ok-yields-ok ()
-  "Boundary: if any source returns :ok with defs, the rollup is (:ok DEFS)."
+  "Boundary: if any source returns :ok with defs, the rollup has non-empty :defs."
   (let* ((gloss-fetch--sources
           `((alpha . ,(lambda (_term)
                         (list :source 'alpha :status :no-defs :reason "404")))
@@ -56,9 +56,9 @@
                              (list (list :source 'beta :text "got it")))))))
          (gloss-fetch-sources '(alpha beta))
          (result (gloss-fetch-definitions "x")))
-    (should (eq (car result) :ok))
-    (should (= 1 (length (plist-get result :ok))))
-    (should (equal "got it" (plist-get (car (plist-get result :ok)) :text)))))
+    (should (plist-get result :defs))
+    (should (= 1 (length (plist-get result :defs))))
+    (should (equal "got it" (plist-get (car (plist-get result :defs)) :text)))))
 
 (ert-deftest test-gloss-fetch-collect-skips-source-not-in-defcustom ()
   "Error: a source registered in `gloss-fetch--sources' but not in `gloss-fetch-sources' is skipped."