No-QA generation runs and TEI-P5 retrieval (4.3.2)

alembic/versions/20260624_000010_add_generation_run_tables.py

@@ -0,0 +1,194 @@
+"""Add durable generation-run and event-log tables."""
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision = "20260624_000010"
+down_revision = "20260601_000009"
+branch_labels = None
+depends_on = None
+
+
+def _enum(name: str, *values: str) -> postgresql.ENUM:
+    """Return an existing-or-creatable PostgreSQL enum."""
+    return postgresql.ENUM(*values, name=name, create_type=False)
+
+
+def _create_enums() -> None:
+    """Create generation-run PostgreSQL enums."""
+    _enum(
+        "generation_run_status",
+        "pending",
+        "running",
+        "paused",
+        "succeeded",
+        "failed",
+        "cancelled",
+    ).create(op.get_bind(), checkfirst=True)
+    _enum("quality_mode", "draft_without_qa").create(op.get_bind(), checkfirst=True)
+    _enum("qa_status", "skipped").create(op.get_bind(), checkfirst=True)
+
+
+def _drop_enums() -> None:
+    """Drop generation-run PostgreSQL enums."""
+    _enum("qa_status", "skipped").drop(op.get_bind(), checkfirst=True)
+    _enum("quality_mode", "draft_without_qa").drop(op.get_bind(), checkfirst=True)
+    _enum(
+        "generation_run_status",
+        "pending",
+        "running",
+        "paused",
+        "succeeded",
+        "failed",
+        "cancelled",
+    ).drop(op.get_bind(), checkfirst=True)
+
+
+def _create_generation_runs_table() -> None:
+    """Create durable generation-run records."""
+    op.create_table(
+        "generation_runs",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "episode_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("episodes.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "source_bundle_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("ingestion_jobs.id"),
+            nullable=False,
+        ),
+        sa.Column("actor", sa.String(length=240), nullable=False),
+        sa.Column(
+            "status",
+            _enum(
+                "generation_run_status",
+                "pending",
+                "running",
+                "paused",
+                "succeeded",
+                "failed",
+                "cancelled",
+            ),
+            nullable=False,
+        ),
+        sa.Column("current_node", sa.String(length=160), nullable=True),
+        sa.Column("budget_snapshot", postgresql.JSONB(), nullable=False),
+        sa.Column("configuration", postgresql.JSONB(), nullable=False),
+        sa.Column(
+            "quality_mode",
+            _enum("quality_mode", "draft_without_qa"),
+            nullable=False,
+        ),
+        sa.Column("qa_status", _enum("qa_status", "skipped"), nullable=True),
+        sa.Column("skip_qa_rationale", sa.Text(), nullable=True),
+        sa.Column(
+            "idempotency_principal_id",
+            sa.String(length=200),
+            nullable=False,
+        ),
+        sa.Column("idempotency_key", sa.String(length=512), nullable=True),
+        sa.Column("error_message", sa.Text(), nullable=True),
+        sa.Column("error_category", sa.String(length=120), nullable=True),
+        sa.Column("lease_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("ended_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.UniqueConstraint(
+            "idempotency_principal_id",
+            "idempotency_key",
+            name="uq_generation_runs_idempotency_principal_key",
+        ),
+    )
+    op.create_index(
+        "ix_generation_runs_episode_id",
+        "generation_runs",
+        ["episode_id"],
+    )
+    op.create_index("ix_generation_runs_status", "generation_runs", ["status"])
+    op.create_index(
+        "ix_generation_runs_started_at",
+        "generation_runs",
+        ["started_at"],
+    )
+
+
+def _drop_generation_runs_table() -> None:
+    """Drop durable generation-run records."""
+    op.drop_index("ix_generation_runs_started_at", table_name="generation_runs")
+    op.drop_index("ix_generation_runs_status", table_name="generation_runs")
+    op.drop_index("ix_generation_runs_episode_id", table_name="generation_runs")
+    op.drop_table("generation_runs")
+
+
+def _create_generation_events_table() -> None:
+    """Create append-only generation-run event records."""
+    op.create_table(
+        "generation_events",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "generation_run_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("generation_runs.id"),
+            nullable=False,
+        ),
+        sa.Column("seq", sa.Integer(), nullable=False),
+        sa.Column("kind", sa.String(length=160), nullable=False),
+        sa.Column("payload", postgresql.JSONB(), nullable=False),
+        sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.UniqueConstraint(
+            "generation_run_id",
+            "seq",
+            name="uq_generation_events_run_seq",
+        ),
+    )
+    op.create_index(
+        "ix_generation_events_generation_run_id",
+        "generation_events",
+        ["generation_run_id"],
+    )
+
+
+def _drop_generation_events_table() -> None:
+    """Drop append-only generation-run event records."""
+    op.drop_index(
+        "ix_generation_events_generation_run_id",
+        table_name="generation_events",
+    )
+    op.drop_table("generation_events")
+
+
+def upgrade() -> None:
+    """Create generation-run persistence tables."""
+    _create_enums()
+    _create_generation_runs_table()
+    _create_generation_events_table()
+
+
+def downgrade() -> None:
+    """Drop generation-run persistence tables."""
+    _drop_generation_events_table()
+    _drop_generation_runs_table()
+    _drop_enums()

alembic/versions/20260624_000011_add_episode_tei_revisioning.py

@@ -0,0 +1,71 @@
+"""Add episode TEI revision metadata."""
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision = "20260624_000011"
+down_revision = "20260624_000010"
+branch_labels = None
+depends_on = None
+
+
+def _qa_status_enum() -> postgresql.ENUM:
+    """Return the existing QA status PostgreSQL enum."""
+    return postgresql.ENUM("skipped", name="qa_status", create_type=False)
+
+
+def upgrade() -> None:
+    """Add optimistic TEI revision metadata to episodes."""
+    op.add_column(
+        "episodes",
+        sa.Column("tei_revision", sa.Integer(), server_default="1", nullable=False),
+    )
+    op.create_check_constraint(
+        "ck_episodes_tei_revision_positive",
+        "episodes",
+        "tei_revision >= 1",
+    )
+    op.add_column(
+        "episodes",
+        sa.Column("tei_content_hash", sa.String(length=128), nullable=True),
+    )
+    op.add_column(
+        "episodes",
+        sa.Column("qa_status", _qa_status_enum(), nullable=True),
+    )
+    op.add_column(
+        "episodes",
+        sa.Column(
+            "last_generation_run_id",
+            postgresql.UUID(as_uuid=True),
+            nullable=True,
+        ),
+    )
+    op.create_foreign_key(
+        "fk_episodes_last_generation_run_id_generation_runs",
+        "episodes",
+        "generation_runs",
+        ["last_generation_run_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+
+
+def downgrade() -> None:
+    """Remove optimistic TEI revision metadata from episodes."""
+    op.drop_constraint(
+        "fk_episodes_last_generation_run_id_generation_runs",
+        "episodes",
+        type_="foreignkey",
+    )
+    op.drop_column("episodes", "last_generation_run_id")
+    op.drop_column("episodes", "qa_status")
+    op.drop_column("episodes", "tei_content_hash")
+    op.drop_constraint(
+        "ck_episodes_tei_revision_positive",
+        "episodes",
+        type_="check",
+    )
+    op.drop_column("episodes", "tei_revision")

docs/adr/adr-009-source-to-script-rest-vertical-slice.md

@@ -127,7 +127,9 @@ vertical-slice tasks:
 The first task owns upload resources, ingestion-job source attachment, and
 presenter-profile use through existing reusable reference-document semantics.
 The second task depends on the first task and owns the generation-run contract,
-the explicit no-QA quality mode, run polling, and TEI retrieval.
+the explicit no-QA quality mode, run polling, and TEI retrieval. ADR 016
+records its execution, persistence, recovery-hook, and content-negotiation
+decisions.
 
 The target API is `/v1`. Existing unversioned routes do not need preservation
 when the vertical slice is implemented because the project has not reached
@@ -248,7 +250,8 @@ the same first-write-wins and conflict-detection invariants.
 
 ## References
 
-See also the system design[^7] and TUI API design.[^8]
+See also the system design[^7], TUI API design,[^8] and the no-QA execution
+decision.[^9]
 
 [^1]: [RFC 6129: The `application/tei+xml` media type](https://datatracker.ietf.org/doc/html/rfc6129)
 [^2]: [ADR 014: Hexagonal architecture enforcement](adr-014-hexagonal-architecture-enforcement.md)
@@ -258,3 +261,4 @@ See also the system design[^7] and TUI API design.[^8]
 [^6]: [Stripe idempotent request guidance](https://docs.stripe.com/api/idempotent_requests)
 [^7]: [Episodic podcast generation system design](../episodic-podcast-generation-system-design.md)
 [^8]: [Episodic TUI API design](../episodic-tui-api-design.md)
+[^9]: [ADR 016: No-QA generation execution and TEI persistence](adr-016-no-qa-generation-run-execution-and-tei-persistence.md)