From 0e29eff7b74ed4e72796a1185430f8a69b83a1d0 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Sun, 1 Nov 2026 11:46:14 -0500
Subject: [PATCH] feat(podcasts): unset listening order defaults to reversed
 (audiobook-first)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The per-feed listening order — the Order dropdown on the podcast page
and player — resolved its UNSET state to "native": feed document order,
which runs newest-first for classic RSS. This platform is audiobook-
first, so native started every book at its LAST chapter (verified on
live data: 7th Son position 1 = Bonus Episode #2, positions descending
through the chapters).

The unset fallback flips to "reverse" at every resolution site of that
ONE setting — the podcast page's list + dropdown (podcastOrderForFeed),
the player's feed chain (reader.go), and the download queue
(orderOverrideFor) — so the dropdown shows reversed selected, the page
renders in that order, and play/download follow. Stored overrides are
untouched (native stays a valid savable choice); no ordering semantics
changed; collections are untouched.

Pins: the flipped native expectation is changelogged in contract_pins;
new pins cover the sequence config carrying reverse, feed position 1
playing last, and the page dropdown rendering reverse selected for an
unset feed.
---
 cmd/server/tests/podcast_test.go    | 24 +++++++++++++++++++++---
 docs/contract_pins.md               | 19 +++++++++++++++++++
 internal/router/podcast_page.go     | 13 ++++++++++---
 internal/router/reader.go           |  7 +++++--
 internal/services/podcast_worker.go | 14 ++++++++++----
 5 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/cmd/server/tests/podcast_test.go b/cmd/server/tests/podcast_test.go
index 8f42749d..c3993113 100644
--- a/cmd/server/tests/podcast_test.go
+++ b/cmd/server/tests/podcast_test.go
@@ -531,13 +531,31 @@ func TestPodcastPlayerOrderControl(t *testing.T) {
 	// match the escaped form.
 	esc := func(s string) string { return strings.ReplaceAll(s, `"`, "&#34;") }
 
-	t.Run("context_carries_feed_source", func(t *testing.T) {
+	t.Run("unset_default_is_reversed", func(t *testing.T) {
+		// 2026-11-01: the UNSET per-feed order resolves to "reverse"
+		// (audiobook-first — feed document order runs newest-first, so
+		// native started a book at its last chapter). The player's
+		// sequence config carries it; the podcast page's dropdown shows
+		// it selected; ep1 (feed position 1 of 2) plays LAST.
 		code, body := podcastAuthed(t, setup, setup.Token, "GET", ep1URL, "")
 		require.Equal(t, http.StatusOK, code)
 		assert.Contains(t, string(body), esc(`"source":"feed"`), "queue context must carry its owner (§10 R2)")
 		assert.Contains(t, string(body), esc(`"feed_id":"`+feedID+`"`))
-		assert.Contains(t, string(body), esc(`"order":"native"`))
-		assert.Contains(t, string(body), esc(`"episode_index":1`))
+		assert.Contains(t, string(body), esc(`"order":"reverse"`),
+			"unset order defaults to reversed (audiobook-first)")
+		assert.Contains(t, string(body), esc(`"episode_index":2`),
+			"feed position 1 plays last under the reversed default")
+	})
+
+	t.Run("podcast_page_dropdown_shows_reversed_when_unset", func(t *testing.T) {
+		code, body := podcastAuthed(t, setup, setup.Token, "GET", "/podcasts/"+feedID, "")
+		require.Equal(t, http.StatusOK, code)
+		html := string(body)
+		assert.Contains(t, html, `id="podcast-order-select"`, "the feed page renders its Order dropdown")
+		assert.Contains(t, html, `<option value="reverse" selected`,
+			"the unset default renders reversed as the selected option")
+		assert.NotContains(t, html, `<option value="native" selected`,
+			"native is no longer the unset default")
 	})
 
 	t.Run("order_dropdown_renders_feed_mode", func(t *testing.T) {
diff --git a/docs/contract_pins.md b/docs/contract_pins.md
index be2da982..a5c81e64 100644
--- a/docs/contract_pins.md
+++ b/docs/contract_pins.md
@@ -649,3 +649,22 @@ episodes).
 - The quiet suggest fetch remains only as a fallback for trees the SSR
   never saw (client-side apply flows); embedded labels make it a no-op
   on refresh.
+
+## 2026-11-01 — unset podcast order defaults to reversed (audiobook-first)
+
+The per-feed listening order (the D5 `podcast_order:<feedID>` KV shown
+in the Order dropdown) resolved its UNSET state to "native" — feed
+document order, which runs newest-first for classic RSS, so an
+audiobook feed played its LAST chapter first. The unset default is now
+`reverse` at every resolution site of that one setting: the podcast
+page list + dropdown (`podcastOrderForFeed`), the player's feed chain
+(reader.go), and the download worker (`orderOverrideFor`).
+
+- Stored overrides are untouched: anyone who picked an order keeps it
+  (native remains a valid, savable choice).
+- No ordering semantics changed — `OrderEpisodes` and the four-option
+  vocabulary are as they were; only the unset fallback flipped.
+- Pinned: the player sequence config carries `"order":"reverse"` and
+  feed position 1 plays LAST for an unset feed; the podcast page's
+  dropdown renders `reverse` selected (TestPodcastPlayerOrderControl,
+  replacing the former native pin).
diff --git a/internal/router/podcast_page.go b/internal/router/podcast_page.go
index 6cf58d4e..3d564a66 100644
--- a/internal/router/podcast_page.go
+++ b/internal/router/podcast_page.go
@@ -381,6 +381,13 @@ func buildPodcastDetailData(c *echo.Context, cfg *Config, user templates.User, f
 }
 
 // podcastOrderForFeed reads the caller's order override (D5).
+//
+// The UNSET default is "reverse" (2026-11-01 user request): the platform
+// is audiobook-first and feed document order runs newest-first, so
+// native starts a book at its LAST chapter. This is the same per-feed
+// setting the Order dropdown shows — page list, player chain, and
+// download queue all resolve through it. Stored overrides are untouched:
+// anyone who picked an order keeps exactly what they picked.
 func podcastOrderForFeed(cfg *Config, c *echo.Context, feedID string) string {
 	user := handlers.MustGetAuthenticatedUser(c)
 	row, err := cfg.Queries.GetUserSettingByKey(c.Request().Context(), database.GetUserSettingByKeyParams{
@@ -388,16 +395,16 @@ func podcastOrderForFeed(cfg *Config, c *echo.Context, feedID string) string {
 		SettingKey: "podcast_order:" + feedID,
 	})
 	if err != nil {
-		return "native"
+		return "reverse"
 	}
 	var v struct {
 		Order string `json:"order"`
 	}
 	if err := json.Unmarshal(row, &v); err != nil {
-		return "native"
+		return "reverse"
 	}
 	if !services.ValidPodcastEpisodeOrder(v.Order) {
-		return "native"
+		return "reverse"
 	}
 	return v.Order
 }
diff --git a/internal/router/reader.go b/internal/router/reader.go
index 38e038ad..b00a80da 100644
--- a/internal/router/reader.go
+++ b/internal/router/reader.go
@@ -187,8 +187,11 @@ func buildPodcastSequenceContext(c *echo.Context, cfg *Config, item *database.Me
 		return nil
 	}
 
-	// Effective order override (D5): reader_settings KV.
-	order := "native"
+	// Effective order override (D5): reader_settings KV. UNSET defaults
+	// to "reverse" (2026-11-01: audiobook-first — native document order
+	// starts a book at its last chapter); the same default the podcast
+	// page's Order dropdown shows. Stored overrides are untouched.
+	order := "reverse"
 	if row, err := cfg.Queries.GetUserSettingByKey(ctx, database.GetUserSettingByKeyParams{
 		UserID:     userID,
 		SettingKey: "podcast_order:" + uuid.UUID(item.SourceFeedID.Bytes).String(),
diff --git a/internal/services/podcast_worker.go b/internal/services/podcast_worker.go
index bfeb3b19..2c59692a 100644
--- a/internal/services/podcast_worker.go
+++ b/internal/services/podcast_worker.go
@@ -317,7 +317,11 @@ func (w *PodcastDownloadWorker) QueueFeedDownloadsAs(ctx context.Context, userID
 		return 0, err
 	}
 
-	order := "native"
+	// THE order helper (§0 item 5a) — same semantics as the sequence,
+	// reader chain, and page list; no per-surface sort drift. UNSET
+	// defaults to "reverse" (2026-11-01, audiobook-first: chapter order
+	// downloads first so listening can start while the rest fetches).
+	order := "reverse"
 	if userID.Valid {
 		order = w.orderOverrideFor(actx, userID, feedID)
 	}
@@ -344,19 +348,21 @@ func (w *PodcastDownloadWorker) QueueFeedDownloadsAs(ctx context.Context, userID
 }
 
 // orderOverrideFor reads a user's podcast_order override via the
-// reader_settings KV (the D5 storage; native when absent/invalid).
+// reader_settings KV (the D5 storage; "reverse" when absent/invalid —
+// the 2026-11-01 audiobook-first default, same as every other
+// resolution site of this setting).
 func (w *PodcastDownloadWorker) orderOverrideFor(ctx context.Context, userID, feedID pgtype.UUID) string {
 	row, err := w.db.GetUserSettingByKey(ctx, database.GetUserSettingByKeyParams{
 		UserID: userID, SettingKey: "podcast_order:" + feedID.String(),
 	})
 	if err != nil {
-		return "native"
+		return "reverse"
 	}
 	var v struct {
 		Order string `json:"order"`
 	}
 	if json.Unmarshal(row, &v) != nil || !ValidPodcastEpisodeOrder(v.Order) {
-		return "native"
+		return "reverse"
 	}
 	return v.Order
 }