feat(agenda): add the renderer output profile and its cache file

The surface that reads this went live, and it reads a different shape than
the canonical profile emits.

- cj/agenda-render-json adds s and e in epoch milliseconds, plus t for the
  title. The canonical fields ride along, so one file serves both readers.
- Every row gets an end it can be drawn with. An all-day entry spans its
  day. A point event has zero width. The canonical profile still reports
  null there, which is faithful to the source but not a width.
- cj/agenda-render-cache-update writes today to the XDG cache path.

Input stays epoch seconds on both profiles. Only the output converts, and
the guards that catch a milliseconds-for-seconds caller still apply.

Nothing schedules the cache write yet, so the file is only as fresh as its
last call. Picking a refresh mechanism is its own decision.

2 files changed, 337 insertions, 6 deletions

diff --git a/modules/agenda-query.el b/modules/agenda-query.el
index a411c89b..5a185076 100644
--- a/modules/agenda-query.el
+++ b/modules/agenda-query.el
@@ -14,8 +14,15 @@
 ;; Direct test load: yes.
 ;;
 ;; Answers "what is on the agenda between these two instants" as JSON, so a
-;; renderer running outside Emacs can draw it.  `cj/agenda-window-json' is the
-;; entry point; it reads `org-agenda-files' and leaves every buffer unmodified.
+;; renderer running outside Emacs can draw it.  Both entry points read
+;; `org-agenda-files' and leave every buffer unmodified.
+;;
+;; Two output profiles over one query.  `cj/agenda-window-json' is canonical:
+;; epoch seconds, descriptive field names, and a null end where the source has
+;; no range.  `cj/agenda-render-json' adds what the wallpaper renderer reads --
+;; s and e in epoch MILLISECONDS, t for the title, and an end every row can
+;; actually be drawn with.  `cj/agenda-render-cache-update' writes that profile
+;; for today to `cj/agenda-render-cache-file'.
 ;;
 ;; Epoch seconds at the boundary is the load-bearing interface choice.  It takes
 ;; timezone out of the contract entirely: the consumer does its own zoneinfo
@@ -416,6 +423,36 @@ counted twice."
                 (string< (alist-get 'title a) (alist-get 'title b))
               (< sa sb))))))
 
+(defun cj/--agenda-query-drawable-end (event)
+  "Return EVENT's end as something a renderer can draw, in epoch seconds.
+
+The canonical row reports a null end when the source has no range, which is
+faithful but not drawable.  Here an all-day entry's extent is its whole day and
+a timed point event's is the instant itself, so every row has a width -- even
+if that width is zero.  Derived from the row, so this stays a pure function of
+canonical output."
+  (let ((start (alist-get 'start event))
+        (end (alist-get 'end event)))
+    (cond
+     ((integerp end) end)
+     ((eq t (alist-get 'all-day event))
+      (let ((d (decode-time start)))
+        (cj/--agenda-query-day-close (nth 3 d) (nth 4 d) (nth 5 d))))
+     (t start))))
+
+(defun cj/--agenda-query-render-row (event)
+  "Return EVENT in the renderer's contract, adding s, e and t.
+
+The renderer reads s and e as epoch MILLISECONDS and t as the title; it takes
+everything else and drops it before drawing.  The canonical fields are kept
+alongside rather than replaced, so one file serves both the renderer and any
+consumer reading the documented shape.  Milliseconds live only in s and e --
+`start' and `end' stay seconds, and the two never mix within a key."
+  (append (list (cons 's (* 1000 (alist-get 'start event)))
+                (cons 'e (* 1000 (cj/--agenda-query-drawable-end event)))
+                (cons 't (alist-get 'title event)))
+          event))
+
 (defun cj/--agenda-query-write-atomically (path text)
   "Write TEXT to PATH through a temp file and a rename, returning PATH.
 
@@ -465,6 +502,15 @@ Signals when either bound falls outside 1900-2200, or when the window is wider
 than `cj/agenda-query-max-window-seconds'.  Both checks exist to surface a
 milliseconds-for-seconds mistake, which otherwise answers with dates in the
 year 58549 or builds millions of rows."
+  (let ((json (json-serialize
+               (vconcat (cj/--agenda-query-events start-epoch end-epoch)))))
+    (when out-path
+      (cj/--agenda-query-write-atomically out-path json))
+    json))
+
+(defun cj/--agenda-query-events (start-epoch end-epoch)
+  "Return the sorted event rows between START-EPOCH and END-EPOCH.
+Shared by both output profiles; the callers do their own writing."
   (unless (numberp start-epoch)
     (signal 'wrong-type-argument (list 'numberp start-epoch)))
   (unless (numberp end-epoch)
@@ -492,10 +538,60 @@ year 58549 or builds millions of rows."
                     (nconc events
                            (cj/--agenda-query-buffer-events
                             buffer file win-start win-end))))))))
-    (let ((json (json-serialize (vconcat (cj/--agenda-query-sort events)))))
-      (when out-path
-        (cj/--agenda-query-write-atomically out-path json))
-      json)))
+    (cj/--agenda-query-sort events)))
+
+(defconst cj/agenda-render-cache-file
+  (expand-file-name
+   "settings/agenda.json"
+   (let ((xdg (getenv "XDG_CACHE_HOME")))
+     ;; An empty XDG_CACHE_HOME is set-but-useless; `or' would take it and
+     ;; resolve the whole path relative to whatever the cwd happens to be.
+     (if (and xdg (not (string-empty-p xdg)))
+         xdg
+       (expand-file-name ".cache" (or (getenv "HOME") "~")))))
+  "Where the wallpaper renderer reads the day from.
+
+A stable path is load-bearing on both sides.  Because the file is only ever
+replaced by a rename, the renderer keeps drawing the last good answer while
+Emacs is down, which makes this file its own cache.")
+
+(defun cj/agenda-render-json (start-epoch end-epoch &optional out-path)
+  "Return the agenda between START-EPOCH and END-EPOCH in the renderer's shape.
+
+Bounds are epoch SECONDS, as everywhere else here.  Each row carries the
+canonical fields plus the three the renderer reads: s and e as epoch
+MILLISECONDS, and t as the title.  The renderer works in milliseconds
+throughout, and converting once here beats converting in three places there.
+
+Every row has a drawable e, even where the canonical end is null: an all-day
+entry spans its day and a point event has zero width.  See
+`cj/--agenda-query-drawable-end'."
+  (let ((json (json-serialize
+               (vconcat (mapcar #'cj/--agenda-query-render-row
+                                (cj/--agenda-query-events start-epoch
+                                                          end-epoch))))))
+    (when out-path
+      (cj/--agenda-query-write-atomically out-path json))
+    json))
+
+(defun cj/agenda-render-cache-update ()
+  "Write today's agenda to `cj/agenda-render-cache-file' for the renderer.
+
+The window is the whole local day, midnight to day close, so it is 23 or 25
+hours long on a DST changeover rather than a flat 24.  Returns the path.
+
+Safe to call repeatedly and from a timer: it only reads org files, creates the
+cache directory if needed, and replaces the file by rename, so a reader on its
+own schedule never sees a partial write."
+  (interactive)
+  (let* ((d (decode-time (time-convert nil 'integer)))
+         (start (cj/--agenda-query-epoch 0 0 0 (nth 3 d) (nth 4 d) (nth 5 d)))
+         (end (cj/--agenda-query-day-close (nth 3 d) (nth 4 d) (nth 5 d))))
+    (make-directory (file-name-directory cj/agenda-render-cache-file) t)
+    (cj/agenda-render-json start end cj/agenda-render-cache-file)
+    (when (called-interactively-p 'interactive)
+      (message "Agenda render cache written to %s" cj/agenda-render-cache-file))
+    cj/agenda-render-cache-file))
 
 (provide 'agenda-query)
 ;;; agenda-query.el ends here
diff --git a/tests/test-agenda-query--render.el b/tests/test-agenda-query--render.el
new file mode 100644
index 00000000..1f7232f2
--- /dev/null
+++ b/tests/test-agenda-query--render.el
@@ -0,0 +1,235 @@
+;;; test-agenda-query--render.el --- Tests for the renderer profile -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for `cj/agenda-render-json' and the row transform behind it.
+;;
+;; The renderer reads three keys — s and e as epoch MILLISECONDS, t as the
+;; title — and drops everything else before drawing.  Two things therefore have
+;; to hold, and both are asserted rather than assumed:
+;;
+;; 1. s and e really are milliseconds.  A seconds-for-milliseconds slip puts
+;;    every bar in 1970 and the surface renders empty, which looks exactly like
+;;    "Emacs isn't writing the file".
+;; 2. Every row has a drawable e.  The canonical profile reports null where the
+;;    source has no range, and null is not a width.
+;;
+;; Helpers carry a file-unique prefix: the editor hook loads every
+;; agenda-query test file into ONE process.
+
+;;; Code:
+
+(require 'ert)
+(require 'org)
+(require 'org-element)
+(require 'org-agenda)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'agenda-query)
+
+(defun test-aq-render--epoch (min hour day month year)
+  "Return the epoch for local MIN HOUR DAY MONTH YEAR."
+  (time-convert (encode-time (list 0 min hour day month year nil -1 nil))
+                'integer))
+
+(defmacro test-aq-render--with-agenda-file (text &rest body)
+  "Write TEXT to a temp agenda file and run BODY with `rows' bound.
+`rows' is the parsed render-profile output for all of 2026-07-31."
+  (declare (indent 1))
+  `(let* ((dir (make-temp-file "agenda-render-" t))
+          (file (expand-file-name "todo.org" dir)))
+     (unwind-protect
+         (progn
+           (with-temp-file file (insert ,text))
+           (let* ((org-agenda-files (list file))
+                  (rows (append (json-parse-string
+                                 (cj/agenda-render-json
+                                  (test-aq-render--epoch 0 0 31 7 2026)
+                                  (test-aq-render--epoch 59 23 31 7 2026))
+                                 :object-type 'alist)
+                                nil)))
+             ,@body))
+       (dolist (buffer (buffer-list))
+         (when (equal (buffer-file-name buffer) file) (kill-buffer buffer)))
+       (delete-directory dir t))))
+
+;;; Normal Cases
+
+(ert-deftest test-agenda-render-normal-emits-milliseconds ()
+  "Normal: s and e are epoch milliseconds, not seconds.
+
+The renderer works in milliseconds throughout.  Sending seconds puts every bar
+in January 1970, which draws as an empty surface — indistinguishable from the
+file never being written."
+  (test-aq-render--with-agenda-file
+      "* Standup\nSCHEDULED: <2026-07-31 Fri 09:00-09:30>\n"
+    (let ((row (car rows)))
+      (should (= (alist-get 's row)
+                 (* 1000 (test-aq-render--epoch 0 9 31 7 2026))))
+      (should (= (alist-get 'e row)
+                 (* 1000 (test-aq-render--epoch 30 9 31 7 2026))))
+      ;; Sanity on the magnitude: milliseconds since 1970 are 13 digits now.
+      (should (= 13 (length (number-to-string (alist-get 's row))))))))
+
+(ert-deftest test-agenda-render-normal-title-is-t ()
+  "Normal: the title is carried as t, the key the renderer reads."
+  (test-aq-render--with-agenda-file
+      "* TODO [#A] Standup with Nerses :work:\nSCHEDULED: <2026-07-31 Fri 09:00>\n"
+    (should (equal "Standup with Nerses" (alist-get 't (car rows))))))
+
+(ert-deftest test-agenda-render-normal-canonical-fields-survive ()
+  "Normal: the canonical fields ride along, since the consumer drops its own.
+One file serves both the renderer and anything reading the documented shape."
+  (test-aq-render--with-agenda-file
+      "* DONE Standup\nSCHEDULED: <2026-07-31 Fri 09:00-09:30>\n"
+    (let ((row (car rows)))
+      (should (equal "Standup" (alist-get 'title row)))
+      (should (eq t (alist-get 'done row)))
+      (should (equal "scheduled" (alist-get 'type row)))
+      ;; start stays SECONDS while s is milliseconds; the units never mix
+      ;; within a key.
+      (should (= (alist-get 'start row) (/ (alist-get 's row) 1000))))))
+
+;;; Boundary Cases
+
+(ert-deftest test-agenda-render-boundary-all-day-spans-its-day ()
+  "Boundary: an all-day entry gets a drawable e covering its whole day.
+Canonically its end is null, and null is not something a renderer can draw."
+  (test-aq-render--with-agenda-file
+      "* TODO Water plants\nSCHEDULED: <2026-07-31 Fri>\n"
+    (let ((row (car rows)))
+      (should (eq :null (alist-get 'end row)))
+      (should (= (alist-get 's row)
+                 (* 1000 (test-aq-render--epoch 0 0 31 7 2026))))
+      (should (= (alist-get 'e row)
+                 (* 1000 (1- (test-aq-render--epoch 0 0 1 8 2026))))))))
+
+(ert-deftest test-agenda-render-boundary-point-event-has-zero-width ()
+  "Boundary: a timed point event ends where it starts rather than at null.
+Zero width is a marker the renderer can decide how to draw; null is a crash or
+a silently dropped row."
+  (test-aq-render--with-agenda-file
+      "* Reminder\n<2026-07-31 Fri 14:00>\n"
+    (let ((row (car rows)))
+      (should (eq :null (alist-get 'end row)))
+      (should (= (alist-get 'e row) (alist-get 's row))))))
+
+(ert-deftest test-agenda-render-boundary-every-row-is-drawable ()
+  "Boundary: across a mixed day, every row has integer s and e with e >= s.
+This is the invariant the surface depends on, so it is asserted over the whole
+set rather than one row at a time."
+  (test-aq-render--with-agenda-file
+      (concat "* TODO All day\nSCHEDULED: <2026-07-31 Fri>\n"
+              "* Point\n<2026-07-31 Fri 14:00>\n"
+              "* Ranged\n<2026-07-31 Fri 15:00-16:30>\n"
+              "* TODO Deadline day\nDEADLINE: <2026-07-31 Fri 17:00>\n")
+    (should (= 4 (length rows)))
+    (dolist (row rows)
+      (should (integerp (alist-get 's row)))
+      (should (integerp (alist-get 'e row)))
+      (should (>= (alist-get 'e row) (alist-get 's row)))
+      (should (stringp (alist-get 't row))))))
+
+(ert-deftest test-agenda-render-boundary-empty-is-array ()
+  "Boundary: an empty day is an empty array, not null.
+The renderer parses the same shape whether or not anything is scheduled."
+  (let ((org-agenda-files nil))
+    (should (equal "[]" (cj/agenda-render-json 1785474000 1785477600)))))
+
+;;; ---------- the cache writer ----------
+
+(ert-deftest test-agenda-render-normal-cache-update-writes-today ()
+  "Normal: the cache writer covers the whole local day and creates its dir.
+
+This is the function that actually ships the feature, so it gets its own
+coverage rather than riding on the tests for the profile beneath it.  The
+window assertion is the point: a writer that quietly covered the last hour,
+or the next 24 from now, would still produce a plausible-looking file."
+  (let* ((dir (make-temp-file "agenda-cache-" t))
+         ;; A path two levels deep, so directory creation is exercised.
+         (cj/agenda-render-cache-file
+          (expand-file-name "settings/agenda.json" dir))
+         (org-agenda-files nil)
+         (windows '()))
+    (unwind-protect
+        (cl-letf (((symbol-function 'cj/agenda-render-json)
+                   (lambda (start end &optional out)
+                     (push (cons start end) windows)
+                     (when out (cj/--agenda-query-write-atomically out "[]"))
+                     "[]")))
+          (should (equal cj/agenda-render-cache-file
+                         (cj/agenda-render-cache-update)))
+          (should (file-exists-p cj/agenda-render-cache-file))
+          (let* ((window (car windows))
+                 (d (decode-time (car window))))
+            ;; Opens at local midnight...
+            (should (= 0 (nth 2 d)))
+            (should (= 0 (nth 1 d)))
+            (should (= 0 (nth 0 d)))
+            ;; ...and closes one second before the next.
+            (should (= (cdr window)
+                       (1- (cj/--agenda-query-epoch
+                            0 0 0 (1+ (nth 3 d)) (nth 4 d) (nth 5 d)))))
+            ;; It is today's day, not an arbitrary one.
+            (should (equal (list (nth 3 d) (nth 4 d) (nth 5 d))
+                           (let ((now (decode-time)))
+                             (list (nth 3 now) (nth 4 now) (nth 5 now)))))))
+      (delete-directory dir t))))
+
+(ert-deftest test-agenda-render-boundary-cache-update-is-idempotent ()
+  "Boundary: writing twice leaves one file and no temp litter."
+  (let* ((dir (make-temp-file "agenda-cache-" t))
+         (cj/agenda-render-cache-file (expand-file-name "agenda.json" dir))
+         (org-agenda-files nil))
+    (unwind-protect
+        (progn
+          (cj/agenda-render-cache-update)
+          (cj/agenda-render-cache-update)
+          (should (equal '("agenda.json")
+                         (directory-files
+                          dir nil directory-files-no-dot-files-regexp))))
+      (delete-directory dir t))))
+
+;;; Error Cases
+
+(ert-deftest test-agenda-render-error-cache-update-unwritable-parent ()
+  "Error: an unwritable cache location signals rather than failing silently.
+A silent failure here looks identical to an empty agenda on the surface."
+  (let* ((dir (make-temp-file "agenda-cache-ro-" t))
+         (cj/agenda-render-cache-file
+          (expand-file-name "settings/agenda.json" dir))
+         (org-agenda-files nil))
+    (unwind-protect
+        (progn
+          (set-file-modes dir #o500)
+          (should-error (cj/agenda-render-cache-update)))
+      (set-file-modes dir #o700)
+      (delete-directory dir t))))
+
+(ert-deftest test-agenda-render-error-bounds-are-still-seconds ()
+  "Error: the render profile takes SECONDS in, even though it emits
+milliseconds.  The direction of conversion is one-way and the input guards
+still apply, so a caller passing milliseconds is told rather than answered."
+  (let ((org-agenda-files nil)
+        (ms 1785474000000))
+    (should-error (cj/agenda-render-json ms (+ ms 3600000)) :type 'user-error)))
+
+;;; Back to Normal Cases -- the profile's own writer
+
+(ert-deftest test-agenda-render-normal-writes-out-path ()
+  "Normal: with an out-path the render profile writes it atomically."
+  (let* ((dir (make-temp-file "agenda-render-out-" t))
+         (out (expand-file-name "agenda.json" dir))
+         (org-agenda-files nil))
+    (unwind-protect
+        (progn
+          (cj/agenda-render-json 1785474000 1785477600 out)
+          (should (file-exists-p out))
+          (with-temp-buffer
+            (insert-file-contents out)
+            (should (equal "[]" (buffer-string))))
+          (should (zerop (logand (file-modes out) #o111))))
+      (delete-directory dir t))))
+
+(provide 'test-agenda-query--render)
+;;; test-agenda-query--render.el ends here