From 30beeb3a2674f4185cf9d4f8a5281d24b7bd9cba Mon Sep 17 00:00:00 2001
From: Aaron Nelson <aaron@aaronnelson.studio>
Date: Fri, 1 May 2026 19:10:16 +0000
Subject: [PATCH] migrations: retroactively track stage_3_queue routing columns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds migrations/ directory with README documenting the convention
(timestamped filenames, idempotent SQL, forward-only, single change per file).

First migration is the Stage 3 queue routing columns added live during
Phase A patches today: state_type, state_type_confidence,
supersedes_prior_state, state_type_rationale, plus index on supersedes.
Required by stage2_worker.py >= 2.2 and stage3_worker.py >= 2.3.

Idempotent (IF NOT EXISTS), safe to re-apply. Verified by re-applying
against the live DB — no changes, no errors.

Closes a reproducibility gap: a fresh DB provisioned from git would crash
on first Stage 2 enqueue without these columns. Now the SQL travels with
the code.
---
 ...0501-001_stage_3_queue_routing_columns.sql | 23 ++++++++++++
 migrations/README.md                          | 37 +++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 migrations/20260501-001_stage_3_queue_routing_columns.sql
 create mode 100644 migrations/README.md

diff --git a/migrations/20260501-001_stage_3_queue_routing_columns.sql b/migrations/20260501-001_stage_3_queue_routing_columns.sql
new file mode 100644
index 0000000..72d7ed3
--- /dev/null
+++ b/migrations/20260501-001_stage_3_queue_routing_columns.sql
@@ -0,0 +1,23 @@
+-- 20260501-001 — Stage 3 queue routing columns for Phase A bulk-vs-single-episode routing
+--
+-- Adds four columns and one index to stage_3_queue, written by Stage 2 v2.2
+-- and read by Stage 3 v2.3 to choose between bulk and single-episode ingest
+-- pathways. See architecture doc and Phase A handoff (2026-05-01) for design.
+--
+-- Required by:
+--   scripts/stage2_worker.py >= 2.2
+--   scripts/stage3_worker.py >= 2.3
+--
+-- Idempotent: safe to re-apply against a database where the columns already
+-- exist (was applied live before this file was created).
+
+ALTER TABLE stage_3_queue
+    ADD COLUMN IF NOT EXISTS state_type             TEXT,
+    ADD COLUMN IF NOT EXISTS state_type_confidence  TEXT,
+    ADD COLUMN IF NOT EXISTS supersedes_prior_state BOOLEAN,
+    ADD COLUMN IF NOT EXISTS state_type_rationale   TEXT;
+
+-- Index on the routing signal — Stage 3 reads this on every dequeue,
+-- and observability queries (item 6: routing_decisions) will filter on it.
+CREATE INDEX IF NOT EXISTS stage_3_queue_supersedes_idx
+    ON stage_3_queue (supersedes_prior_state);
diff --git a/migrations/README.md b/migrations/README.md
new file mode 100644
index 0000000..448cf6e
--- /dev/null
+++ b/migrations/README.md
@@ -0,0 +1,37 @@
+# BirdAI database migrations
+
+Schema changes applied to the BirdAI Postgres database, in chronological order.
+Filenames are YYYYMMDD-NNN_short_description.sql where NNN is a sequence number
+within the day for ordering when multiple migrations land same-day.
+
+## Conventions
+
+- Each file is idempotent: uses IF NOT EXISTS / IF EXISTS so it can be
+  re-run safely against a database that already has the change applied. This
+  matters because we don't track which migrations a given DB has applied (no
+  migrations table yet — that's its own future migration).
+- Each file is a single logical change: one feature, one rollout. Don't pile
+  unrelated DDL into one file.
+- Each file documents what it's for and which worker version requires it
+  in a header comment, so the relationship between schema and code is legible
+  from either side.
+- Migrations are forward-only. No down-migrations. If a change is wrong,
+  write a new migration that fixes it.
+
+## Applying
+
+Against the live DB:
+
+    psql "$PG_DSN" -f migrations/YYYYMMDD-NNN_name.sql
+
+Against a fresh DB (disaster recovery, dev clone), apply all files in order:
+
+    for f in migrations/*.sql; do
+        echo "Applying $f"
+        psql "$PG_DSN" -f "$f"
+    done
+
+## Pending: migrations tracking table
+
+There is no schema_migrations table yet. Adding one is itself a migration —
+deferred until a second migration after this one lands and the need is real.