feat(metadata): add resilient match queue diagnostics (#463)

* feat(metadata): add resilient match queue diagnostics

* fix(metadata): harden match queue lifecycle

---------

Co-authored-by: Quick104 <31828688+Quick104@users.noreply.github.com>

migrations/sql/20260721211627_metadata_match_queue_state.sql

@@ -0,0 +1,55 @@
+-- +goose Up
+-- +goose StatementBegin
+ALTER TABLE movie_match_queue
+    ADD COLUMN state text NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'parked')),
+    ADD COLUMN failure_kind text NOT NULL DEFAULT '',
+    ADD COLUMN failure_detail jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN deterministic_attempt_count integer NOT NULL DEFAULT 0,
+    ADD COLUMN input_fingerprint text NOT NULL DEFAULT '',
+    ADD COLUMN matcher_revision integer NOT NULL DEFAULT 0,
+    ADD COLUMN lease_token text NOT NULL DEFAULT '',
+    ADD COLUMN parked_at timestamptz;
+
+ALTER TABLE series_root_match_queue
+    ADD COLUMN state text NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'parked')),
+    ADD COLUMN failure_kind text NOT NULL DEFAULT '',
+    ADD COLUMN failure_detail jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN deterministic_attempt_count integer NOT NULL DEFAULT 0,
+    ADD COLUMN input_fingerprint text NOT NULL DEFAULT '',
+    ADD COLUMN matcher_revision integer NOT NULL DEFAULT 0,
+    ADD COLUMN lease_token text NOT NULL DEFAULT '',
+    ADD COLUMN parked_at timestamptz;
+
+CREATE INDEX idx_movie_match_queue_claimable
+    ON movie_match_queue (available_at, last_attempted_at, media_folder_id, media_file_id)
+    WHERE state = 'pending';
+CREATE INDEX idx_series_root_match_queue_claimable
+    ON series_root_match_queue (available_at, last_attempted_at, media_folder_id, observed_root_path)
+    WHERE state = 'pending';
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DROP INDEX IF EXISTS idx_series_root_match_queue_claimable;
+DROP INDEX IF EXISTS idx_movie_match_queue_claimable;
+
+ALTER TABLE series_root_match_queue
+    DROP COLUMN IF EXISTS parked_at,
+    DROP COLUMN IF EXISTS lease_token,
+    DROP COLUMN IF EXISTS matcher_revision,
+    DROP COLUMN IF EXISTS input_fingerprint,
+    DROP COLUMN IF EXISTS deterministic_attempt_count,
+    DROP COLUMN IF EXISTS failure_detail,
+    DROP COLUMN IF EXISTS failure_kind,
+    DROP COLUMN IF EXISTS state;
+
+ALTER TABLE movie_match_queue
+    DROP COLUMN IF EXISTS parked_at,
+    DROP COLUMN IF EXISTS lease_token,
+    DROP COLUMN IF EXISTS matcher_revision,
+    DROP COLUMN IF EXISTS input_fingerprint,
+    DROP COLUMN IF EXISTS deterministic_attempt_count,
+    DROP COLUMN IF EXISTS failure_detail,
+    DROP COLUMN IF EXISTS failure_kind,
+    DROP COLUMN IF EXISTS state;
+-- +goose StatementEnd

migrations/sql/20260723214954_media_files_series_match_fingerprint_index.sql

@@ -0,0 +1,32 @@
+-- +goose NO TRANSACTION
+
+-- +goose Up
+-- The series queue fingerprint aggregates active paths under each observed
+-- root. Build its supporting index without blocking scanner writes to the
+-- potentially large media_files table during deployment.
+-- A failed concurrent build can leave an INVALID relation that makes
+-- IF NOT EXISTS skip every retry. Remove only that unusable artifact.
+-- +goose StatementBegin
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        JOIN pg_index i ON i.indexrelid = c.oid
+        WHERE n.nspname = 'public'
+          AND c.relname = 'idx_media_files_folder_root_active'
+          AND NOT i.indisvalid
+    ) THEN
+        DROP INDEX public.idx_media_files_folder_root_active;
+    END IF;
+END;
+$$;
+-- +goose StatementEnd
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_media_files_folder_root_active
+    ON public.media_files (media_folder_id, observed_root_path)
+    WHERE missing_since IS NULL AND extra_id IS NULL;
+
+-- +goose Down
+DROP INDEX CONCURRENTLY IF EXISTS idx_media_files_folder_root_active;

migrations/sql/20260724135931_add_metadata_match_queue_rerun_requests.sql

@@ -0,0 +1,17 @@
+-- +goose Up
+ALTER TABLE movie_match_queue
+    ADD COLUMN rerun_requested boolean NOT NULL DEFAULT false,
+    ADD COLUMN lease_forced_rerun boolean NOT NULL DEFAULT false;
+
+ALTER TABLE series_root_match_queue
+    ADD COLUMN rerun_requested boolean NOT NULL DEFAULT false,
+    ADD COLUMN lease_forced_rerun boolean NOT NULL DEFAULT false;
+
+-- +goose Down
+ALTER TABLE series_root_match_queue
+    DROP COLUMN lease_forced_rerun,
+    DROP COLUMN rerun_requested;
+
+ALTER TABLE movie_match_queue
+    DROP COLUMN lease_forced_rerun,
+    DROP COLUMN rerun_requested;