feat(quality): schema drift guard ORM↔DB + fix 16 latent drifts (FDD-OPS-001 L5)

pulse/packages/pulse-data/src/contexts/engineering_data/models.py

@@ -22,18 +22,28 @@ class EngPullRequest(TenantModel):
         UniqueConstraint("tenant_id", "external_id", name="uq_eng_pr_tenant_external"),
     )
 
-    external_id: Mapped[str] = mapped_column(String(512), nullable=False, index=True)
-    source: Mapped[str] = mapped_column(String(32), nullable=False)  # github | gitlab | azure
-    repo: Mapped[str] = mapped_column(String(512), nullable=False)
+    # FDD-OPS-001 L5 — sizes aligned with migration 002 schema.
+    external_id: Mapped[str] = mapped_column(String(500), nullable=False, index=True)
+    source: Mapped[str] = mapped_column(String(50), nullable=False)  # github | gitlab | azure
+    repo: Mapped[str] = mapped_column(String(255), nullable=False)
+    # FDD-OPS-001 L5 — `url` exists in DB schema (TEXT) but ORM lacked it.
+    # Surfaced by the schema drift guard (INC-023#4 class).
+    url: Mapped[str | None] = mapped_column(Text, nullable=True)
     title: Mapped[str] = mapped_column(Text, nullable=False)
-    author: Mapped[str] = mapped_column(String(256), nullable=False)
-    state: Mapped[str] = mapped_column(String(32), nullable=False)  # open | merged | closed | declined
+    # FDD-OPS-001 L5 — DB has VARCHAR(255); ORM previously declared String(256)
+    # which would cause INSERT failures for boundary-length authors.
+    # Aligned to DB.
+    author: Mapped[str] = mapped_column(String(255), nullable=False)
+    # FDD-OPS-001 L5 — DB has VARCHAR(50); aligned ORM up.
+    state: Mapped[str] = mapped_column(String(50), nullable=False)  # open | merged | closed | declined
 
     # Timestamps for cycle/lead time calculation
     first_commit_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     first_review_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     approved_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     merged_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    # FDD-OPS-001 L5 — `closed_at` exists in DB but ORM lacked it.
+    closed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     deployed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
 
     # Size metrics
@@ -84,30 +94,41 @@ class EngIssue(TenantModel):
         UniqueConstraint("tenant_id", "external_id", name="uq_eng_issue_tenant_external"),
     )
 
-    external_id: Mapped[str] = mapped_column(String(512), nullable=False, index=True)
-    source: Mapped[str] = mapped_column(String(32), nullable=False)  # jira | linear | azure
-    project_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    # FDD-OPS-001 L5 — sizes aligned with migration 002 schema.
+    external_id: Mapped[str] = mapped_column(String(500), nullable=False, index=True)
+    source: Mapped[str] = mapped_column(String(50), nullable=False)  # jira | linear | azure
+    project_key: Mapped[str] = mapped_column(String(100), nullable=False)
     # Human-readable issue key (e.g. "SECOM-1441"). Distinct from external_id,
     # which is the internal source ID (numeric for Jira). Used by PR linker
     # to match title/branch references back to issues.
     issue_key: Mapped[str | None] = mapped_column(String(128), nullable=True, index=True)
+    # FDD-OPS-001 L5 — `url` exists in DB but ORM lacked it.
+    url: Mapped[str | None] = mapped_column(Text, nullable=True)
     title: Mapped[str] = mapped_column(Text, nullable=False)
     # Plain-text description extracted from Jira ADF (Atlassian Document
     # Format) at ingestion. Capped at 4000 chars in the normalizer — see
     # jira_connector._extract_description_text() + backfill service.
     # NULL for legacy rows; API truncates to 300 chars before exposing.
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    issue_type: Mapped[str] = mapped_column(String(64), nullable=False)  # bug | story | task | epic
-    status: Mapped[str] = mapped_column(String(128), nullable=False)  # raw status from source
-    normalized_status: Mapped[str] = mapped_column(String(32), nullable=False)  # todo | in_progress | done
-    assignee: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    # FDD-OPS-001 L5 — sizes aligned with migration 002 schema.
+    issue_type: Mapped[str] = mapped_column(String(100), nullable=False)  # bug | story | task | epic
+    status: Mapped[str] = mapped_column(String(100), nullable=False)  # raw status from source
+    normalized_status: Mapped[str] = mapped_column(String(50), nullable=False)  # todo | in_progress | done
+    # FDD-OPS-001 L5 — `priority` exists in DB but ORM lacked it.
+    priority: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    assignee: Mapped[str | None] = mapped_column(String(255), nullable=True)
 
     story_points: Mapped[float | None] = mapped_column(Float, nullable=True)
     sprint_id: Mapped[str | None] = mapped_column(String(500), nullable=True, index=True)
 
     # Status transition log for CFD / flow metrics
     status_transitions: Mapped[list | None] = mapped_column(JSONB, nullable=True, default=list)
 
+    # FDD-OPS-001 L5 — `linked_pr_ids` exists in DB but ORM lacked it.
+    # Reverse of `eng_pull_requests.linked_issue_ids`: lists PR external_ids
+    # that reference this issue. Populated by the PR linker.
+    linked_pr_ids: Mapped[list | None] = mapped_column(JSONB, nullable=True, default=list)
+
     # Timestamps
     started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
@@ -145,13 +166,18 @@ class EngDeployment(TenantModel):
         UniqueConstraint("tenant_id", "external_id", name="uq_eng_deploy_tenant_external"),
     )
 
+    # FDD-OPS-001 L5 — sizes aligned with actual DB schema.
     external_id: Mapped[str] = mapped_column(String(512), nullable=False, index=True)
-    source: Mapped[str] = mapped_column(String(32), nullable=False)  # github | gitlab | azure | jenkins
-    repo: Mapped[str] = mapped_column(String(512), nullable=False)
-    environment: Mapped[str] = mapped_column(String(64), nullable=False)  # production | staging | dev
-    sha: Mapped[str] = mapped_column(String(512), nullable=True, default="")
-    author: Mapped[str] = mapped_column(String(256), nullable=True, default="")
+    source: Mapped[str] = mapped_column(String(50), nullable=False)  # github | gitlab | azure | jenkins
+    repo: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    environment: Mapped[str | None] = mapped_column(String(100), nullable=True)  # production | staging | dev
+    sha: Mapped[str | None] = mapped_column(String(512), nullable=True, default="")
+    author: Mapped[str | None] = mapped_column(String(256), nullable=True, default="")
     is_failure: Mapped[bool] = mapped_column(Boolean, default=False)
+    # FDD-OPS-001 L5 — these columns exist in DB but ORM lacked them.
+    url: Mapped[str | None] = mapped_column(Text, nullable=True)
+    trigger_type: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    trigger_ref: Mapped[str | None] = mapped_column(String(500), nullable=True)
     deployed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     recovery_time_hours: Mapped[float | None] = mapped_column(Float, nullable=True)
 
@@ -164,10 +190,16 @@ class EngSprint(TenantModel):
         UniqueConstraint("tenant_id", "external_id", name="uq_eng_sprint_tenant_external"),
     )
 
-    external_id: Mapped[str] = mapped_column(String(512), nullable=False, index=True)
-    source: Mapped[str] = mapped_column(String(32), nullable=False)
-    name: Mapped[str] = mapped_column(String(256), nullable=False)
-    board_id: Mapped[str] = mapped_column(String(128), nullable=False)
+    # FDD-OPS-001 L5 — sizes aligned with migration 002 schema:
+    # external_id VARCHAR(500), source VARCHAR(50), name VARCHAR(255),
+    # board_id VARCHAR(500). Previously ORM declared (512/32/256/128)
+    # which would either reject INSERTs (when ORM larger than DB) or
+    # cause type drift (when ORM stricter than DB). Surfaced by the
+    # schema drift guard.
+    external_id: Mapped[str] = mapped_column(String(500), nullable=False, index=True)
+    source: Mapped[str] = mapped_column(String(50), nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    board_id: Mapped[str] = mapped_column(String(500), nullable=False)
     # FDD-OPS-018 — sprint lifecycle: active | closed | future | NULL.
     # Was missing from the ORM model despite existing in the DB schema
     # (schema drift). Without this Mapped column, every attempt to upsert

pulse/packages/pulse-data/src/contexts/metrics/infrastructure/models.py

@@ -42,13 +42,14 @@ class MetricsSnapshot(Base):
         nullable=True,
         index=True,
     )
+    # FDD-OPS-001 L5 — sizes aligned with migration schema (50/100).
     metric_type: Mapped[str] = mapped_column(
-        String(64),
+        String(50),
         nullable=False,
         index=True,
     )  # dora | lean | cycle_time | throughput | sprint
     metric_name: Mapped[str] = mapped_column(
-        String(128),
+        String(100),
         nullable=False,
     )  # deployment_frequency | lead_time | cfd | wip | etc.
     value: Mapped[dict] = mapped_column(