test: add gloss orchestration core test suite (red phase)

Two test files for the orchestration core. All 13 tests fail at this
commit because the implementation is still stubbed.

`gloss--orchestrate-fetch-result' gets full N/B/E coverage on the
decision matrix: single def, multi def, the >1 boundary, empty defs
with each combination of :no-defs and :failed populated, and the
all-empty degenerate case.

`gloss--lookup-flow' covers cache hit (no fetch), cache miss with one
def (auto-save), cache miss with multiple (picker), cancelled picker
(no save), no-defs error, and the force-fetch override that bypasses
the cache. Mocks live at network and UI boundaries; persistence runs
against a real temp glossary so the save side effect is validated.

2 files changed, 176 insertions, 0 deletions

diff --git a/tests/test-gloss--lookup-flow.el b/tests/test-gloss--lookup-flow.el
new file mode 100644
index 0000000..3b5ee40
--- /dev/null
+++ b/tests/test-gloss--lookup-flow.el
@@ -0,0 +1,109 @@
+;;; test-gloss--lookup-flow.el --- Tests for gloss--lookup-flow -*- lexical-binding: t -*-
+
+;; SPDX-License-Identifier: GPL-3.0-or-later
+
+;;; Commentary:
+;; Tests for the internal `gloss--lookup-flow' that orchestrates
+;; cache lookup, online fetch, picker, and persistence.
+;;
+;; Mocks are at the boundaries: `gloss-fetch-definitions' (network
+;; call), `gloss-display-show-entry' / `gloss-display-pick-definition'
+;; (UI side effects).  Persistence (`gloss-core-save') is exercised
+;; against a real temp glossary so the save side effect is validated
+;; end-to-end.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+(require 'gloss)
+(require 'testutil-gloss)
+
+(ert-deftest test-gloss-lookup-flow-cache-hit-shows-cached-and-skips-fetch ()
+  "Normal: cache hit shows the cached body, never fetches, returns :show."
+  (gloss-test--with-temp-glossary gloss-test--sample-content
+    (let (shown)
+      (cl-letf (((symbol-function 'gloss-fetch-definitions)
+                 (lambda (&rest _) (error "fetch must not be called on cache hit")))
+                ((symbol-function 'gloss-display-show-entry)
+                 (lambda (term body) (setq shown (list term body)))))
+        (should (eq (gloss--lookup-flow "anaphora") :show))
+        (should (equal (car shown) "anaphora"))
+        (should (string-match-p "Reference to something earlier"
+                                (cadr shown)))))))
+
+(ert-deftest test-gloss-lookup-flow-cache-miss-single-def-auto-saves ()
+  "Normal: cache miss + 1 def auto-saves, shows entry, returns :auto-save."
+  (gloss-test--with-missing-glossary
+    (let* ((def '(:source wiktionary :text "The lone definition."))
+           (result (list :defs (list def) :no-defs nil :failed nil)))
+      (cl-letf (((symbol-function 'gloss-fetch-definitions)
+                 (lambda (_) result))
+                ((symbol-function 'gloss-display-show-entry)
+                 (lambda (_ _) nil)))
+        (should (eq (gloss--lookup-flow "newterm") :auto-save))
+        (let ((saved (gloss-core-lookup "newterm")))
+          (should saved)
+          (should (equal (plist-get saved :body) "The lone definition."))
+          (should (eq (plist-get saved :source) 'wiktionary)))))))
+
+(ert-deftest test-gloss-lookup-flow-cache-miss-multi-def-picks-and-saves ()
+  "Normal: cache miss + multi-def calls picker, saves chosen, returns :pick."
+  (gloss-test--with-missing-glossary
+    (let* ((d1 '(:source wiktionary :text "First sense."))
+           (d2 '(:source wiktionary :text "Second sense."))
+           (result (list :defs (list d1 d2) :no-defs nil :failed nil)))
+      (cl-letf (((symbol-function 'gloss-fetch-definitions)
+                 (lambda (_) result))
+                ((symbol-function 'gloss-display-pick-definition)
+                 (lambda (_term _defs) d2))
+                ((symbol-function 'gloss-display-show-entry)
+                 (lambda (_ _) nil)))
+        (should (eq (gloss--lookup-flow "API") :pick))
+        (let ((saved (gloss-core-lookup "API")))
+          (should saved)
+          (should (equal (plist-get saved :body) "Second sense.")))))))
+
+(ert-deftest test-gloss-lookup-flow-multi-def-cancelled-leaves-no-save ()
+  "Boundary: cancelled picker (returns nil) leaves no save, still returns :pick."
+  (gloss-test--with-missing-glossary
+    (let* ((d1 '(:source wiktionary :text "A."))
+           (d2 '(:source wiktionary :text "B."))
+           (result (list :defs (list d1 d2) :no-defs nil :failed nil))
+           (show-called nil))
+      (cl-letf (((symbol-function 'gloss-fetch-definitions)
+                 (lambda (_) result))
+                ((symbol-function 'gloss-display-pick-definition)
+                 (lambda (_term _defs) nil))
+                ((symbol-function 'gloss-display-show-entry)
+                 (lambda (_ _) (setq show-called t))))
+        (should (eq (gloss--lookup-flow "X") :pick))
+        (should-not show-called)
+        (should-not (gloss-core-lookup "X"))))))
+
+(ert-deftest test-gloss-lookup-flow-no-defs-returns-error-no-defs ()
+  "Error: cache miss + empty result + only :no-defs returns :error-no-defs."
+  (gloss-test--with-missing-glossary
+    (cl-letf (((symbol-function 'gloss-fetch-definitions)
+               (lambda (_)
+                 (list :defs nil :no-defs '(wiktionary) :failed nil))))
+      (should (eq (gloss--lookup-flow "X") :error-no-defs))
+      (should-not (gloss-core-lookup "X")))))
+
+(ert-deftest test-gloss-lookup-flow-force-fetch-bypasses-cache ()
+  "Normal: force-fetch arg t skips cache hit and fetches, replacing entry."
+  (gloss-test--with-temp-glossary gloss-test--sample-content
+    (let* ((fresh '(:source wiktionary :text "Replacement body."))
+           (result (list :defs (list fresh) :no-defs nil :failed nil))
+           (fetch-called nil))
+      (cl-letf (((symbol-function 'gloss-fetch-definitions)
+                 (lambda (_) (setq fetch-called t) result))
+                ((symbol-function 'gloss-display-show-entry)
+                 (lambda (_ _) nil)))
+        (should (eq (gloss--lookup-flow "anaphora" t) :auto-save))
+        (should fetch-called)
+        (let ((entry (gloss-core-lookup "anaphora")))
+          (should (equal (plist-get entry :body) "Replacement body.")))))))
+
+(provide 'test-gloss--lookup-flow)
+;;; test-gloss--lookup-flow.el ends here
diff --git a/tests/test-gloss--orchestrate-fetch-result.el b/tests/test-gloss--orchestrate-fetch-result.el
new file mode 100644
index 0000000..b4a4cf8
--- /dev/null
+++ b/tests/test-gloss--orchestrate-fetch-result.el
@@ -0,0 +1,67 @@
+;;; test-gloss--orchestrate-fetch-result.el --- Tests for gloss--orchestrate-fetch-result -*- lexical-binding: t -*-
+
+;; SPDX-License-Identifier: GPL-3.0-or-later
+
+;;; Commentary:
+;; Tests for the pure pattern-matcher `gloss--orchestrate-fetch-result'.
+;; It maps a `gloss-fetch-definitions' result plist to a decision
+;; symbol that the lookup flow then dispatches on.  Full N/B/E
+;; coverage on the full decision matrix.
+
+;;; Code:
+
+(require 'ert)
+(require 'gloss)
+
+(ert-deftest test-gloss-orchestrate-fetch-result-single-def-returns-auto-save ()
+  "Normal: exactly one definition returns :auto-save."
+  (let ((result '(:defs ((:source wiktionary :text "Only sense."))
+                  :no-defs nil
+                  :failed nil)))
+    (should (eq (gloss--orchestrate-fetch-result result) :auto-save))))
+
+(ert-deftest test-gloss-orchestrate-fetch-result-multi-def-returns-pick ()
+  "Normal: more than one definition returns :pick."
+  (let ((result '(:defs ((:source wiktionary :text "First.")
+                         (:source wiktionary :text "Second.")
+                         (:source wiktionary :text "Third."))
+                  :no-defs nil
+                  :failed nil)))
+    (should (eq (gloss--orchestrate-fetch-result result) :pick))))
+
+(ert-deftest test-gloss-orchestrate-fetch-result-two-defs-returns-pick ()
+  "Boundary: exactly two definitions returns :pick (above the >1 threshold)."
+  (let ((result '(:defs ((:source wiktionary :text "A.")
+                         (:source wiktionary :text "B."))
+                  :no-defs nil
+                  :failed nil)))
+    (should (eq (gloss--orchestrate-fetch-result result) :pick))))
+
+(ert-deftest test-gloss-orchestrate-fetch-result-only-no-defs-returns-error-no-defs ()
+  "Boundary: no defs and only :no-defs sources returns :error-no-defs."
+  (let ((result '(:defs nil
+                  :no-defs (wiktionary)
+                  :failed nil)))
+    (should (eq (gloss--orchestrate-fetch-result result) :error-no-defs))))
+
+(ert-deftest test-gloss-orchestrate-fetch-result-only-failed-returns-error-failed ()
+  "Boundary: no defs and only :failed sources returns :error-failed."
+  (let ((result '(:defs nil
+                  :no-defs nil
+                  :failed (wiktionary))))
+    (should (eq (gloss--orchestrate-fetch-result result) :error-failed))))
+
+(ert-deftest test-gloss-orchestrate-fetch-result-mixed-no-defs-and-failed-returns-error-mixed ()
+  "Boundary: no defs but BOTH :no-defs and :failed populated returns :error-mixed."
+  (let ((result '(:defs nil
+                  :no-defs (wiktionary)
+                  :failed (dictionary-api))))
+    (should (eq (gloss--orchestrate-fetch-result result) :error-mixed))))
+
+(ert-deftest test-gloss-orchestrate-fetch-result-all-empty-returns-error-no-defs ()
+  "Error: degenerate result with all three keys empty returns :error-no-defs."
+  (let ((result '(:defs nil :no-defs nil :failed nil)))
+    (should (eq (gloss--orchestrate-fetch-result result) :error-no-defs))))
+
+(provide 'test-gloss--orchestrate-fetch-result)
+;;; test-gloss--orchestrate-fetch-result.el ends here