From 15f41e6fd4e3acb68a0ab0b03c3d3a2bad5c735c Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Fri, 30 Oct 2026 10:40:34 -0400
Subject: [PATCH] test(pins): whitelist download_queue_pos on raw media rows
 (additive widening)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The contract pin caught the §0 item 4 column surfacing on media-list
raw sqlc rows — its job. Widened additively per doctrine: rawRowKeys +
docs/contract_pins.md changelog entry. NULL for scan rows and
never-queued episodes; nothing removed or renamed.
---
 cmd/server/tests/contract_pins_test.go | 4 ++++
 docs/contract_pins.md                  | 9 +++++++++
 2 files changed, 13 insertions(+)

diff --git a/cmd/server/tests/contract_pins_test.go b/cmd/server/tests/contract_pins_test.go
index 8f9fd76a..a870d1b7 100644
--- a/cmd/server/tests/contract_pins_test.go
+++ b/cmd/server/tests/contract_pins_test.go
@@ -761,6 +761,10 @@ func TestContractPin_MediaListBothBranches(t *testing.T) {
 		"declared_duration_seconds", "transcript_url", "chapters_url",
 		"hosts", "guests", "download_state", "download_error",
 		"download_attempts",
+		// §0 item 4 (2026-10-30 additive widening): the download pool's
+		// queue ticket — SEQUENCE-stamped at enqueue, NULL for scan rows
+		// and never-queued episodes. See docs/contract_pins.md changelog.
+		"download_queue_pos",
 	}
 	resolvedKeys := []string{
 		"id", "library_id", "title", "subtitle", "author", "authors", "isbn", "description",
diff --git a/docs/contract_pins.md b/docs/contract_pins.md
index 3f84a72a..804f96e1 100644
--- a/docs/contract_pins.md
+++ b/docs/contract_pins.md
@@ -459,3 +459,12 @@ resolved unscoped map:
 Scan-sourced rows carry the inert defaults ('scan' / NULLs / 'pending');
 raw-row consumers that filter `source='scan'` (scanner paths) are unaffected.
 Nothing removed, nothing renamed.
+
+## 2026-10-30 — download_queue_pos joins media_items (additive widening)
+
+§0 item 4 of podcast-integration.md: the download pool's monotonic
+queue ticket. `download_queue_pos BIGINT` (NULL for scan rows and
+never-queued episodes) is stamped from the `podcast_queue_seq` SEQUENCE
+at enqueue time so claim order = enqueue order (the effective listening
+order). Raw-row pins (TestContractPin_MediaListBothBranches →
+rawRowKeys) whitelist the key. Nothing removed, nothing renamed.