fix(sec): stop an unrecoverable filing gap pausing setups forever

A filing gap pauses its issuer until the filing is ingested or a later one
supersedes it, which assumes the gap is temporary. It is not always: SEC's
per-company Company-Facts files can go stale indefinitely — 43 large caps
whose Q2 10-Qs the frames API carries but whose companyfacts files never
received (Abbott's newest fact was 2026-04-29 in late August) — and because
the supersede rule needs a *successfully ingested* later filing, a stale file
swallows the next quarter too. The pause was open-ended, not seasonal.

So the pause hands off to the alert: once filing_gap_aged has escalated a gap,
it stops gating if the issuer's newest stored 10-K/10-Q is under 180 days old.
An issuer with nothing that recent has no usable fundamentals at all and stays
paused, which is the case the gate was built for.

Applied in the gate service only. active_gaps is deliberately untouched so
_retry_backlog keeps retrying and a recovered filing still resolves normally,
and the bound covers both gate paths — the queue and the validation_json
summary that mirrors the same filings — since bounding one leaves production
behaviour unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Lo99z3jWqu9X9ueBU3Z3D

app/services/fundamentals_quality_service.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 import json
+from collections import defaultdict
 from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
 
 from sqlalchemy import exists, func, select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -15,6 +17,23 @@ from app.models.ticker import Ticker
 
 _SEC_FORMS = ("10-K", "10-Q", "10-K/A", "10-Q/A")
 
+# How recent the issuer's own newest filing must be for an *escalated* gap to
+# stop pausing setups. A gap pauses an issuer until it is either resolved or
+# superseded by a later ingested filing — which assumes the gap is temporary.
+# It is not always: SEC's per-company Company-Facts files can go stale
+# indefinitely (2026-08, 43 large caps whose Q2 10-Qs the frames API carried but
+# whose companyfacts files never received), and since the supersede rule needs a
+# *successfully ingested* later filing, a stale file also swallows the next
+# quarter. The pause is then open-ended rather than seasonal.
+#
+# So the pause hands off to the alert: once `filing_gap_aged` has escalated a gap
+# to an operator (`escalated_at`), the issuer resumes on the fundamentals it does
+# have — provided those are recent. An issuer with nothing this fresh has no
+# usable fundamentals at all and stays paused, which is the case the gate was
+# built for. The retry queue is untouched: `active_gaps` still returns these, so
+# the importer keeps retrying and a recovered filing still resolves normally.
+GAP_GATE_RECENT_FILING_DAYS = 180
+
 
 @dataclass(frozen=True)
 class SetupQuality:
@@ -51,6 +70,39 @@ async def active_gaps(
     return list((await db.execute(stmt)).scalars().all())
 
 
+async def _gap_exempt_ciks(
+    db: AsyncSession, gaps: list[SecFilingGap]
+) -> set[str]:
+    """CIKs whose gaps have stopped pausing setups (see GAP_GATE_RECENT_FILING_DAYS).
+
+    Every one of a CIK's active gaps must be escalated: one fresh gap alongside an
+    old one still means a filing we might yet ingest, which is worth pausing for.
+    """
+    by_cik: dict[str, list[SecFilingGap]] = defaultdict(list)
+    for gap in gaps:
+        by_cik[gap.cik].append(gap)
+    escalated = {
+        cik
+        for cik, items in by_cik.items()
+        if all(gap.escalated_at is not None for gap in items)
+    }
+    if not escalated:
+        return set()
+    cutoff = (
+        datetime.now(timezone.utc) - timedelta(days=GAP_GATE_RECENT_FILING_DAYS)
+    ).date()
+    rows = await db.execute(
+        select(FundamentalSnapshot.cik)
+        .where(
+            FundamentalSnapshot.cik.in_(escalated),
+            FundamentalSnapshot.form.in_(_SEC_FORMS),
+            FundamentalSnapshot.filed_date >= cutoff,
+        )
+        .distinct()
+    )
+    return set(rows.scalars())
+
+
 async def _latest_validation(db: AsyncSession) -> dict:
     payload = (
         await db.execute(
@@ -80,8 +132,12 @@ async def blocked_reasons_by_cik(
     if ciks is not None and not ciks:
         return {}
 
+    gaps = await active_gaps(db, ciks)
+    # Escalated gaps on issuers that still have recent fundamentals no longer
+    # pause setups, on either path below — the summary mirrors the same filings.
+    exempt = await _gap_exempt_ciks(db, gaps)
     reasons = {
-        gap.cik: "sec_filing_gap" for gap in await active_gaps(db, ciks)
+        gap.cik: "sec_filing_gap" for gap in gaps if gap.cik not in exempt
     }
     summary = await _latest_validation(db)
 
@@ -92,11 +148,11 @@ async def blocked_reasons_by_cik(
     # stay capped for audit readability. Detailed entries supply the reason.
     for cik in summary.get("setup_blocked_ciks") or []:
         normalized = str(cik) if cik else ""
-        if normalized and wanted(normalized):
+        if normalized and wanted(normalized) and normalized not in exempt:
             reasons.setdefault(normalized, "sec_filing_gap")
     for item in summary.get("missing_xbrl") or []:
         normalized = str(item.get("cik") or "")
-        if normalized and wanted(normalized):
+        if normalized and wanted(normalized) and normalized not in exempt:
             reasons.setdefault(normalized, "sec_filing_gap")
     for cik in summary.get("no_xbrl_ciks") or []:
         normalized = str(cik) if cik else ""