SEP-1907: Neutralize the dependency-typing artifacts in ty's warning output (#1434)

`ty check` reported 4,072 diagnostics with nothing in the output
separating a genuine typing defect in this repository from an artifact
of how a third-party dependency is typed. This splits the two and
neutralizes only the artifact half — 446 diagnostics — leaving a 3,626
first-party remainder that SEP-1908 can be sized against. **No rule
severity changes**: no severity in `[tool.ty.rules]` moved, and
`[tool.ty.src].include` and the `Makefile` `typecheck` target are
byte-identical to `main`. The only edit inside the `[tool.ty.rules]`
span is the comment block introducing the override entries that follow
it.

**`scripts/classify_ty_diagnostics.py` (new).** Holds the classification
as executable predicates rather than prose: eleven `Group` entries, each
pairing a rule set with a message regex and recording the discriminant
it keys on. The discriminant is load-bearing because most groups share a
rule with genuine defects — under `unknown-argument`, the
pydantic-settings `_secrets_dir` kwarg and a first-party `PMM` kwarg
differ only in the symbol the message names, and
`tests/app/sep/test_config.py` carries both. One group is additionally
confined to a set of paths: `Cannot resolve imported module` reads
identically for a golden-app module scaffolded at test time and for a
first-party import someone mistyped, so `absent-modules` matches only
under `tests/app/sep/apps/framework/golden/` and at
`app/sep/sync/syncers/system_facts/payload.py`. Three modes: `report`
prints the group table and the per-rule artifact/residual split,
`baseline` emits a fingerprint manifest, `check` reconciles a run
against one.

`check` is the gate, and it compares fingerprints rather than counts. A
count comparison cannot establish the ticket's central invariant: once a
suppression hides a first-party warning that row is simply absent, so a
change removing one artifact *and* one first-party diagnostic while an
unrelated new one appears reconciles to the expected total. `check`
instead takes the multiset difference over `(path, rule, message)` and
fails unless every diagnostic that stopped reporting is one the
classification marks as an artifact, naming any that is not. The
fingerprint is exactly what `classify()` reads, so two diagnostics
sharing one always share a verdict; folding the line and column away
costs the gate no soundness and lets it survive the reformatting the
suppression comments provoke, which would otherwise report every
diagnostic below an edited line as newly suppressed.

**Two neutralization mechanisms, chosen per `(file, rule)` pair.**
Eleven `[[tool.ty.overrides]]` entries in `pyproject.toml` cover the 59
pairs whose every hit of that rule in that file is an artifact — 264
hits. Each entry names explicit file paths rather than a directory
wildcard, softens exactly one rule, and carries the reason. The 27 pairs
that mix take 182 per-site `# ty: ignore[rule]` comments instead,
because an override cannot discriminate within a file and would suppress
the genuine defects alongside. No pair gets both: an override makes a
same-rule comment unused, and `unused-ignore-comment` is unlisted in
`[tool.ty.rules]` and so inherits `all = "error"` — which is also what
makes the comments self-cleaning as the tree drifts.

**`docs/development/ty-policy.md`** gains a *Neutralized
dependency-typing artifacts* section recording the group table with each
discriminant and mechanism, the per-rule residual next to the commit it
was measured at, and the commands that reproduce the split. The existing
per-rule tables and sampling record are untouched; the recorded-baseline
section gains a pointer, since its 3,926 figure now describes a
configuration that has moved.

**Reproducing the claim** (the manifest is a build artifact, not a
committed file):

```bash
# Capture the base run first: the classifier does not exist at the merge base.
git switch --detach $(git merge-base HEAD origin/main)
ty check --output-format concise > /tmp/ty-base.txt
git switch -
python3 scripts/classify_ty_diagnostics.py baseline --from /tmp/ty-base.txt \
    --out /tmp/ty-baseline.json
python3 scripts/classify_ty_diagnostics.py check --baseline /tmp/ty-baseline.json
```

Measured at merge-base 8ab1800 with ty 0.0.49: 4,072 → 3,626, all 446
removed rows are warnings, all 366 `error`-severity diagnostics survive
untouched, and `check` exits 0 with an empty `RETAINED` list.

**What is *not* neutralized.** The sqlmodel-vs-sqlalchemy `AsyncSession`
mismatch — 201 `invalid-argument-type` hits expecting
`sqlmodel.ext.asyncio.session.AsyncSession` and finding the `sqlalchemy`
one — is first-party and stays reportable. The two classes are not
parallel declarations by two libraries: the sqlmodel class subclasses
the sqlalchemy one, adding `exec`, and `app/core/db/crud.py:40` imports
the subclass so `BaseManager` can call `session.exec(...)` at
`app/core/db/crud.py:227`. A value typed as the supertype cannot satisfy
a parameter requiring the subtype, so ty is right; every hit arises
where a test file or helper annotates its own `session` parameter with
the sqlalchemy import.

Author: yyyyyyyan

app/celery.py

@@ -42,7 +42,7 @@
 celery = Celery("sep", **settings.CELERY.model_dump())
 
 celery.loop = asyncio.new_event_loop()
-asyncio.set_event_loop(celery.loop)
+asyncio.set_event_loop(celery.loop)  # ty: ignore[unresolved-attribute]
 
 
 @setup_logging.connect
@@ -56,7 +56,7 @@ def init_child_event_loop(**kwargs: Any) -> None:
     """Initialize a new event loop for each worker process."""
     logger.debug("Initializing new event loop for worker process")
     celery.loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(celery.loop)
+    asyncio.set_event_loop(celery.loop)  # ty: ignore[unresolved-attribute]
 
 
 CORRELATION_ID_HEADER_KEY = "correlation_id"

app/core/alerts/config.py

@@ -50,11 +50,11 @@ class AlertSettings(BaseYamlSettings):
     """
 
     SETTINGS_PREFIXES: ClassVar[list[str]] = ["ALERTING"]
-    PROVIDERS: set[BaseAlertProvider] = hot_field(
+    PROVIDERS: set[BaseAlertProvider] = hot_field(  # ty: ignore[invalid-assignment]
         set(), materializer=materialize_via_owning_model
     )
-    SOURCE_PREFIX: str = hot_field("")
-    SOURCE_SUFFIX: str = hot_field("")
+    SOURCE_PREFIX: str = hot_field("")  # ty: ignore[invalid-assignment]
+    SOURCE_SUFFIX: str = hot_field("")  # ty: ignore[invalid-assignment]
 
     @field_validator("PROVIDERS", mode="before")
     @classmethod

app/core/config.py

@@ -355,12 +355,22 @@ class PMMSettings(BaseLowercaseModel):
     """
 
     endpoint: StrCredentialHttpUrl | None = None
-    frontend: StrHttpUrl | None = hot_field(None, advanced=True)
+    frontend: StrHttpUrl | None = hot_field(  # ty: ignore[invalid-assignment]
+        None, advanced=True
+    )
     api_key: SecretStr | None = None
-    verify_ssl: bool = hot_field(default=True, advanced=True)
-    execution_target: str | None = hot_field(None, advanced=True)
-    annotations_enabled: bool = hot_field(default=False, advanced=True)
-    annotations_timeout: PositiveInt = hot_field(5, advanced=True)
+    verify_ssl: bool = hot_field(  # ty: ignore[invalid-assignment]
+        default=True, advanced=True
+    )
+    execution_target: str | None = hot_field(  # ty: ignore[invalid-assignment]
+        None, advanced=True
+    )
+    annotations_enabled: bool = hot_field(  # ty: ignore[invalid-assignment]
+        default=False, advanced=True
+    )
+    annotations_timeout: PositiveInt = hot_field(  # ty: ignore[invalid-assignment]
+        5, advanced=True
+    )
 
     @model_validator(mode="after")
     def _default_frontend_to_endpoint(self) -> Self:
@@ -423,7 +433,9 @@ class SettingsOverrideOptions(BaseCaseInsensitiveModel):
         seconds=30
     )
     REFRESHER_ENABLED: bool = True
-    ALLOWED_KEYS: set[SettingsOverrideKey] | None = not_overridable_field(None)
+    ALLOWED_KEYS: set[SettingsOverrideKey] | None = (  # ty: ignore[invalid-assignment]
+        not_overridable_field(None)
+    )
 
 
 _REMOVED_SETTINGS_OVERRIDE_KEYS = {
@@ -604,14 +616,14 @@ class Settings(BaseYamlSettings):
     ALLOW_CONCURRENT_SESSIONS: bool = False
     SECRET_KEY: SecretStr = SecretStr(secrets.token_urlsafe(32))
     SEP_INTERNAL_TOKEN: SecretStr | None = None
-    LOGGING: LogLevel = hot_field(LogLevel.WARNING)
+    LOGGING: LogLevel = hot_field(LogLevel.WARNING)  # ty: ignore[invalid-assignment]
     LOGGING_CONFIG: dict[str, Any] = {}
     SSL_CAFILE: RelativeFilePathField | None = None
     BASE_URL: URL | None = None
     BACKEND_CORS_ORIGINS: list[StrHttpUrl] | None = None
     ALLOWED_HOSTS: list[str] = []
     SECURITY_HEADERS: SecurityHeadersOptions | None = SecurityHeadersOptions()
-    PMM: PMMSettings = hot_field(PMMSettings())
+    PMM: PMMSettings = hot_field(PMMSettings())  # ty: ignore[invalid-assignment]
     SETTINGS_OVERRIDE: SettingsOverrideOptions = SettingsOverrideOptions()
     _CLIENT_REGISTRY: ClientRegistry = ClientRegistry()
 

app/sep/app_drain.py

@@ -194,7 +194,9 @@ def record_task_start(task_id: str, task: Any, **_: Any) -> None:
     app_key = getattr(task, _OWNER_APP_KEY_ATTR, None)
     if app_key is None:
         return
-    celery.loop.run_until_complete(_record_start(app_key, task_id))
+    celery.loop.run_until_complete(  # ty: ignore[unresolved-attribute]
+        _record_start(app_key, task_id)
+    )
 
 
 @task_postrun.connect
@@ -203,13 +205,17 @@ def record_task_end(task_id: str, task: Any, **_: Any) -> None:
     app_key = getattr(task, _OWNER_APP_KEY_ATTR, None)
     if app_key is None:
         return
-    celery.loop.run_until_complete(_record_end(app_key, task_id))
+    celery.loop.run_until_complete(  # ty: ignore[unresolved-attribute]
+        _record_end(app_key, task_id)
+    )
 
 
 @celery.task
 def reconcile_disabling_apps() -> None:
     """Prune orphaned running-task rows and finalize drained apps (safety net)."""
-    celery.loop.run_until_complete(_reconcile_disabling_apps())
+    celery.loop.run_until_complete(  # ty: ignore[unresolved-attribute]
+        _reconcile_disabling_apps()
+    )
 
 
 async def _reconcile_disabling_apps() -> None:

app/sep/apps/alerts/config.py

@@ -41,11 +41,11 @@ class AlertsSettings(BaseYamlSettings):
     """
 
     SETTINGS_PREFIXES: ClassVar[list[str]] = ["SEP", "ALERTS"]
-    BACKUP_INTERVAL: IntervalSchedule = hot_field(
+    BACKUP_INTERVAL: IntervalSchedule = hot_field(  # ty: ignore[invalid-assignment]
         IntervalSchedule(every=24, period=Period.HOURS)
     )
-    BACKUP_RETENTION: PositiveInt = hot_field(10)
-    ALERT_FOLDER_NAME: str = hot_field("SEP Alerts")
+    BACKUP_RETENTION: PositiveInt = hot_field(10)  # ty: ignore[invalid-assignment]
+    ALERT_FOLDER_NAME: str = hot_field("SEP Alerts")  # ty: ignore[invalid-assignment]
 
 
 alerts_settings: AlertsSettings = OverridableSettingsProxy(

app/sep/apps/inventory/config.py

@@ -59,12 +59,20 @@ class InventoryAppSettings(BaseYamlSettings):
     """
 
     SETTINGS_PREFIXES: ClassVar[list[str]] = ["SEP", "INVENTORY"]
-    COLLECTION_INTERVAL: ManageableInterval | None = hot_field(None)
-    COLLECTION_RETENTION: Annotated[timedelta, Gt(timedelta(0))] = hot_field(
-        timedelta(days=30)
+    COLLECTION_INTERVAL: ManageableInterval | None = (  # ty: ignore[invalid-assignment]
+        hot_field(None)
+    )
+    COLLECTION_RETENTION: Annotated[
+        timedelta, Gt(timedelta(0))
+    ] = (  # ty: ignore[invalid-assignment]
+        hot_field(timedelta(days=30))
+    )
+    COLLECTION_BATCH_SIZE: PositiveInt = hot_field(  # ty: ignore[invalid-assignment]
+        500, advanced=True
+    )
+    COLLECTION_MAX_BATCHES: PositiveInt = hot_field(  # ty: ignore[invalid-assignment]
+        20, advanced=True
     )
-    COLLECTION_BATCH_SIZE: PositiveInt = hot_field(500, advanced=True)
-    COLLECTION_MAX_BATCHES: PositiveInt = hot_field(20, advanced=True)
 
 
 inventory_app_settings: InventoryAppSettings = OverridableSettingsProxy(

app/sep/config.py

@@ -471,8 +471,12 @@ class DeliveryPlanInputs(BaseModel):
     :param secrets: Values for the secret names the baked plan declares.
     """
 
-    endpoint: CredentialHttpUrl | None = not_overridable_field(None)
-    secrets: dict[str, SecretStr] = not_overridable_field({})
+    endpoint: CredentialHttpUrl | None = (  # ty: ignore[invalid-assignment]
+        not_overridable_field(None)
+    )
+    secrets: dict[str, SecretStr] = (  # ty: ignore[invalid-assignment]
+        not_overridable_field({})
+    )
 
     @field_validator("secrets")
     @classmethod
@@ -633,16 +637,22 @@ class SEPSettings(BaseYamlAppSettings):
     SETTINGS_PREFIXES: ClassVar[list[str]] = ["SEP"]
     UVICORN_PORT: int = 8000
     ROOT_PATH: URIPathPrefix = ""
-    SESSION_REFRESH: CookieOptions = nested_overridable_field(
-        CookieOptions(
-            COOKIE_NAME="refreshToken",
-            PATH="/api/oauth",
-        ),
-        advanced=True,
+    SESSION_REFRESH: CookieOptions = (  # ty: ignore[invalid-assignment]
+        nested_overridable_field(
+            CookieOptions(
+                COOKIE_NAME="refreshToken",
+                PATH="/api/oauth",
+            ),
+            advanced=True,
+        )
     )
     ALERT_DEFINITIONS_DIR: RelativeDirectoryPathField | None = None
-    INVENTORY_ENDPOINT: CredentialHttpUrl = hot_field(..., advanced=True)
-    TASKS_ENDPOINT: CredentialHttpUrl = hot_field(..., advanced=True)
+    INVENTORY_ENDPOINT: CredentialHttpUrl = hot_field(  # ty: ignore[invalid-assignment]
+        ..., advanced=True
+    )
+    TASKS_ENDPOINT: CredentialHttpUrl = hot_field(  # ty: ignore[invalid-assignment]
+        ..., advanced=True
+    )
     APPS: UniqueList[App] = Field(
         default_factory=UniqueList,
         validation_alias=AliasChoices("APPS", "PLUGINS"),
@@ -651,21 +661,29 @@ class SEPSettings(BaseYamlAppSettings):
     DATABASE: DatabaseOptions = DatabaseOptions(NAME="sep.db")
     SYNCERS: UniqueList[SyncOptions] = UniqueList()
     SYNCER_EXTRA_KWARGS: SyncerExtraKwargs = SyncerExtraKwargs()
-    SYNC_REFRESH_TIME: int = hot_field(5)
-    DIAGNOSTICS_DELIVERY: DeliveryPlan | None = not_overridable_field(
-        None, advanced=True
+    SYNC_REFRESH_TIME: int = hot_field(5)  # ty: ignore[invalid-assignment]
+    DIAGNOSTICS_DELIVERY: DeliveryPlan | None = (  # ty: ignore[invalid-assignment]
+        not_overridable_field(None, advanced=True)
+    )
+    DIAGNOSTICS_DELIVERY_INPUTS: (
+        DeliveryPlanInputs | None
+    ) = (  # ty: ignore[invalid-assignment]
+        hot_field(None, materializer=materialize_delivery_plan_inputs, advanced=True)
     )
-    DIAGNOSTICS_DELIVERY_INPUTS: DeliveryPlanInputs | None = hot_field(
-        None, materializer=materialize_delivery_plan_inputs, advanced=True
+    APP_DRAIN: AppDrainSettings = (  # ty: ignore[invalid-assignment]
+        nested_overridable_field(AppDrainSettings())
+    )
+    ARTIFACT_DOWNLOAD_TTL: PositiveInt = hot_field(  # ty: ignore[invalid-assignment]
+        600, advanced=True
     )
-    APP_DRAIN: AppDrainSettings = nested_overridable_field(AppDrainSettings())
-    ARTIFACT_DOWNLOAD_TTL: PositiveInt = hot_field(600, advanced=True)
     # Plain fields rather than ``hot_field``: the readiness gate runs in a
     # pre-fork beat child, before the DB override refresher exists to serve one.
     API_READINESS_TIMEOUT: PositiveFloat = DEFAULT_API_READINESS_TIMEOUT
     API_READINESS_POLL_INTERVAL: PositiveFloat = DEFAULT_API_READINESS_POLL_INTERVAL
-    CONNECTIVITY_CHECK_DEFAULT: bool = hot_field(default=False)
-    AMBIENT_SESSION_SSO_ENABLED: bool = hot_field(
+    CONNECTIVITY_CHECK_DEFAULT: bool = hot_field(  # ty: ignore[invalid-assignment]
+        default=False
+    )
+    AMBIENT_SESSION_SSO_ENABLED: bool = hot_field(  # ty: ignore[invalid-assignment]
         default=False,
         description=(
             "Enable ambient Grafana-session SSO: sign an unauthenticated caller "
@@ -675,7 +693,7 @@ class SEPSettings(BaseYamlAppSettings):
             "the browser sends the session cookie to SEP."
         ),
     )
-    FOOTER_TEMPLATE: Template = hot_field(
+    FOOTER_TEMPLATE: Template = hot_field(  # ty: ignore[invalid-assignment]
         Template("$summary $version"),
         materializer=materialize_template,
         advanced=True,

app/sep/snippets/celery.py

@@ -55,7 +55,9 @@
 @celery.task
 def sync_snippets() -> None:
     """Define Celery task to sync snippets from `sep_setting.SNIPPETS.SNIPPETS_DIR`."""
-    celery.loop.run_until_complete(update_snippets())
+    celery.loop.run_until_complete(  # ty: ignore[unresolved-attribute]
+        update_snippets()
+    )
 
 
 async def update_snippets() -> None:

app/sep/snippets/config.py

@@ -398,23 +398,29 @@ class SnippetsSettings(BaseYamlSettings):
     # stores it as ``{"_url": ...}`` rather than a plain string, which then
     # coerces back into a broken ``URL``. Persist the raw string and
     # re-materialize through the owning model on load instead.
-    SNIPPETS_BASE_URL: URL | None = hot_field(
+    SNIPPETS_BASE_URL: URL | None = hot_field(  # ty: ignore[invalid-assignment]
         None, materializer=materialize_via_owning_model
     )
     META: SnippetsMetaOptions = SnippetsMetaOptions()
-    SYNC_FILTER: set[SnippetFilter] | None = hot_field(None)
+    SYNC_FILTER: set[SnippetFilter] | None = (  # ty: ignore[invalid-assignment]
+        hot_field(None)
+    )
     INTERPRETERS: OrderedDict[SnippetFilter, SnippetInterpreterConfig] = (
         DEFAULT_INTERPRETERS
     )
     USE_MAGIC: bool = False
-    SYNC_INTERVAL: IntervalSchedule = hot_field(
+    SYNC_INTERVAL: IntervalSchedule = hot_field(  # ty: ignore[invalid-assignment]
         IntervalSchedule(every=1, period=Period.HOURS)
     )
-    ENABLE_MANUAL_SYNC: bool = hot_field(default=False)
-    AUTO_APPROVE_BUILTIN_SNIPPETS: bool = hot_field(default=True)
+    ENABLE_MANUAL_SYNC: bool = hot_field(  # ty: ignore[invalid-assignment]
+        default=False
+    )
+    AUTO_APPROVE_BUILTIN_SNIPPETS: bool = hot_field(  # ty: ignore[invalid-assignment]
+        default=True
+    )
     SYNC_ON_STARTUP: bool = True
-    PREVIEW_MAX_CHARS: PositiveInt = hot_field(10000)
-    PREVIEW_MAX_LINES: PositiveInt = hot_field(500)
+    PREVIEW_MAX_CHARS: PositiveInt = hot_field(10000)  # ty: ignore[invalid-assignment]
+    PREVIEW_MAX_LINES: PositiveInt = hot_field(500)  # ty: ignore[invalid-assignment]
 
     @model_validator(mode="before")
     @classmethod

app/sep/snippets/models/snippet.py

@@ -883,7 +883,7 @@ class Snippet(BaseSnippet, BaseSQLModel, table=True):
 
     __table_args__ = (Index("ix_snippet_filename", "filename", unique=True),)
     approved_at: UTCDatetime | None = SQLField(
-        sa_type=DateTimeWithTimezone,
+        sa_type=DateTimeWithTimezone,  # ty: ignore[invalid-argument-type]
         default=None,
         index=True,
     )