1from __future__ import annotations
 2
 3from typing import Any, Literal, TypedDict
 4
 5Source = Literal["app", "package", ""]
 6CheckStatus = Literal["ok", "warning", "critical", "skipped", "error"]
 7# "warning" — items are actionable in user's code or as an app-level action.
 8# "operational" — items describe DB state the user can act on via SQL but
 9# can't currently express in their model code (ANALYZE, VACUUM, REINDEX,
10# autovacuum tuning). Rendered as context rather than alarms.
11CheckTier = Literal["warning", "operational"]
12PgssAvailability = Literal["usable", "not_installed", "no_permission"]
13
14
15class TableOwner(TypedDict):
16    package_label: str
17    source: Source
18    model_class: str  # e.g. "ProcessingResult" — empty if not resolvable
19    model_file: str  # absolute path to the .py file declaring the model
20
21
22class CheckItem(TypedDict):
23    table: str
24    name: str
25    detail: str
26    source: Source
27    package: str  # package label or ""
28    model_class: str  # Plain model class name; empty for non-table findings
29    model_file: str  # absolute path to the model's .py file; empty when unresolved
30    suggestion: str
31    caveats: list[str]  # cross-check context, populated by run_all_checks
32
33
34class CheckResult(TypedDict):
35    name: str
36    label: str
37    status: CheckStatus
38    summary: str
39    items: list[CheckItem]
40    message: str
41    tier: CheckTier
42
43
44class Informational(TypedDict):
45    """A numeric or string fact about the database that is always shown, never
46    warns. Used for context an agent may want to read but that isn't an
47    actionable finding on its own (e.g. hit ratios, xid age, connection
48    utilization)."""
49
50    name: str
51    label: str
52    value: Any
53    unit: str
54    note: str