kryten-webqueue 0.46.0__tar.gz → 0.47.0__tar.gz

{kryten_webqueue-0.46.0 → kryten_webqueue-0.47.0}/.gitignore

@@ -62,6 +62,10 @@ config-*.json
 *.db
 *.db-wal
 *.db-shm
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+data/
 
 # OS
 .DS_Store

{kryten_webqueue-0.46.0 → kryten_webqueue-0.47.0}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.47.0] - 2026-09-23
+
+### Added
+
+- **SQLite Domain Partitioning (`sqlite-domain-separation`)**:
+  - Split database architecture isolating heavy background write jobs from real-time pollers across 4 discrete SQLite databases:
+    - `catalog.sqlite3` — Catalog items, FTS5 index, categories, tags, people, studios, enrichment state, MOTD overrides.
+    - `queue.sqlite3` — Queue shadow, spend requests, queue history, saved playlists, schedules, play completions, blackouts.
+    - `jobs.sqlite3` — Background job runs, per-line job run logs, schedules, and fetch queue.
+    - `users.sqlite3` — OTPs, device link codes, device API keys, watchlists, feedback, title suggestions.
+  - Multi-database connection facade (`Database`) managing domain sub-connections (`self.catalog`, `self.queue`, `self.jobs`, `self.users`) with independent WAL, checkpoints, and busy timeouts.
+  - Configurable `DatabaseConfig` supporting `layout="monolith"` and `layout="partitioned"` with safe path resolution and guards against accidental silent bypass of existing monolith databases.
+  - Automated database migration ETL script `scripts/split_databases.py` (`kryten-webqueue-split-db`) with checkpoint-safe reading, foreign key verification, and deterministic SHA-256 data parity validation.
+  - Concurrency stress test suite (`tests/test_concurrency_split.py`) verifying zero cross-domain lock contention between high-frequency queue polling, burst job logging, and web browse requests.
+
+### Changed
+
+- Decoupled cross-domain SQL queries:
+  - User watchlist ("My List") queries `users.sqlite3` for ordered tokens and hydrates item metadata from `catalog.sqlite3`.
+  - Recently-played hiding and weekend blackout exclusions resolved across domain boundaries without cross-file SQL joins.
+  - Promo-pool hide state purge orchestrated across `queue.sqlite3` and `catalog.sqlite3`.
+
+## [0.46.1] - 2026-09-10
+
+### Changed
+
+- **The grid is an even split again** (6/6 for a 12-slot Friday+Saturday
+  weekend). The 5/7 shape 0.46.0 inferred from the live MOTD was an artifact of
+  a markup bug: with the `<a>` tags left unclosed, the blank line after the
+  fifth poster looks like a night break but isn't, and most screen widths hide
+  the resulting reflow. The generated snippet closes its tags, so it renders the
+  intended 6/6.
+- A night with more scheduled titles than grid positions now records a warning
+  (job result, admin panel, and log) instead of silently dropping the extras.
+
 ## [0.46.0] - 2026-09-10
 
 ### Changed
@@ -15,6 +50,7 @@
   night is never truncated, so an over-full weekend shows every scheduled movie;
   `motd.slots` is a target the grid is only padded *up* to when the weekend is
   still thin.
+  (Reverted in 0.46.1 — the 5/7 reading was a markup artifact.)
 - **Sunday is excluded.** New `motd.nights` (default `[1, 2]`) controls which
   nights the grid covers; Sunday has no schedule yet, so its workbook titles are
   parsed but ignored. Add `3` once the scheduled-playlists feature fills that

{kryten_webqueue-0.46.0 → kryten_webqueue-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kryten-webqueue
-Version: 0.46.0
+Version: 0.47.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.46.0 → kryten_webqueue-0.47.0}/config.example.json

@@ -62,6 +62,15 @@
     }
   },
 
+  "database": {
+    "layout": "monolith",
+    "db_path": "/var/lib/kryten-webqueue/webqueue.db",
+    "data_dir": "/var/lib/kryten-webqueue/data",
+    "catalog_db_path": null,
+    "queue_db_path": null,
+    "jobs_db_path": null,
+    "users_db_path": null
+  },
   "db_path": "/var/lib/kryten-webqueue/webqueue.db",
 
   "image_dir": "/var/lib/kryten-webqueue/images",

kryten_webqueue-0.47.0/docs/DATABASE_ARCHITECTURE_PLAN.md

@@ -0,0 +1,206 @@
+# Database Architecture & Evolution Plan: Kryten-WebQueue
+
+**Status**: Approved Architecture Plan  
+**Target System**: `kryten-webqueue`  
+**Author**: Senior Microservice Architect (Kryten)  
+**Last Updated**: September 2026  
+
+---
+
+## Executive Summary
+
+`kryten-webqueue` has evolved from a lightweight catalog viewer into a multi-faceted web application hosting the CyTube channel catalog, real-time queue shadows, automated playlist schedulers, background media ingestion, TMDB enrichment pipelines, user watchlists, device API authentication, and per-line job logging.
+
+Under heavy concurrent operation, the application suffers from SQLite database write-lock contention (`sqlite3.OperationalError: database is locked`) because all domains share a single SQLite database file and a single async worker connection.
+
+This document outlines the **two-part architectural roadmap**:
+
+1. **Part 1 (Immediate / Stopgap)**: **SQLite Domain Partitioning** — Split the monolithic SQLite database into 4 logical database files (`catalog.db`, `queue.db`, `jobs.db`, `users.db`) to isolate high-throughput writers (job logs, enrichment syncs) from real-time pollers and public browse traffic. This removes cross-domain contention; it does not remove writer serialization within a single domain file.
+2. **Part 2 (Strategic / Chandra-1 Migration)**: **PostgreSQL on Chandra-1 via Podman** — Migrate all partitioned domains into one PostgreSQL database (`webqueue`) on `chandra-1` utilizing schemas (`catalog`, `queue`, `jobs`, `users`, `tmdb`), powered by **SQLAlchemy 2.0 (`asyncpg`)**, PostgreSQL Full-Text Search (`tsvector` + GIN) + `pg_trgm` fuzzy matching, and automated 30-day job log pruning (strictly exempting all financial, chat, and purchase records).
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                 TWO-PART ROADMAP                                       │
+├────────────────────────────────────────┬───────────────────────────────────────────────┤
+│ PART 1: SQLite Domain Partitioning     │ PART 2: Chandra-1 PostgreSQL & Podman Pod     │
+├────────────────────────────────────────┼───────────────────────────────────────────────┤
+│ • Split single DB into 4 files:        │ • Single Postgres database `webqueue` on      │
+│   - catalog.db (MediaCMS mirror, art)  │   chandra-1 with logical schemas.             │
+│   - queue.db (shadow, schedules, play) │ • SQLAlchemy 2.0 (asyncpg) connection pool.   │
+│   - jobs.db (job runs, logs, fetch)    │ • English `tsvector` + GIN + `pg_trgm` search.│
+│   - users.db (OTPs, devices, list)     │ • 30-day job run log pruning policy (strictly │
+│ • Decouple cross-table JOINs in Python │   exempting economy, spend, and chat data).   │
+│ • Zero lock contention between batch   │ • Podman container deployment on chandra-1    │
+│   jobs and real-time playback pollers. │   with shared media asset volumes.            │
+└────────────────────────────────────────┴───────────────────────────────────────────────┘
+```
+
+---
+
+## Part 1: SQLite Domain Partitioning & Lock Elimination
+
+### 1.1 Root Cause of Current Contention
+
+1. **Single Writer Serialization**: In SQLite WAL mode, any number of readers can proceed concurrently, but only one write transaction can execute at a time per database file.
+2. **Single Connection Dispatcher**: `_connection.py` instantiates a single `aiosqlite.Connection`. In `aiosqlite`, all calls queue onto a single background OS thread, serializing even concurrent read operations.
+3. **Collision of Asynchronous Workloads**:
+   - **Heavy Writers**: `catalog_enrich` (updating thousands of item records), `catalog_sync`, `fetch_queue_drain` (yt-dlp ingestion), and `log_capture.py` (bulk inserting hundreds of log rows per job run).
+   - **Real-Time Pollers & API**: `StatePoller` (every 2–5s), `RacePoller`, `PlaylistScheduler`, `CompletionRecorder`, `PresenceRefundMonitor`, and device API key authentication (updating `last_used_at` per HTTP request).
+   - When a batch job holds the WAL write lock or issues rapid write transactions, real-time pollers and web requests exceed the 5000ms `busy_timeout` and crash with `database is locked`.
+
+### 1.2 Domain Partitioning Strategy
+
+We partition tables into 4 dedicated SQLite databases:
+
+```
+┌──────────────────────────┐   ┌──────────────────────────┐
+│        catalog.db        │   │         queue.db         │
+├──────────────────────────┤   ├──────────────────────────┤
+│ • catalog                │   │ • queue_shadow           │
+│ • catalog_fts (FTS5)     │   │ • spend_requests         │
+│ • categories             │   │ • queue_history          │
+│ • catalog_categories     │   │ • saved_playlists        │
+│ • tags                   │   │ • saved_playlist_items   │
+│ • catalog_tags           │   │ • playlist_schedules     │
+│ • people                 │   │ • active_schedule        │
+│ • catalog_people         │   │ • play_completions       │
+│ • studios                │   │ • playlist_item_played   │
+│ • catalog_studios        │   │ • catalog_blackouts      │
+│ • item_enrichment_state  │   └──────────────────────────┘
+│ • item_edit_log          │
+│ • sync_log               │   ┌──────────────────────────┐
+│ • motd_overrides         │   │         users.db         │
+└──────────────────────────┘   ├──────────────────────────┤
+                               │ • user_watchlist         │
+┌──────────────────────────┐   │ • otps                   │
+│         jobs.db          │   │ • device_link_codes      │
+├──────────────────────────┤   │ • device_api_keys        │
+│ • job_runs               │   │ • feedback               │
+│ • job_run_logs           │   │ • title_suggestions      │
+│ • job_schedules          │   └──────────────────────────┘
+│ • fetch_queue            │
+└──────────────────────────┘
+```
+
+### 1.3 Cross-Domain Query Decoupling
+
+Separating SQLite database files removes the ability to perform single SQL `JOIN`s across tables in different files. We resolve the existing cross-table queries in the application layer:
+
+1. **Recently-Played Catalog Suppression Filter**:
+   - *Previous*: `catalog` query joined `play_completions` and `playlist_item_played`.
+   - *Partitioned*: `queue.db` executes `get_active_hidden_media_ids() -> set[str]`. The browse query in `catalog.db` filters with `WHERE friendly_token NOT IN (...)`.
+2. **User Watchlist ("My List")**:
+   - *Previous*: `user_watchlist JOIN catalog`.
+   - *Partitioned*: Query `users.db` for `friendly_tokens` for the user, then query `catalog.db` with `get_catalog_items_by_tokens(tokens)`.
+3. **Title Suggestions Catalog Match**:
+   - *Previous*: `title_suggestions` lookup checking if `catalog_token` exists.
+   - *Partitioned*: Check `catalog.db` by token/title independently during triage or submission.
+4. **Job Run Logs & Job History**:
+   - `JobManager` writes exclusively to `jobs.db`. Background enrichment tasks write their metadata updates to `catalog.db` without locking the job log tables.
+
+### 1.4 Partitioning Limits and Safety
+
+Partitioning removes only cross-domain SQLite contention. `catalog` still contains browse reads
+and enrichment writes, while `queue` still contains poller, scheduler, and queue-history writes.
+Each domain therefore uses short, bounded transactions, retry/latency metrics, and domain-scoped
+concurrency tests. A `busy_timeout` is a wait budget, not a correctness mechanism.
+
+The layout is selected explicitly as `monolith` or `partitioned`. Startup never chooses a new
+default data directory when a legacy database exists, and migration history is never copied from
+the monolith: each partition has a fresh baseline schema version after ETL validation.
+
+### 1.5 Part 1 Implementation Artifacts
+
+- **Sprint Specs**: Located in `docs/sqlite-domain-separation/`
+  - `PRD-sqlite-domain-separation.md`
+  - `SPEC-Sortie-1-schema-partitioning-and-config.md`
+  - `SPEC-Sortie-2-multi-db-connection-layer.md`
+  - `SPEC-Sortie-3-cross-domain-query-decoupling.md`
+  - `SPEC-Sortie-4-etl-split-script-and-validation.md`
+
+---
+
+## Part 2: Chandra-1 PostgreSQL & Podman Migration
+
+### 2.1 Target Architecture
+
+Upon completion of Part 1, the partitioned domain model directly maps to PostgreSQL. Instead of maintaining multiple SQLite files, the application connects to a **single PostgreSQL database (`webqueue`)** on `chandra-1`, structured with logical schemas:
+
+- `catalog.*` — MediaCMS catalog mirror, cast/crew, tags, categories, enrichment state, MOTD overrides.
+- `queue.*` — Queue shadow, spend requests, saved playlists, schedules, play completions, blackouts.
+- `jobs.*` — Job schedules, job runs, per-line job logs, fetch queue.
+- `users.*` — OTP authentication, device link codes & API keys, user watchlists, feedback, title suggestions.
+- `tmdb.*` — Persistent, queryable local TMDB dump index.
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                 chandra-1 Host System                                  │
+│                                                                                        │
+│  ┌──────────────────────────────────────────────────────────────────────────────────┐  │
+│  │                            Podman Pod: kryten-webqueue                           │  │
+│  │                                                                                  │  │
+│  │  ┌─────────────────────────────┐           ┌──────────────────────────────────┐  │  │
+│  │  │    kryten-webqueue-app      │           │           nginx proxy            │  │  │
+│  │  │   (FastAPI + uvicorn)       │◄─────────►│     (Reverse Proxy + SSL)        │  │  │
+│  │  │   SQLAlchemy 2.0 (asyncpg)  │           │                                  │  │  │
+│  │  └──────────────┬──────────────┘           └────────────────┬─────────────────┘  │  │
+│  └─────────────────┼───────────────────────────────────────────┼────────────────────┘  │
+│                    │                                           │                       │
+│                    ▼                                           ▼                       │
+│  ┌─────────────────────────────────────┐     ┌──────────────────────────────────────┐  │
+│  │        PostgreSQL on chandra-1      │     │         Shared Media Volume          │  │
+│  │        Database: webqueue           │     │        /var/lib/kryten/media         │  │
+│  │        Schemas: catalog, queue,     │     │        - cover art / posters         │  │
+│  │                 jobs, users, tmdb   │     │        - TMDB dump files             │  │
+│  └─────────────────────────────────────┘     └──────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Core Technical Specifications
+
+1. **ORM & Driver**: **SQLAlchemy 2.0 with `asyncpg`** (`create_async_engine`, `async_sessionmaker`, `AsyncSession`).
+   - Retains clean async repository layer with type-safe query construction and parameterized execution.
+   - Automatic connection pooling (`pool_size=10, max_overflow=20, pool_pre_ping=True`).
+2. **Search Engine**:
+   - **Full-Text Search**: English `tsvector` generated column + `GIN` index on `catalog.title` and `catalog.description`.
+   - **Typo-Tolerant Matching**: `pg_trgm` extension with GIN/GiST index on `catalog.title` for fuzzy `similarity()` matching (e.g., matching "terminatr" to "The Terminator").
+   - Eliminates all SQLite FTS5 query-sanitization crashes.
+3. **Automated Log Pruning Policy**:
+   - A scheduled background job cleans up rows in `jobs.job_run_logs` older than **30 days**.
+   - **CRITICAL COMPLIANCE CONSTRAINT**: This pruning policy applies **EXCLUSIVELY** to `jobs.job_run_logs`. It must **NEVER** touch or prune:
+     - Chat logs or user communication records
+     - Economy or z-coin purchase history (`spend_requests`, `queue_history`)
+     - User feedback or moderation audit logs (`item_edit_log`, `feedback`)
+4. **ETL & Data Migration**:
+   - Streaming migration script (`migrate_sqlite_to_pg.py`) reading from the 4 SQLite databases and writing into PostgreSQL with foreign key verification, sequence resets, and JSONB conversion.
+
+### 2.3 Cutover Contract
+
+WebQueue runs as a rootful Quadlet application container on `chandra-1`; PostgreSQL is
+host-managed on the same host and reached through an explicit container host gateway, never
+container-localhost. The PostgreSQL cutover uses a maintenance window and forward-fix recovery:
+the SQLite snapshot remains read-only for one release, but it is not an automatic rollback target
+after PostgreSQL accepts writes.
+
+### 2.4 Part 2 Implementation Artifacts
+
+- **Sprint Specs**: Located in `docs/postgres-migration/`
+  - `PRD-postgres-migration.md`
+  - `SPEC-Sortie-1-db-config-and-pool.md`
+  - `SPEC-Sortie-2-connection-layer-port.md`
+  - `SPEC-Sortie-3-fts5-to-tsvector.md`
+  - `SPEC-Sortie-4-tmdb-index-database.md`
+  - `SPEC-Sortie-5-etl-migration.md`
+  - `SPEC-Sortie-6-tests-cutover-release.md`
+
+---
+
+## Sequencing & Next Steps
+
+1. **Phase 1 Execution (Immediate)**:
+   - Implement Part 1 (SQLite Domain Partitioning) to resolve production write-lock crashes immediately without requiring infrastructure migration on chandra-1.
+   - Run `split_databases.py` in staging/production to migrate single SQLite DB to `catalog.sqlite3`, `queue.sqlite3`, `jobs.sqlite3`, `users.sqlite3`.
+2. **Phase 2 Execution (Subsequent)**:
+   - Bootstrap PostgreSQL `webqueue` database on `chandra-1`.
+   - Deploy Podman container on `chandra-1` with SQLAlchemy 2.0 + asyncpg.
+   - Execute ETL migration and switch production traffic.

kryten_webqueue-0.47.0/docs/postgres-migration/PRD-postgres-migration.md

@@ -0,0 +1,203 @@
+# PRD: PostgreSQL & Chandra-1 Podman Migration
+
+**Sprint**: `postgres-migration`
+**Status**: Planned - Post SQLite Domain Separation
+**Builds on**: `sqlite-domain-separation`
+**Target version**: `0.48.0`
+**Workflow**: [../../AGENT-WORKFLOW-GUIDE.md](../../AGENT-WORKFLOW-GUIDE.md)
+**Parent Plan**: [../DATABASE_ARCHITECTURE_PLAN.md](../DATABASE_ARCHITECTURE_PLAN.md)
+
+---
+
+## 1. Executive Summary
+
+Following SQLite domain separation, `kryten-webqueue` will move its application data to one
+PostgreSQL 16+ database, `webqueue`, on `chandra-1`. The database has five logical schemas:
+`catalog`, `queue`, `jobs`, `users`, and `tmdb`. The application will use SQLAlchemy 2.0 async
+sessions backed by `asyncpg`, with PostgreSQL full-text search and trigram matching replacing
+SQLite FTS5.
+
+The cutover is a planned maintenance-window migration. SQLite remains an immutable recovery
+snapshot for one release, but production writes accepted after cutover are repaired forward in
+PostgreSQL; the system does not silently fall back to a divergent SQLite copy.
+
+## 2. Decisions and Boundaries
+
+The following decisions are fixed for this sprint:
+
+- One PostgreSQL database named `webqueue` owns all five schemas. `tmdb` is a schema, not a
+  separate database, so catalog enrichment can use relational queries when needed.
+- The application runs as a rootful Podman Quadlet service on `chandra-1`.
+- PostgreSQL is host-managed on `chandra-1`. The rootful application container connects through
+  an explicitly configured host-gateway address; it must not use `localhost`.
+- The migration uses a maintenance window and a forward-fix rollback policy. There is no
+  dual-write phase and no automatic return to SQLite after PostgreSQL accepts writes.
+- Existing api-gate, MediaCMS, and CyTube integration contracts are unchanged. This sprint does
+  not add direct service-to-service communication paths.
+
+## 3. Goals and Success Metrics
+
+- Preserve all application records and identity values during migration without external
+  TMDB/OMDB calls.
+- Remove SQLite writer starvation between independent workloads after the SQLite partitioning
+  release, then move to PostgreSQL MVCC and pooled connections.
+- Preserve public and administrative response shapes, queue semantics, OTP single-use behavior,
+  device-key behavior, and audit history.
+- Provide typo-tolerant search while removing FTS5 parser failures.
+- Complete staging rehearsal and production cutover with source/destination parity, foreign-key
+  validation, application smoke tests, and no unplanned data loss.
+
+Success is measured by zero unhandled database errors during the concurrency test suite, no
+migration verification mismatch, successful health/browse/search/queue smoke tests, and a
+recorded cutover checkpoint that can be restored for investigation.
+
+## 4. Target Architecture
+
+### 4.1 Schema Ownership
+
+| Schema | Tables and responsibility |
+| --- | --- |
+| `catalog` | Catalog mirror, FTS source data, categories, tags, people, studios, enrichment state, edit log, sync log, MOTD overrides. |
+| `queue` | Queue shadow, spend requests, queue history, playlists, schedules, completions, and blackouts. |
+| `jobs` | Job schedules, job runs, run logs, and fetch queue. |
+| `users` | OTPs, device link codes, device API keys, watchlists, feedback, and title suggestions. |
+| `tmdb` | Persistent TMDB dump index and index metadata. |
+
+Schema ownership organizes privileges, migrations, and repository modules. It does not imply
+separate transactions: a single SQLAlchemy session may atomically update related WebQueue
+schemas. External economy and CyTube actions remain distributed operations and require
+idempotency and reconciliation rather than a cross-system transaction.
+
+### 4.2 Access Model
+
+- All application repository I/O uses SQLAlchemy 2.0 async sessions and parameterized named
+  binds. Raw `asyncpg` calls and mechanical `?` to `$n` translation are out of scope.
+- Repository methods retain their public return shapes. A request or job defines the transaction
+  boundary; helpers must not commit independently unless explicitly documented as standalone.
+- Migrations use a dedicated migrator role and a PostgreSQL advisory lock. Application instances
+  never race to apply DDL during startup.
+- The runtime role receives only application DML privileges. The migration role owns schema DDL.
+  The scheduled log-pruner uses a restricted maintenance role that can delete only from
+  `jobs.job_run_logs`.
+
+### 4.3 Configuration and Secrets
+
+`database.backend` is `sqlite` or `postgres`. The transitional SQLite configuration explicitly
+selects `monolith` or `partitioned`; startup rejects ambiguous layouts and rejects an unmigrated
+legacy database instead of creating empty default files.
+
+For PostgreSQL, connection resolution is `dsn_env`, then a password-free `dsn`, then assembled
+host/port/user/database values. `KRYTEN_WEBQUEUE_PG_PASSWORD` is the only password source.
+Configuration files must not contain a password or a DSN with an embedded password. The
+container receives its database settings through a root-owned, mode-0600 environment file.
+
+### 4.4 Container Connectivity
+
+The rootful Quadlet supplies the host-gateway mapping and configures the database host as that
+mapping (for example, `host.containers.internal` mapped to `host-gateway`). `localhost:5432` is
+not valid for the application container unless PostgreSQL is deliberately moved into the same
+pod, which is not part of this sprint. Deployment verification includes a connection test from
+inside the running application container.
+
+## 5. PostgreSQL Design
+
+### 5.1 Migrations and Types
+
+PostgreSQL DDL lives in ordered, immutable migration files with a tracked schema-version table.
+The initial migration is a clean PostgreSQL baseline; it does not replay the SQLite migration
+history or its historic data mutations. Each foreign key is schema-qualified, and migration tests
+validate constraints, unique indexes, cascade behavior, and application-required indexes.
+
+SQLite timestamps are interpreted as UTC during ETL. The ETL preflight rejects unparseable
+values rather than guessing. Columns designated as structured JSON are validated before writing
+`jsonb`; free-form log and detail fields remain `text` unless a separate compatibility decision
+changes their contract. Identity values are imported with `OVERRIDING SYSTEM VALUE`, then every
+identity sequence is reset with correct empty-table semantics.
+
+### 5.2 Search
+
+`catalog.catalog` stores a generated English `tsvector` with title-weighted ranking and a GIN
+index. `pg_trgm` supplies a title trigram index and a fuzzy fallback with an initial similarity
+threshold of `0.3`. Search uses `websearch_to_tsquery` with bound parameters.
+
+`catalog_fts` is a derived SQLite-only index. It is neither copied nor checksum-compared during
+ETL. PostgreSQL search is rebuilt from `catalog.catalog` and verified against exact, multi-word,
+fuzzy, and adversarial-input fixtures.
+
+### 5.3 Retention
+
+Only `jobs.job_run_logs` is eligible for retention deletion. The daily 04:00 UTC task deletes
+bounded batches using an index on `logged_at`, records a metric and audit log with the deleted
+row count, and retries on transient database failures. It never deletes `queue.spend_requests`,
+`queue.queue_history`, `users.feedback`, `users.title_suggestions`, `catalog.item_edit_log`, or
+records owned by other services.
+
+## 6. ETL and Verification
+
+The ETL reads partitioned SQLite files read-only after the source service and schedulers have
+stopped. It creates a fresh PostgreSQL target, streams tables in foreign-key-safe order, and
+never calls an external API. It writes only to a staging target that has passed migrations.
+
+Verification is deterministic for every source table:
+
+1. Compare row counts.
+2. Compare canonical hashes over stable primary-key ordering, normalized UTC timestamps, and
+   canonical JSON representations.
+3. Validate foreign keys, uniqueness, and sequence next values in PostgreSQL.
+4. Rebuild and test derived search indexes.
+5. Run application-level fixtures for browse, recently-played suppression, watchlist ordering,
+   queue history, OTP redemption, device-key authentication, jobs, and search.
+
+The source is captured with a SQLite backup/checkpoint-safe procedure while the service is
+stopped. Target files are created in a staging location for the SQLite split release; the source
+is never renamed or deleted automatically. Archival requires an explicit operator action after
+verification.
+
+## 7. Cutover and Recovery
+
+1. Rehearse the complete migration against a representative production snapshot and record
+   timings, hashes, and failures.
+2. Build and verify the rootful Quadlet image and host-gateway database connectivity on
+   `chandra-1`.
+3. Enter maintenance mode; stop WebQueue, its scheduler, and any writer that can touch the
+   SQLite files.
+4. Capture a verified SQLite backup, run PostgreSQL migrations once with the migrator role, and
+   run the ETL into a fresh target.
+5. Require all verification gates to pass before granting the runtime/pruner roles and starting
+   the Quadlet service.
+6. Run health, browse, search, queue, admin, OTP, device-key, and job-log smoke tests. Monitor
+   connection-pool saturation, query latency, database errors, and scheduler health.
+7. Preserve the SQLite snapshot read-only for one release. After PostgreSQL accepts a write,
+   recovery is a forward repair in PostgreSQL using recorded request identifiers and audit data;
+   reverting to SQLite is not an automatic rollback path.
+
+A failed pre-cutover verification returns to the unchanged SQLite service. A post-cutover defect
+is triaged as a forward fix; any manual recovery must explicitly account for writes accepted by
+PostgreSQL.
+
+## 8. Dependencies and Security
+
+Runtime dependencies are `sqlalchemy>=2.0.30`, `asyncpg>=0.29.0`, and `greenlet>=3.0`.
+PostgreSQL 16+ must provide `pg_trgm`; extension installation is performed by an administrator,
+not the application runtime role.
+
+Device-key hashes, OTPs, and session/auth behavior are preserved. TLS is required for a remote
+PostgreSQL endpoint; the approved host-local connection uses the configured host-gateway and
+host firewall restrictions. Backup ownership, retention, and restore testing are operational
+requirements before production cutover.
+
+## 9. Explicit Non-Goals
+
+- Redis caching, vector search, recommender features, and cross-service live database joins.
+- A dual-write migration or automatic rollback to a stale SQLite database.
+- Raw single-row speed as the primary success metric.
+
+## 10. Release Acceptance Criteria
+
+- One canonical `webqueue` database contains the five approved schemas.
+- SQLite configuration prevents accidental empty-database startup during transition.
+- All migrations, ETL verification, and application fixture checks pass in rehearsal.
+- The runtime uses SQLAlchemy async sessions; migrations and pruning use least-privilege roles.
+- The Quadlet app connects to host-managed PostgreSQL without relying on container-localhost.
+- Search, queue/payment reconciliation, retention, observability, and forward-recovery procedures
+  are documented and tested before the production cutover.

kryten_webqueue-0.47.0/docs/postgres-migration/SPEC-Sortie-1-db-config-and-pool.md

@@ -0,0 +1,90 @@
+# SPEC — Sortie 1: Database Config + SQLAlchemy 2.0 Async Engine
+
+**Sprint**: `postgres-migration`
+**PRD**: [PRD-postgres-migration.md](PRD-postgres-migration.md)
+**Depends on**: none
+**Estimated**: 2–4 h
+
+---
+
+## 1. Overview
+
+Add the Postgres backend selector, DSN resolution, and **SQLAlchemy 2.0 (`asyncpg`)** engine and session factory for the unified `webqueue` database on `chandra-1`, supporting both partitioned SQLite (from Part 1) and PostgreSQL backends.
+
+## 2. Scope and Non-Goals
+
+**In scope**: configuration models, DSN resolution, SQLAlchemy `AsyncEngine` and `async_sessionmaker` factory, example configuration updates, dependency additions (`sqlalchemy>=2.0.30`, `asyncpg>=0.29.0`, `greenlet>=3.0`).
+**Non-goals**: no repository port (Sortie 2), no FTS change (Sortie 3), no TMDB schema port (Sortie 4), no ETL (Sortie 5).
+
+## 3. Requirements
+
+- `database.backend: sqlite | postgres` (default `sqlite` during development/transitional phase).
+- `database.postgres`: `dsn_env`/password-free `dsn`/`host`/`port`/`user`/`dbname`/`password_env`/`pool_size`/`max_overflow`.
+- Single database `dbname = webqueue` hosting all logical schemas (`catalog`, `queue`, `jobs`, `users`, `tmdb`).
+- DSN precedence: `dsn_env` → password-free `dsn` plus `password_env` → assembled URL using `password_env`. No secrets, password field, or password-bearing DSN is permitted in `config.json`.
+
+## 4. Design
+
+```python
+# kryten_webqueue/config.py
+class PostgresConfig(BaseModel):
+    dsn_env: str | None = None
+    dsn: str | None = None
+    host: str = "host.containers.internal"
+    port: int = 5432
+    user: str = "kryten"
+    dbname: str = "webqueue"
+    password_env: str | None = "KRYTEN_WEBQUEUE_PG_PASSWORD"
+    pool_size: int = 10
+    max_overflow: int = 20
+
+class DatabaseConfig(BaseModel):
+    backend: Literal["sqlite", "postgres"] = "sqlite"
+    sqlite_layout: Literal["monolith", "partitioned"] = "monolith"
+    data_dir: str = "./data"                  # for partitioned sqlite
+    postgres: PostgresConfig = PostgresConfig()
+```
+
+```python
+# kryten_webqueue/catalog/db/engine.py
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+
+def create_pg_engine(config: PostgresConfig):
+    url = config.get_async_url()  # postgresql+asyncpg://...
+    engine = create_async_engine(
+        url,
+        pool_size=config.pool_size,
+        max_overflow=config.max_overflow,
+        pool_pre_ping=True,
+    )
+    session_factory = async_sessionmaker(
+        bind=engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+    return engine, session_factory
+```
+
+The runtime container resolves `host.containers.internal` through an explicit rootful Quadlet
+host-gateway mapping. This is not a container-localhost connection. Configuration validation
+rejects password-bearing `dsn` values and ambiguous SQLite layouts before startup.
+
+## 5. Implementation Plan
+
+- **Modify** `config.py`: add `PostgresConfig`, `DatabaseConfig` with `postgresql+asyncpg` URL builder.
+- **Create** `kryten_webqueue/catalog/db/engine.py`.
+- **Add dependencies** in `pyproject.toml`: `sqlalchemy>=2.0.30`, `asyncpg>=0.29.0`, `greenlet>=3.0`.
+- **Modify** `config.example.json`: document Postgres connection block with `KRYTEN_WEBQUEUE_PG_PASSWORD` environment placeholder.
+
+## 6. Testing Strategy
+
+- Unit tests for `PostgresConfig.get_async_url()` testing precedence order, environment-only password substitution, and rejection of password-bearing file DSNs.
+- Configuration loading tests for default SQLite and PostgreSQL configurations.
+
+## 7. Acceptance Criteria
+
+- [ ] Backend selectable; supports `sqlite` and `postgres`.
+- [ ] SQLAlchemy 2.0 `AsyncEngine` initialized with connection pooling.
+- [ ] Environment variable secret resolution verified without leaks.
+- [ ] SQLite layout validation prevents an existing monolith from being silently replaced by empty partitioned files.
+- [ ] Dependencies installed and all checks green (`black`, `ruff`, `mypy`, `pytest`).