From 198e772efbb17cc8dbd514b0c0487d780c5e3eaa Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Wed, 27 May 2026 19:22:19 -0500
Subject: refactor: add org-drill-card-state struct + ADR

First step of #147. I added a cl-defstruct bundling the recall fields the schedulers and the item-data round-trip shuttle around (last-interval, repetitions, ease, failures, meanq, total-repeats), with an ADR comment recording why: the same fields were passed as positional lists in three different orderings, and three call sites re-ordered between them by hand.

The struct is inert here. The item-data round-trip and the schedulers adopt it in the following commits.
---
 org-drill.el | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'org-drill.el')

diff --git a/org-drill.el b/org-drill.el
index e60a49d..270a19f 100644
--- a/org-drill.el
+++ b/org-drill.el
@@ -1122,6 +1122,28 @@ Returns the parsed list or nil if invalid or unsafe."
             data))
       (error nil))))
 
+;;; Card-state struct ---------------------------------------------------------
+;;
+;; ADR (2026-05-27): the schedulers and the item-data round-trip used to pass
+;; the same recall fields around as long positional lists, in three different
+;; orderings — `get-item-data'/`store-item-data' as
+;; (last-interval repetitions failures total-repeats meanq ease), the schedulers
+;; taking (last-interval n ef quality failures meanq total-repeats ...), and the
+;; schedulers returning (next-interval repetitions ef failures meanq
+;; total-repeats ...).  Three call sites re-ordered between the shapes by hand,
+;; each re-order a latent positional bug, and a new scheduler had to match all
+;; three layouts.
+;;
+;; `org-drill-card-state' bundles the shared stored fields under named slots so
+;; the shape is explicit and the manual re-ordering goes away.  `next-interval'
+;; and `quality' stay outside the struct: the former is scheduling output, the
+;; latter is the rating just entered — neither is persisted recall state.
+;;
+;; Migration is staged: this struct lands first (inert), then the item-data
+;; round-trip adopts it, then each scheduler in turn.
+(cl-defstruct org-drill-card-state
+  last-interval repetitions ease failures meanq total-repeats)
+
 (defun org-drill-get-item-data ()
   "Return alist of 6 items, containing all the stored recall
   data for the item at point:
-- 
cgit v1.2.3