US03-03: Generate and Persist Versioned Proposals (#63)

migrations/versions/0006_album_proposals.py

@@ -0,0 +1,59 @@
+"""Versioned album naming proposals (US03-03).
+
+Revision ID: 0006_album_proposals
+Revises: 0005_safety_analysis
+Create Date: 2026-08-15
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0006_album_proposals"
+down_revision = "0005_safety_analysis"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "album_proposals",
+        sa.Column("id", sa.String(), primary_key=True),
+        # The album label (US03-01 identity) this proposal names. One current
+        # proposal per album; superseded ones keep their history in the events.
+        sa.Column("album", sa.String(), nullable=False),
+        sa.Column("proposed_name", sa.String(), nullable=True),
+        sa.Column("final_name", sa.String(), nullable=True),
+        sa.Column("rationale", sa.String(), nullable=True),
+        sa.Column("confidence", sa.Float(), nullable=True),
+        # pending | proposed | edited | approved | error
+        sa.Column("status", sa.String(), nullable=False, server_default="pending"),
+        sa.Column("error_code", sa.String(), nullable=True),
+        sa.Column("error_message", sa.String(), nullable=True),
+        # The US03-01 evidence content hash the proposal was generated from; a
+        # different current value means the proposal is stale.
+        sa.Column("evidence_version", sa.String(), nullable=True),
+        sa.Column("model", sa.String(), nullable=True),
+        sa.Column("prompt_version", sa.String(), nullable=True),
+        sa.Column("raw_response", sa.String(), nullable=True),
+        # Optimistic concurrency: an edit/approval must present this version.
+        sa.Column("version", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("approved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+        ),
+    )
+    op.create_index("ix_album_proposals_album", "album_proposals", ["album"], unique=True)
+    op.create_index("ix_album_proposals_status", "album_proposals", ["status"])
+
+
+def downgrade() -> None:
+    op.drop_table("album_proposals")