feat: harden public OpenAI API contracts

backend/migrations/versions/20260907_0025_harden_openai_responses_contract.py

@@ -0,0 +1,64 @@
+"""add Responses idempotency, usage, and tombstones
+
+Revision ID: 20260907_0025
+Revises: 20260826_0024
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "20260907_0025"
+down_revision: str | Sequence[str] | None = "20260826_0024"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "openai_responses",
+        sa.Column("usage", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    )
+    op.add_column(
+        "openai_responses",
+        sa.Column("idempotency_key", sa.String(length=255), nullable=True),
+    )
+    op.add_column(
+        "openai_responses",
+        sa.Column("request_hash", sa.String(length=64), nullable=True),
+    )
+    op.add_column(
+        "openai_responses",
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_unique_constraint(
+        "uq_openai_response_idempotency",
+        "openai_responses",
+        ["api_key_id", "idempotency_key"],
+    )
+    op.create_index(
+        "ix_openai_responses_deleted_at",
+        "openai_responses",
+        ["deleted_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_openai_responses_deleted_at",
+        table_name="openai_responses",
+    )
+    op.drop_constraint(
+        "uq_openai_response_idempotency",
+        "openai_responses",
+        type_="unique",
+    )
+    op.drop_column("openai_responses", "deleted_at")
+    op.drop_column("openai_responses", "request_hash")
+    op.drop_column("openai_responses", "idempotency_key")
+    op.drop_column("openai_responses", "usage")