from __future__ import annotations import argparse import json import mimetypes import os import re import signal import sqlite3 import sys import threading import time import uuid from collections import defaultdict from contextvars import ContextVar, Token from datetime import datetime, timedelta, timezone from http import HTTPStatus from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from math import ceil, isfinite from pathlib import Path from statistics import median from typing import Any from urllib.error import HTTPError, URLError from urllib.parse import parse_qs, quote, urlencode, urlparse from urllib.request import Request, urlopen from .auth import Auth0Authenticator, Auth0Settings, AuthError, AuthPrincipal from .catalog_metrics import aggregate_metric_values, project_catalog_metric_history from .catalog_timeline import project_catalog_timeline from .clinic_health_check import ( SUPPORTED_SQL_CHECK_SET, build_report_import, build_report_source_url, importable_check_names, ) from .database import ( connect_mysql, connect_sqlite, connection_dialect, database_description, finding_run_idempotency_key, warm_mysql_pool, ) from .i18n import localize_error, negotiate_locale, translate from .tidb_schema import SCHEMA_VERSION, ensure_tidb_schema ROOT = Path(__file__).resolve().parents[2] WEB_DIR = ROOT / "frontend" / "dist" def load_dotenv() -> None: env_path = ROOT / ".env" if not env_path.exists(): return for raw_line in env_path.read_text(encoding="utf-8").splitlines(): line = raw_line.strip() if not line or line.startswith("#") or "=" not in line: continue key, value = line.split("=", 1) key = key.strip() value = value.strip().strip("'").strip('"') if key and key not in os.environ: os.environ[key] = value load_dotenv() def bounded_env_float(name: str, default: float, minimum: float, maximum: float) -> float: try: value = float(os.environ.get(name, default)) except (TypeError, ValueError): return default return min(max(value, minimum), maximum) def env_flag(name: str, default: bool = False) -> bool: value = os.environ.get(name) if value is None: return default return value.strip().lower() in {"1", "true", "yes", "on"} CONFIGURED_DB_PATH = Path( os.environ.get("SQL_CATALOG_DB", ROOT / "data" / "sql_catalog.sqlite3") ) # Tests and one-time migration tools override DB_PATH to point at an isolated # SQLite file. Normal development and deployment use DATABASE_URL when set. DB_PATH = CONFIGURED_DB_PATH DATABASE_URL = os.environ.get("SQL_CATALOG_DATABASE_URL") DATABASE_PASSWORD_ENV = os.environ.get( "SQL_CATALOG_DATABASE_PASSWORD_ENV", "DB_PASSWD" ) HOST = os.environ.get("SQL_CATALOG_HOST", "127.0.0.1") PORT = int(os.environ.get("SQL_CATALOG_PORT", "8765")) CORS_ALLOWED_ORIGINS = frozenset( origin.strip().rstrip("/") for origin in os.environ.get( "SQL_CATALOG_CORS_ALLOWED_ORIGINS", ( "http://localhost:5173,http://127.0.0.1:5173" if HOST in {"127.0.0.1", "localhost", "::1"} else "" ), ).split(",") if origin.strip() ) HISTORICAL_REPLAY_HEADER = "X-SQL-Catalog-Replay-At" ALLOW_HISTORICAL_REPLAY = env_flag( "SQL_CATALOG_ALLOW_HISTORICAL_REPLAY", HOST in {"127.0.0.1", "localhost", "::1"}, ) CLINIC_ENV = os.environ.get("CLINIC_ENV", "prod").lower() CLINIC_ENDPOINT = os.environ.get( "CLINIC_ENDPOINT", { "dev": "https://dev-clinic.pingcap.com", "staging": "https://staging-clinic.pingcap.com", "prod": "https://clinic.pingcap.com", }.get(CLINIC_ENV, "https://clinic.pingcap.com"), ).rstrip("/") CLINIC_DATA_PROXY_API_BASE = os.environ.get( "CLINIC_DATA_PROXY_API_BASE", f"{CLINIC_ENDPOINT}/data-proxy/api/v1" ).rstrip("/") CLINIC_API_BASE = os.environ.get( "CLINIC_API_BASE", f"{CLINIC_ENDPOINT}/clinic/api/v1" ).rstrip("/") CLINIC_PORTAL_BASE = os.environ.get( "CLINIC_PORTAL_BASE", f"{CLINIC_ENDPOINT}/portal/#" ).rstrip("/") CLINIC_API_KEY = os.environ.get("CLINIC_API_KEY") CLINIC_API_TIMEOUT_SECONDS = bounded_env_float( "CLINIC_API_TIMEOUT_SECONDS", 30.0, 1.0, 120.0 ) LEGACY_USER_ID = os.environ.get("SQL_CATALOG_LEGACY_USER_ID", "demo-user") REQUEST_USER: ContextVar[dict[str, Any] | None] = ContextVar( "sql_catalog_request_user", default=None ) _AUTHENTICATOR: Auth0Authenticator | None = None _AUTHENTICATOR_LOCK = threading.Lock() _AUTH_USER_CACHE: dict[str, tuple[float, dict[str, Any]]] = {} _AUTH_USER_CACHE_LOCK = threading.Lock() _HEALTH_CHECK_IMPORT_WAKE = threading.Event() _HEALTH_CHECK_IMPORT_STOP = threading.Event() _HEALTH_CHECK_IMPORT_WORKER: threading.Thread | None = None _HEALTH_CHECK_IMPORT_WORKER_LOCK = threading.Lock() DEFAULT_SQL_REVIEW_POLICY = { "critical_finding_triggers_review": True, "finding_count_threshold": 5, "finding_window_days": 14, } FINDING_SIGNAL_ANOMALY = "anomaly" FINDING_SIGNAL_RANKING_OBSERVATION = "ranking_observation" FINDING_SIGNAL_CLASSES = frozenset( {FINDING_SIGNAL_ANOMALY, FINDING_SIGNAL_RANKING_OBSERVATION} ) REVIEW_PRIORITY_TIERS = ("p0", "p1") RECOMMENDED_REVIEW_BATCH_SIZE = 8 REVIEW_FOCUS_WINDOW_DAYS = 7 IMPACT_RANK_DIMENSIONS = frozenset( { "top_by_count", "top_by_total_latency", "top_by_total_keys", "top_by_process_keys", "top_by_request_count", "top_by_sum_ru", } ) GOVERNANCE_REOPEN_POLICIES = frozenset( {"any_anomaly", "meaningful_change", "manual_review"} ) GOVERNANCE_MEMORY_CONCLUSIONS = frozenset( { "watch", "no_action", "no_intervention", "expected_workload", "known_stable", "not_optimizable", "accepted_risk", "false_positive", "obsolete", } ) # These statement families can be slow, but they do not represent a reusable # application SQL optimization target. Keep their evidence for audit and # metrics, while excluding them from automatic review and cluster health. NON_TUNABLE_SQL_STATEMENT_TYPES = frozenset( { "admin", "alter", "analyze", "backup", "begin", "check", "commit", "create", "deallocate", "desc", "describe", "drop", "execute", "explain", "flush", "grant", "kill", "optimize", "prepare", "release", "rename", "repair", "restore", "revoke", "rollback", "savepoint", "set", "show", "start", "truncate", "use", } ) SEVERITY_RANK = { "info": 0, "low": 1, "medium": 2, "high": 3, "critical": 4, } SEVERITIES = frozenset(SEVERITY_RANK) DAY_BUCKET_SECONDS = 24 * 60 * 60 SOURCE_TYPES = frozenset({"inspection", "manual", "ai_agent", "integration"}) CLUSTER_SCOPE_VISIBILITIES = frozenset({"private", "public"}) CLUSTER_SCOPE_MEMBERSHIP_MODES = frozenset({"snapshot", "dynamic"}) FINDING_RUN_STATUSES = frozenset({"running", "success", "partial", "failed"}) HEALTH_CHECK_REPORT_STATUSES = frozenset( {"pending", "running", "partial", "success", "partial_failed", "failed"} ) HEALTH_CHECK_SYNC_STATES = frozenset({"syncing", "succeeded", "partial", "failed"}) SYMPTOM_DEFINITION_STATUSES = frozenset({"active", "deprecated"}) ASSESSMENT_METHODS = frozenset({"rule", "model", "human", "external"}) CATALOG_POSTURE_STATES = frozenset( { "needs_review", "in_treatment", "watching", "no_intervention", "registered", "archived", } ) CATALOG_ATTENTION_LEVELS = frozenset({"urgent", "attention", "normal", "none"}) TREATMENT_STATES = frozenset({"active", "completed", "cancelled"}) TREATMENT_STAGES = ( "assessment", "planning", "alignment", "execution", "observation", "completed", ) TREATMENT_OUTCOMES = frozenset( { "fixed", "improved", "unchanged", "not_optimizable", "accepted_risk", "failed", "cancelled", "superseded", } ) RECORD_TYPES = frozenset( { "triage_record", "analysis_record", "proposal_record", "no_action_record", "customer_sync_record", "customer_feedback_record", "execution_record", "observation_record", "outcome_record", "postmortem_record", "comment", } ) RECORD_STATES = frozenset({"draft", "ready", "reviewed", "obsolete"}) RECORD_VISIBILITIES = frozenset({"internal", "customer_visible"}) MAX_REQUEST_BYTES = 2 * 1024 * 1024 FINDING_INPUT_FIELDS = frozenset( { "source", "source_type", "source_event_id", "source_batch_id", "source_run_id", "org_id", "project_id", "cluster_id", "sql_digest", "normalized_sql", "reported_at", "observed_at", "time_window_start", "time_window_end", "detector_code", "detector_version", "metric_schema_version", "metrics", "dimensions", "evidence_refs", "raw_payload", "symptoms", "created_by", } ) FINDING_SYMPTOM_INPUT_FIELDS = frozenset( { "code", "severity", "confidence", "signal_codes", "metric_keys", "evidence_refs", "assessment", } ) FINDING_ASSESSMENT_INPUT_FIELDS = frozenset( { "method", "summary", "rule_code", "rule_version", "policy_id", "policy_version", "policy_url", "parameters", } ) FINDING_BATCH_INPUT_FIELDS = frozenset( {"source", "source_type", "source_batch_id", "defaults", "findings", "created_by"} ) FINDING_DELETION_FILTER_FIELDS = frozenset( { "q", "org_id", "project_id", "cluster_id", "source", "source_type", "severity", "detector_code", "sql_digest", "source_event_id", "source_batch_id", "source_run_id", "symptom_code", "symptom_severity", "new_digest", "created_catalog_item", "created_from", "created_to", "from", "to", "time_basis", "has_active_treatment", "has_triage_record", } ) FINDING_RUN_INPUT_FIELDS = frozenset( { "source", "source_type", "source_run_id", "org_id", "project_id", "cluster_id", "time_window_start", "time_window_end", "status", "detector_version", "expected_detector_count", "completed_detector_count", "metadata", "started_at", "completed_at", } ) CATALOG_ITEM_INPUT_FIELDS = frozenset( { "org_id", "project_id", "cluster_id", "sql_digest", "normalized_sql", "registration_reason", "source_reference", "source_url", "note", "initial_action", "owner", "created_by", } ) CATALOG_REGISTRATION_REASONS = frozenset( {"customer_ticket", "high_frequency", "proactive_watch", "other"} ) CATALOG_INITIAL_ACTIONS = frozenset({"register_only", "watch"}) DEFAULT_SYMPTOM_DEFINITIONS = ( { "code": "slow_query_frequency", "name": "Frequent slow execution", "category": "latency", "description": "The SQL digest is observed as a slow query unusually often for the source context.", }, { "code": "high_total_latency", "name": "High latency contribution", "category": "latency", "description": "The SQL digest contributes excessive individual or accumulated execution latency.", }, { "code": "large_key_scan", "name": "Large key scan", "category": "efficiency", "description": "The SQL digest scans or processes an excessive number of keys.", }, { "code": "high_kv_request_count", "name": "High KV request count", "category": "efficiency", "description": "The SQL digest produces an excessive number of requests to the KV layer.", }, { "code": "tikv_cpu_hotspot", "name": "TiKV CPU hotspot", "category": "resource", "description": "The SQL digest is attributed to a material TiKV CPU hotspot.", }, { "code": "unclassified_sql_anomaly", "name": "Unclassified SQL anomaly", "category": "unclassified", "description": "A manually reported SQL anomaly that requires a written assessment and later classification.", }, ) SYMPTOM_NAMES = { definition["code"]: definition["name"] for definition in DEFAULT_SYMPTOM_DEFINITIONS } TREATMENT_STAGE_TRANSITIONS = { "assessment": {"planning"}, "planning": {"assessment", "alignment", "execution"}, "alignment": {"planning", "execution"}, "execution": {"planning"}, "observation": {"execution"}, "completed": set(), } def now_iso() -> str: return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z") def current_user() -> dict[str, Any] | None: return REQUEST_USER.get() def current_user_id() -> str: user = current_user() return str(user["id"]) if user else LEGACY_USER_ID def current_actor() -> str: return current_user_id() if current_user() else "api" def since_iso(days: int) -> str: return ( datetime.now(timezone.utc).replace(microsecond=0) - timedelta(days=days) ).isoformat().replace("+00:00", "Z") def duration_hours(start: str | None, end: str | None = None) -> float | None: if not start: return None try: start_value = datetime.fromisoformat(start.replace("Z", "+00:00")) end_value = datetime.fromisoformat((end or now_iso()).replace("Z", "+00:00")) except (TypeError, ValueError): return None return round(max(0.0, (end_value - start_value).total_seconds() / 3600), 1) def new_id(prefix: str) -> str: return f"{prefix}_{uuid.uuid4().hex}" def json_dumps(value: Any) -> str: return json.dumps(value, ensure_ascii=False, separators=(",", ":")) def json_loads(value: str | None, fallback: Any) -> Any: if value is None or value == "": return fallback try: return json.loads(value) except json.JSONDecodeError: return fallback def ensure_list(value: Any) -> list[Any]: if value is None: return [] if isinstance(value, list): return value return [value] def ensure_dict(value: Any) -> dict[str, Any]: if isinstance(value, dict): return value return {} def parse_iso(value: Any, field: str, required: bool = False) -> str | None: if value is None or value == "": if required: raise ValueError(f"{field} is required") return None if not isinstance(value, str) or len(value) > 64: raise ValueError(f"{field} must be an ISO 8601 string") try: parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) except ValueError as exc: raise ValueError(f"{field} must be an ISO 8601 string") from exc if parsed.tzinfo is None: parsed = parsed.replace(tzinfo=timezone.utc) return parsed.astimezone(timezone.utc).isoformat().replace("+00:00", "Z") def intake_timestamp(received_at: str | None = None) -> str: if received_at is None: return now_iso() return str(parse_iso(received_at, "received_at", required=True)) def historical_replay_at(value: str | None) -> str | None: if not value: return None if not ALLOW_HISTORICAL_REPLAY: raise PermissionError("Historical replay is disabled") replay_at = str(parse_iso(value, HISTORICAL_REPLAY_HEADER, required=True)) replay_datetime = datetime.fromisoformat(replay_at.replace("Z", "+00:00")) if replay_datetime > datetime.now(timezone.utc) + timedelta(minutes=5): raise ValueError(f"{HISTORICAL_REPLAY_HEADER} must not be in the future") return replay_at def require_string( payload: dict[str, Any], field: str, *, max_length: int, allow_empty: bool = False, ) -> str: value = payload.get(field) if value is None: raise ValueError(f"{field} is required") if not isinstance(value, str): raise ValueError(f"{field} must be a string") value = value.strip() if not value and not allow_empty: raise ValueError(f"{field} is required") if len(value) > max_length: raise ValueError(f"{field} must be at most {max_length} characters") return value def optional_string(value: Any, field: str, max_length: int) -> str | None: if value is None or value == "": return None if not isinstance(value, str): raise ValueError(f"{field} must be a string") value = value.strip() if len(value) > max_length: raise ValueError(f"{field} must be at most {max_length} characters") return value def positive_int(value: Any, default: int, maximum: int) -> int: try: parsed = int(value) except (TypeError, ValueError): return default return min(max(parsed, 0), maximum) def reject_unknown_fields( value: dict[str, Any], allowed: frozenset[str], object_name: str ) -> None: unknown = sorted(set(value) - allowed) if unknown: raise ValueError(f"{object_name} contains unknown fields: {', '.join(unknown)}") def use_configured_database_url() -> bool: # Existing tests override DB_PATH and should remain hermetic even when the # developer's .env points local development at TiDB. return bool(DATABASE_URL and DB_PATH == CONFIGURED_DB_PATH) def get_conn() -> Any: if use_configured_database_url(): return connect_mysql(str(DATABASE_URL), DATABASE_PASSWORD_ENV) if DB_PATH != CONFIGURED_DB_PATH: return connect_sqlite(DB_PATH) raise RuntimeError( "SQL_CATALOG_DATABASE_URL is required; SQLite is supported only by " "isolated tests and the one-time migration tool" ) def dialect_sql(conn: Any, sqlite_sql: str, mysql_sql: str) -> str: return mysql_sql if connection_dialect(conn) == "mysql" else sqlite_sql def insert_ignore_sql(conn: Any, sql: str) -> str: if connection_dialect(conn) == "mysql": return sql.replace("INSERT OR IGNORE", "INSERT IGNORE", 1) return sql def row_to_user(row: Any) -> dict[str, Any]: return { "id": row["id"], "email": row["email"], "email_verified": bool(row["email_verified"]), "name": row["name"], "picture_url": row["picture_url"], "role": row["role"], "status": row["status"], "last_login_at": row["last_login_at"], "created_at": row["created_at"], "updated_at": row["updated_at"], } def migrate_legacy_user_ownership(conn: Any, legacy_id: str, user_id: str) -> None: if not legacy_id or legacy_id == user_id: return for table, column in ( ("cluster_scopes", "owner_id"), ("groups", "owner_id"), ("catalog_items", "owner"), ("treatments", "owner"), ("treatments", "assignee"), ("records", "created_by"), ("findings", "created_by"), ("findings", "deleted_by"), ("finding_deletions", "requested_by"), ("timeline_events", "actor"), ("health_check_report_syncs", "requested_by"), ("cluster_sql_review_policies", "updated_by"), ("cluster_sql_health_owners", "assigned_by"), ): conn.execute( f"UPDATE `{table}` SET `{column}` = ? WHERE `{column}` = ?", (user_id, legacy_id), ) legacy_preference = conn.execute( "SELECT * FROM user_preferences WHERE owner_id = ?", (legacy_id,) ).fetchone() current_preference = conn.execute( "SELECT * FROM user_preferences WHERE owner_id = ?", (user_id,) ).fetchone() if legacy_preference and current_preference: if not current_preference["default_cluster_scope_id"]: conn.execute( "UPDATE user_preferences SET default_cluster_scope_id = ?, updated_at = ? " "WHERE owner_id = ?", ( legacy_preference["default_cluster_scope_id"], legacy_preference["updated_at"], user_id, ), ) conn.execute("DELETE FROM user_preferences WHERE owner_id = ?", (legacy_id,)) elif legacy_preference: conn.execute( "UPDATE user_preferences SET owner_id = ? WHERE owner_id = ?", (user_id, legacy_id), ) legacy_settings = conn.execute( "SELECT * FROM user_scope_settings WHERE owner_id = ?", (legacy_id,) ).fetchone() current_settings = conn.execute( "SELECT * FROM user_scope_settings WHERE owner_id = ?", (user_id,) ).fetchone() if legacy_settings and current_settings: conn.execute("DELETE FROM user_scope_settings WHERE owner_id = ?", (legacy_id,)) elif legacy_settings: conn.execute( "UPDATE user_scope_settings SET owner_id = ? WHERE owner_id = ?", (user_id, legacy_id), ) for row in conn.execute( "SELECT id, scope_type, scope_id FROM followed_scopes WHERE owner_id = ?", (legacy_id,), ).fetchall(): duplicate = conn.execute( "SELECT id FROM followed_scopes " "WHERE owner_id = ? AND scope_type = ? AND scope_id = ?", (user_id, row["scope_type"], row["scope_id"]), ).fetchone() if duplicate: conn.execute("DELETE FROM followed_scopes WHERE id = ?", (row["id"],)) else: conn.execute( "UPDATE followed_scopes SET owner_id = ? WHERE id = ?", (user_id, row["id"]), ) for row in conn.execute( "SELECT cluster_id FROM cluster_sql_health_owners WHERE owner_id = ?", (legacy_id,), ).fetchall(): duplicate = conn.execute( "SELECT 1 FROM cluster_sql_health_owners " "WHERE cluster_id = ? AND owner_id = ?", (row["cluster_id"], user_id), ).fetchone() if duplicate: conn.execute( "DELETE FROM cluster_sql_health_owners " "WHERE cluster_id = ? AND owner_id = ?", (row["cluster_id"], legacy_id), ) else: conn.execute( "UPDATE cluster_sql_health_owners SET owner_id = ? " "WHERE cluster_id = ? AND owner_id = ?", (user_id, row["cluster_id"], legacy_id), ) def bootstrap_auth_user(conn: Any) -> None: email = os.environ.get("AUTH0_BOOTSTRAP_EMAIL", "").strip().lower() if not email: return timestamp = now_iso() row = conn.execute( "SELECT * FROM users WHERE LOWER(email) = ?", (email,) ).fetchone() if row: user_id = row["id"] if row["role"] != "admin": conn.execute( "UPDATE users SET role = 'admin', updated_at = ? WHERE id = ?", (timestamp, user_id), ) else: user_id = new_id("usr") name = os.environ.get("AUTH0_BOOTSTRAP_NAME", "").strip() if not name: name = email.split("@", 1)[0].replace(".", " ").replace("_", " ").title() conn.execute( """ INSERT INTO users (id, auth0_subject, email, email_verified, name, picture_url, role, status, last_login_at, created_at, updated_at) VALUES (?, NULL, ?, 0, ?, NULL, 'admin', 'active', NULL, ?, ?) """, (user_id, email, name, timestamp, timestamp), ) migrate_legacy_user_ownership(conn, LEGACY_USER_ID, user_id) def ensure_authenticated_user(principal: AuthPrincipal) -> dict[str, Any]: now = time.monotonic() with _AUTH_USER_CACHE_LOCK: cached = _AUTH_USER_CACHE.get(principal.subject) if cached and cached[0] > now: return cached[1] timestamp = now_iso() with get_conn() as conn: row = conn.execute( "SELECT * FROM users WHERE auth0_subject = ?", (principal.subject,) ).fetchone() if not row: row = conn.execute( "SELECT * FROM users WHERE LOWER(email) = ?", (principal.email,) ).fetchone() if row and row["auth0_subject"] not in {None, "", principal.subject}: raise AuthError(403, "account_not_allowed", "This email is linked to another identity") if row and row["status"] != "active": raise AuthError(403, "account_disabled", "This SQL Catalog account is disabled") if row: user_id = row["id"] conn.execute( """ UPDATE users SET auth0_subject = ?, email = ?, email_verified = 1, name = ?, picture_url = ?, last_login_at = ?, updated_at = ? WHERE id = ? """, ( principal.subject, principal.email, principal.name, principal.picture_url, timestamp, timestamp, user_id, ), ) else: user_id = new_id("usr") conn.execute( """ INSERT INTO users (id, auth0_subject, email, email_verified, name, picture_url, role, status, last_login_at, created_at, updated_at) VALUES (?, ?, ?, 1, ?, ?, 'member', 'active', ?, ?, ?) """, ( user_id, principal.subject, principal.email, principal.name, principal.picture_url, timestamp, timestamp, timestamp, ), ) row = conn.execute("SELECT * FROM users WHERE id = ?", (user_id,)).fetchone() user = row_to_user(row) with _AUTH_USER_CACHE_LOCK: _AUTH_USER_CACHE[principal.subject] = (now + 30.0, user) return user def list_users() -> dict[str, Any]: with get_conn() as conn: rows = conn.execute( """ SELECT * FROM users WHERE status = 'active' ORDER BY LOWER(name), LOWER(email), id """ ).fetchall() items = [row_to_user(row) for row in rows] return {"items": items, "total": len(items)} def get_authenticator() -> Auth0Authenticator: global _AUTHENTICATOR if _AUTHENTICATOR is not None: return _AUTHENTICATOR with _AUTHENTICATOR_LOCK: if _AUTHENTICATOR is None: _AUTHENTICATOR = Auth0Authenticator(Auth0Settings.from_env()) return _AUTHENTICATOR def bind_request_actor(payload: dict[str, Any]) -> dict[str, Any]: """Replace client-supplied audit identities with the authenticated user.""" actor = current_user_id() audit_fields = ("actor", "created_by", "deleted_by", "restored_by") for field in audit_fields: if field in payload: payload[field] = actor defaults = payload.get("defaults") if isinstance(defaults, dict) and "created_by" in defaults: defaults["created_by"] = actor findings = payload.get("findings") if isinstance(findings, list): for finding in findings: if isinstance(finding, dict) and "created_by" in finding: finding["created_by"] = actor return payload def timeline_sequence_sql(conn: Any, alias: str | None = None) -> str: prefix = f"{alias}." if alias else "" column = "event_sequence" if connection_dialect(conn) == "mysql" else "rowid" return f"{prefix}{column}" def table_columns(conn: sqlite3.Connection, table: str) -> set[str]: return {str(row["name"]) for row in conn.execute(f"PRAGMA table_info({table})")} def migrate_catalog_item_posture_schema(conn: sqlite3.Connection) -> None: columns = table_columns(conn, "catalog_items") if not columns or "status" not in columns: return if "archived_at" not in columns: conn.execute("ALTER TABLE catalog_items ADD COLUMN archived_at TEXT") rows = conn.execute( "SELECT id, status, owner, updated_at FROM catalog_items" ).fetchall() for row in rows: status = str(row["status"] or "") if status == "archived": conn.execute( "UPDATE catalog_items SET archived_at = COALESCE(archived_at, ?) WHERE id = ?", (row["updated_at"], row["id"]), ) continue if status == "reviewing": # The old mutable status represented work intent rather than a # durable domain fact. Migrated items return to a derived posture. continue if status not in {"watching", "no_action_needed"}: continue completed = conn.execute( """ SELECT t.id FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? WHERE t.state IN ('completed', 'cancelled') ORDER BY t.completed_at DESC, t.updated_at DESC LIMIT 1 """, (row["id"],), ).fetchone() registration = conn.execute( f""" SELECT payload_json FROM timeline_events WHERE target_type = 'catalog_item' AND target_id = ? AND event_type = 'catalog_item_created' ORDER BY created_at ASC, {timeline_sequence_sql(conn)} ASC LIMIT 1 """, (row["id"],), ).fetchone() registration_payload = json_loads(registration["payload_json"], {}) if registration else {} if completed or ( status == "watching" and registration_payload.get("initial_action") == "watch" ): continue action = "watch" if status == "watching" else "no_action" record = conn.execute( """ SELECT rec.id FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' AND r.to_type = 'catalog_item' AND r.to_id = ? WHERE rec.record_type IN ('triage_record', 'no_action_record') ORDER BY rec.updated_at DESC, rec.id DESC LIMIT 1 """, (row["id"],), ).fetchone() reviewed_through = conn.execute( """ SELECT MAX(created_at) FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL AND created_at <= ? """, (row["id"], row["updated_at"]), ).fetchone()[0] conn.execute( """ INSERT INTO timeline_events (id, event_type, target_type, target_id, actor, summary, payload_json, created_at) VALUES (?, 'catalog_decision_recorded', 'catalog_item', ?, ?, ?, ?, ?) """, ( new_id("evt"), row["id"], row["owner"] or "migration", f"Catalog decision recorded: {action}", json_dumps( { "action": action, "record_id": record["id"] if record else None, "reviewed_through_finding_at": reviewed_through, "migrated_from": status, } ), row["updated_at"], ), ) conn.execute("DROP INDEX IF EXISTS idx_catalog_status") conn.execute("ALTER TABLE catalog_items DROP COLUMN status") conn.execute("ALTER TABLE catalog_items DROP COLUMN severity") def init_db() -> None: with get_conn() as conn: if connection_dialect(conn) == "mysql": init_tidb(conn) return schema_version = conn.execute("PRAGMA user_version").fetchone()[0] if 0 < schema_version < 8: reset_early_database(conn) migrate_catalog_item_posture_schema(conn) conn.executescript( """ CREATE TABLE IF NOT EXISTS users ( id TEXT PRIMARY KEY, auth0_subject TEXT UNIQUE, email TEXT NOT NULL UNIQUE, email_verified INTEGER NOT NULL DEFAULT 0, name TEXT NOT NULL, picture_url TEXT, role TEXT NOT NULL DEFAULT 'member', status TEXT NOT NULL DEFAULT 'active', last_login_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS catalog_items ( id TEXT PRIMARY KEY, org_id TEXT NOT NULL, project_id TEXT, cluster_id TEXT NOT NULL, sql_digest TEXT NOT NULL, normalized_sql TEXT, owner TEXT, priority TEXT, labels_json TEXT NOT NULL DEFAULT '[]', first_seen_at TEXT, last_seen_at TEXT, latest_finding_at TEXT, reappeared_at TEXT, archived_at TEXT, orphaned_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, UNIQUE(org_id, cluster_id, sql_digest) ); CREATE TABLE IF NOT EXISTS finding_runs ( id TEXT PRIMARY KEY, source TEXT NOT NULL, source_type TEXT NOT NULL CHECK(source_type IN ('inspection', 'manual', 'ai_agent', 'integration')), source_run_id TEXT NOT NULL, org_id TEXT NOT NULL, project_id TEXT, cluster_id TEXT NOT NULL, time_window_start TEXT NOT NULL, time_window_end TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('running', 'success', 'partial', 'failed')), detector_version TEXT, expected_detector_count INTEGER NOT NULL DEFAULT 0, completed_detector_count INTEGER NOT NULL DEFAULT 0, metadata_json TEXT NOT NULL DEFAULT '{}', started_at TEXT, completed_at TEXT, ingested_at TEXT NOT NULL, UNIQUE(org_id, cluster_id, source, source_run_id) ); CREATE TABLE IF NOT EXISTS cluster_metadata ( cluster_id TEXT PRIMARY KEY, clinic_org_id TEXT, tenant_id TEXT, org_name TEXT, cluster_name TEXT, deploy_type TEXT, metadata_json TEXT NOT NULL DEFAULT '{}', fetched_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS cluster_scopes ( id TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT, owner_id TEXT NOT NULL, visibility TEXT NOT NULL CHECK(visibility IN ('private', 'public')), membership_mode TEXT NOT NULL CHECK(membership_mode IN ('snapshot', 'dynamic')), definition_json TEXT NOT NULL DEFAULT '{}', include_deleted INTEGER NOT NULL DEFAULT 1, is_recommended INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS cluster_scope_members ( id TEXT PRIMARY KEY, scope_id TEXT NOT NULL, cluster_id TEXT NOT NULL, cluster_name TEXT NOT NULL, org_id TEXT NOT NULL, org_name TEXT, reason TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL, UNIQUE(scope_id, cluster_id), FOREIGN KEY(scope_id) REFERENCES cluster_scopes(id) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS user_preferences ( owner_id TEXT PRIMARY KEY, default_cluster_scope_id TEXT, updated_at TEXT NOT NULL, FOREIGN KEY(default_cluster_scope_id) REFERENCES cluster_scopes(id) ON DELETE SET NULL ); CREATE TABLE IF NOT EXISTS cluster_sql_health_owners ( cluster_id TEXT NOT NULL, owner_id TEXT NOT NULL, assigned_by TEXT NOT NULL, assigned_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(cluster_id, owner_id) ); CREATE TABLE IF NOT EXISTS cluster_sql_review_policies ( cluster_id TEXT PRIMARY KEY, critical_finding_triggers_review INTEGER NOT NULL, finding_count_threshold INTEGER NOT NULL, finding_window_days INTEGER NOT NULL, updated_by TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS health_check_report_syncs ( id TEXT PRIMARY KEY, org_id TEXT NOT NULL, cluster_id TEXT NOT NULL, report_id TEXT NOT NULL, report_status TEXT, state TEXT NOT NULL CHECK(state IN ('queued', 'syncing', 'succeeded', 'partial', 'failed')), selected_items_json TEXT NOT NULL DEFAULT '[]', finding_run_id TEXT, finding_count INTEGER NOT NULL DEFAULT 0, created_count INTEGER NOT NULL DEFAULT 0, duplicate_count INTEGER NOT NULL DEFAULT 0, rejected_count INTEGER NOT NULL DEFAULT 0, catalog_created_count INTEGER NOT NULL DEFAULT 0, requested_by TEXT NOT NULL, report_created_at TEXT, report_updated_at TEXT, error_message TEXT, started_at TEXT NOT NULL, completed_at TEXT, updated_at TEXT NOT NULL, UNIQUE(org_id, cluster_id, report_id), FOREIGN KEY(finding_run_id) REFERENCES finding_runs(id) ); CREATE TABLE IF NOT EXISTS followed_scopes ( id TEXT PRIMARY KEY, owner_id TEXT NOT NULL, scope_type TEXT NOT NULL, scope_id TEXT NOT NULL, scope_name TEXT NOT NULL, org_id TEXT NOT NULL, org_name TEXT, tenant_id TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, UNIQUE(owner_id, scope_type, scope_id) ); CREATE TABLE IF NOT EXISTS user_scope_settings ( owner_id TEXT PRIMARY KEY, initialized_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS groups ( id TEXT PRIMARY KEY, group_type TEXT NOT NULL, name TEXT NOT NULL, description TEXT, org_id TEXT, owner_id TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active', created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS group_members ( id TEXT PRIMARY KEY, group_id TEXT NOT NULL, member_type TEXT NOT NULL, member_id TEXT NOT NULL, member_name TEXT NOT NULL, org_id TEXT NOT NULL, org_name TEXT, reason TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL, UNIQUE(group_id, member_type, member_id), FOREIGN KEY(group_id) REFERENCES groups(id) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS symptom_definitions ( code TEXT PRIMARY KEY, name TEXT NOT NULL, category TEXT NOT NULL, description TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('active', 'deprecated')), version INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS finding_deletions ( id TEXT PRIMARY KEY, requested_by TEXT NOT NULL, reason TEXT NOT NULL, selection_json TEXT NOT NULL, finding_count INTEGER NOT NULL, created_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS findings ( id TEXT PRIMARY KEY, source TEXT NOT NULL, source_type TEXT NOT NULL CHECK(source_type IN ('inspection', 'manual', 'ai_agent', 'integration')), source_event_id TEXT NOT NULL, source_batch_id TEXT, source_run_id TEXT, finding_run_id TEXT, org_id TEXT NOT NULL, project_id TEXT, cluster_id TEXT NOT NULL, sql_digest TEXT NOT NULL, normalized_sql TEXT, time_window_start TEXT, time_window_end TEXT, reported_at TEXT NOT NULL, observed_at TEXT NOT NULL, ingested_at TEXT NOT NULL, severity TEXT NOT NULL CHECK(severity IN ('critical', 'high', 'medium', 'low', 'info')), detector_code TEXT NOT NULL, detector_version TEXT, metric_schema_version TEXT, metrics_json TEXT NOT NULL DEFAULT '{}', dimensions_json TEXT NOT NULL DEFAULT '{}', evidence_refs_json TEXT NOT NULL DEFAULT '[]', raw_payload_json TEXT NOT NULL DEFAULT '{}', catalog_item_id TEXT NOT NULL, is_new_digest INTEGER NOT NULL DEFAULT 0, is_first_observation INTEGER NOT NULL DEFAULT 0, created_by TEXT, created_at TEXT NOT NULL, deleted_at TEXT, deleted_by TEXT, deletion_reason TEXT, deletion_id TEXT, CHECK( (time_window_start IS NULL AND time_window_end IS NULL) OR (time_window_start IS NOT NULL AND time_window_end IS NOT NULL AND time_window_end >= time_window_start) ), UNIQUE(source, source_event_id), FOREIGN KEY(catalog_item_id) REFERENCES catalog_items(id), FOREIGN KEY(finding_run_id) REFERENCES finding_runs(id), FOREIGN KEY(deletion_id) REFERENCES finding_deletions(id) ); CREATE TABLE IF NOT EXISTS finding_symptoms ( id TEXT PRIMARY KEY, finding_id TEXT NOT NULL, symptom_code TEXT NOT NULL, severity TEXT NOT NULL CHECK(severity IN ('critical', 'high', 'medium', 'low', 'info')), confidence REAL CHECK(confidence IS NULL OR (confidence >= 0 AND confidence <= 1)), signal_codes_json TEXT NOT NULL DEFAULT '[]', metric_keys_json TEXT NOT NULL DEFAULT '[]', evidence_refs_json TEXT NOT NULL DEFAULT '[]', assessment_json TEXT NOT NULL DEFAULT '{}', UNIQUE(finding_id, symptom_code), FOREIGN KEY(finding_id) REFERENCES findings(id) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS treatments ( id TEXT PRIMARY KEY, treatment_no TEXT NOT NULL UNIQUE, title TEXT NOT NULL, objective TEXT NOT NULL, success_criteria TEXT NOT NULL DEFAULT '', state TEXT NOT NULL CHECK(state IN ('active', 'completed', 'cancelled')), stage TEXT NOT NULL CHECK(stage IN ('assessment', 'planning', 'alignment', 'execution', 'observation', 'completed')), outcome TEXT CHECK(outcome IS NULL OR outcome IN ('fixed', 'improved', 'unchanged', 'not_optimizable', 'accepted_risk', 'failed', 'cancelled', 'superseded')), outcome_record_id TEXT, superseded_by_treatment_id TEXT, owner TEXT, assignee TEXT, priority TEXT, severity TEXT, labels_json TEXT NOT NULL DEFAULT '[]', observation_started_at TEXT, observation_due_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, completed_at TEXT ); CREATE TABLE IF NOT EXISTS records ( id TEXT PRIMARY KEY, record_type TEXT NOT NULL, title TEXT NOT NULL, structured_fields_json TEXT NOT NULL DEFAULT '{}', body_markdown TEXT NOT NULL DEFAULT '', visibility TEXT NOT NULL DEFAULT 'internal', review_status TEXT NOT NULL DEFAULT 'draft', created_by TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS relations ( id TEXT PRIMARY KEY, from_type TEXT NOT NULL, from_id TEXT NOT NULL, relation_type TEXT NOT NULL, to_type TEXT NOT NULL, to_id TEXT NOT NULL, created_at TEXT NOT NULL, UNIQUE(from_type, from_id, relation_type, to_type, to_id) ); CREATE TABLE IF NOT EXISTS timeline_events ( id TEXT PRIMARY KEY, event_type TEXT NOT NULL, target_type TEXT NOT NULL, target_id TEXT NOT NULL, actor TEXT, summary TEXT NOT NULL, payload_json TEXT NOT NULL DEFAULT '{}', created_at TEXT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_findings_created_at ON findings(created_at); CREATE INDEX IF NOT EXISTS idx_findings_digest ON findings(org_id, cluster_id, sql_digest); CREATE INDEX IF NOT EXISTS idx_findings_batch ON findings(source, source_batch_id); CREATE INDEX IF NOT EXISTS idx_findings_deleted ON findings(deleted_at, created_at); CREATE INDEX IF NOT EXISTS idx_finding_symptoms_code ON finding_symptoms(symptom_code, finding_id); CREATE INDEX IF NOT EXISTS idx_finding_runs_window ON finding_runs(time_window_end); CREATE INDEX IF NOT EXISTS idx_finding_runs_scope ON finding_runs(org_id, cluster_id, source); CREATE INDEX IF NOT EXISTS idx_finding_runs_cluster_window ON finding_runs(cluster_id, time_window_end, ingested_at); CREATE INDEX IF NOT EXISTS idx_cluster_metadata_org ON cluster_metadata(clinic_org_id); CREATE INDEX IF NOT EXISTS idx_cluster_scopes_owner ON cluster_scopes(owner_id, visibility); CREATE INDEX IF NOT EXISTS idx_cluster_scope_members_cluster ON cluster_scope_members(cluster_id, scope_id); CREATE INDEX IF NOT EXISTS idx_health_check_syncs_cluster ON health_check_report_syncs(cluster_id, report_id); CREATE INDEX IF NOT EXISTS idx_followed_scopes_owner ON followed_scopes(owner_id, scope_type); CREATE INDEX IF NOT EXISTS idx_groups_owner ON groups(owner_id, group_type, status); CREATE INDEX IF NOT EXISTS idx_group_members_member ON group_members(member_type, member_id); CREATE INDEX IF NOT EXISTS idx_catalog_archived ON catalog_items(archived_at); CREATE INDEX IF NOT EXISTS idx_catalog_cluster ON catalog_items(cluster_id, orphaned_at, archived_at); CREATE INDEX IF NOT EXISTS idx_treatments_state_stage ON treatments(state, stage); CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_type, to_id); CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_type, from_id); CREATE INDEX IF NOT EXISTS idx_timeline_target ON timeline_events(target_type, target_id, created_at); CREATE INDEX IF NOT EXISTS idx_catalog_orphaned ON catalog_items(orphaned_at); CREATE INDEX IF NOT EXISTS idx_findings_catalog_event ON findings(catalog_item_id, deleted_at, reported_at, created_at); CREATE INDEX IF NOT EXISTS idx_findings_cluster_observed ON findings(cluster_id, deleted_at, observed_at); """ ) migrate_schema(conn) seed_symptom_definitions(conn) bootstrap_auth_user(conn) def init_tidb(conn: Any) -> None: ensure_tidb_schema(conn) seed_symptom_definitions(conn) bootstrap_auth_user(conn) def health_status() -> dict[str, Any]: with get_conn() as conn: conn.execute("SELECT 1").fetchone() return { "ok": True, "database": { "dialect": connection_dialect(conn), "schema_version": SCHEMA_VERSION, }, } def readiness_status() -> tuple[int, dict[str, Any]]: try: return HTTPStatus.OK, health_status() except Exception: # noqa: BLE001 - probes must not expose dependency details. return HTTPStatus.SERVICE_UNAVAILABLE, { "ok": False, "database": {"status": "unavailable"}, } def reset_early_database(conn: sqlite3.Connection) -> None: conn.execute("PRAGMA foreign_keys = OFF") for table in ( "users", "cluster_sql_review_policies", "cluster_sql_health_owners", "health_check_report_syncs", "user_preferences", "cluster_scope_members", "cluster_scopes", "group_members", "groups", "user_scope_settings", "followed_scopes", "cluster_metadata", "relations", "timeline_events", "records", "treatments", "finding_symptoms", "findings", "finding_deletions", "symptom_definitions", "finding_runs", "catalog_items", ): conn.execute(f"DROP TABLE IF EXISTS {table}") conn.execute("PRAGMA user_version = 0") conn.execute("PRAGMA foreign_keys = ON") def migrate_schema(conn: sqlite3.Connection) -> None: previous_version = int(conn.execute("PRAGMA user_version").fetchone()[0]) finding_columns = table_columns(conn, "findings") if "reported_at" not in finding_columns: conn.execute("ALTER TABLE findings ADD COLUMN reported_at TEXT") conn.execute( """ UPDATE findings SET reported_at = COALESCE(observed_at, time_window_end, created_at) WHERE reported_at IS NULL """ ) if previous_version < 11: conn.execute( """ UPDATE catalog_items SET latest_finding_at = ( SELECT MAX(COALESCE(f.reported_at, f.created_at)) FROM findings f WHERE f.catalog_item_id = catalog_items.id AND f.deleted_at IS NULL ) WHERE EXISTS ( SELECT 1 FROM findings f WHERE f.catalog_item_id = catalog_items.id AND f.deleted_at IS NULL ) """ ) conn.executescript( """ CREATE INDEX IF NOT EXISTS idx_findings_reported_at ON findings(reported_at); CREATE INDEX IF NOT EXISTS idx_findings_observed_at ON findings(observed_at); CREATE INDEX IF NOT EXISTS idx_findings_ingested_at ON findings(ingested_at); CREATE INDEX IF NOT EXISTS idx_findings_detector ON findings(detector_code); CREATE INDEX IF NOT EXISTS idx_findings_run ON findings(finding_run_id); CREATE INDEX IF NOT EXISTS idx_findings_batch ON findings(source, source_batch_id); CREATE INDEX IF NOT EXISTS idx_findings_deleted ON findings(deleted_at, created_at); CREATE INDEX IF NOT EXISTS idx_finding_symptoms_code ON finding_symptoms(symptom_code, finding_id); CREATE INDEX IF NOT EXISTS idx_finding_runs_window ON finding_runs(time_window_end); CREATE INDEX IF NOT EXISTS idx_finding_runs_scope ON finding_runs(org_id, cluster_id, source); """ ) conn.execute("CREATE INDEX IF NOT EXISTS idx_treatments_observation_due ON treatments(observation_due_at)") conn.execute("CREATE INDEX IF NOT EXISTS idx_catalog_orphaned ON catalog_items(orphaned_at)") migrate_cluster_sql_health_owners(conn) conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}") def migrate_cluster_sql_health_owners(conn: sqlite3.Connection) -> None: rows = conn.execute("PRAGMA table_info(cluster_sql_health_owners)").fetchall() primary_key = [ str(row["name"]) for row in sorted(rows, key=lambda row: int(row["pk"]) if row["pk"] else 999) if row["pk"] ] if primary_key == ["cluster_id", "owner_id"]: return conn.executescript( """ ALTER TABLE cluster_sql_health_owners RENAME TO cluster_sql_health_owners_legacy; CREATE TABLE cluster_sql_health_owners ( cluster_id TEXT NOT NULL, owner_id TEXT NOT NULL, assigned_by TEXT NOT NULL, assigned_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(cluster_id, owner_id) ); INSERT OR IGNORE INTO cluster_sql_health_owners (cluster_id, owner_id, assigned_by, assigned_at, updated_at) SELECT cluster_id, owner_id, assigned_by, assigned_at, updated_at FROM cluster_sql_health_owners_legacy; DROP TABLE cluster_sql_health_owners_legacy; """ ) def seed_symptom_definitions(conn: sqlite3.Connection) -> None: timestamp = now_iso() for definition in DEFAULT_SYMPTOM_DEFINITIONS: conn.execute( dialect_sql( conn, """ INSERT INTO symptom_definitions (code, name, category, description, status, version, created_at, updated_at) VALUES (?, ?, ?, ?, 'active', 1, ?, ?) ON CONFLICT(code) DO UPDATE SET name = excluded.name, category = excluded.category, description = excluded.description, version = symptom_definitions.version + 1, updated_at = excluded.updated_at WHERE symptom_definitions.name != excluded.name OR symptom_definitions.category != excluded.category OR symptom_definitions.description != excluded.description """, """ INSERT INTO symptom_definitions (code, name, category, description, status, version, created_at, updated_at) VALUES (?, ?, ?, ?, 'active', 1, ?, ?) ON DUPLICATE KEY UPDATE version = version + IF( name <> VALUES(name) OR category <> VALUES(category) OR description <> VALUES(description), 1, 0 ), updated_at = IF( name <> VALUES(name) OR category <> VALUES(category) OR description <> VALUES(description), VALUES(updated_at), updated_at ), name = VALUES(name), category = VALUES(category), description = VALUES(description) """, ), ( definition["code"], definition["name"], definition["category"], definition["description"], timestamp, timestamp, ), ) def row_to_finding_symptom(row: sqlite3.Row) -> dict[str, Any]: result = dict(row) result["code"] = result.pop("symptom_code") result["signal_codes"] = json_loads(result.pop("signal_codes_json", None), []) result["metric_keys"] = json_loads(result.pop("metric_keys_json", None), []) result["evidence_refs"] = json_loads(result.pop("evidence_refs_json", None), []) result["assessment"] = json_loads(result.pop("assessment_json", None), {}) return result def load_finding_symptoms( conn: sqlite3.Connection, finding_ids: list[str] ) -> dict[str, list[dict[str, Any]]]: grouped: dict[str, list[dict[str, Any]]] = {finding_id: [] for finding_id in finding_ids} if not finding_ids: return grouped placeholders = ",".join("?" for _ in finding_ids) rows = conn.execute( f""" SELECT * FROM finding_symptoms WHERE finding_id IN ({placeholders}) ORDER BY CASE severity WHEN 'critical' THEN 4 WHEN 'high' THEN 3 WHEN 'medium' THEN 2 WHEN 'low' THEN 1 ELSE 0 END DESC, symptom_code """, finding_ids, ).fetchall() for row in rows: symptom = row_to_finding_symptom(row) grouped.setdefault(symptom["finding_id"], []).append(symptom) return grouped def row_to_finding( row: sqlite3.Row, symptoms: list[dict[str, Any]] | None = None ) -> dict[str, Any]: result = dict(row) result["metrics"] = json_loads(result.pop("metrics_json", None), {}) result["dimensions"] = json_loads(result.pop("dimensions_json", None), {}) result["evidence_refs"] = json_loads(result.pop("evidence_refs_json", None), []) result["raw_payload"] = json_loads(result.pop("raw_payload_json", None), {}) result["symptoms"] = symptoms or [] result["symptom_count"] = len(result["symptoms"]) result["is_new_digest"] = bool(result.get("is_new_digest")) result["is_first_observation"] = bool(result.get("is_first_observation")) result["is_deleted"] = bool(result.get("deleted_at")) result["observed_at"] = result.get("observed_at") or result.get("time_window_end") or result.get("created_at") result["reported_at"] = result.get("reported_at") or result.get("created_at") result["ingested_at"] = result.get("ingested_at") or result.get("created_at") fixture_derivation = ensure_dict(result.get("dimensions", {}).get("fixture_derivation")) result["metadata_cluster_id"] = ( report_value(fixture_derivation, "source_cluster_id") or result.get("cluster_id") ) result["source_url"] = build_finding_source_url(result) result["source_report_id"] = finding_source_report_id(result) result["signal_class"] = finding_signal_class(result) return result def finding_source_report(finding: dict[str, Any]) -> dict[str, Any]: raw_payload = ensure_dict(finding.get("raw_payload")) dimensions = ensure_dict(finding.get("dimensions")) return ensure_dict(raw_payload.get("report")) or ensure_dict(dimensions.get("report")) def report_value(report: dict[str, Any], *keys: str) -> str | None: for key in keys: value = report.get(key) if isinstance(value, str) and value.strip(): return value.strip() return None def finding_source_report_id(finding: dict[str, Any]) -> str | None: if finding.get("source") != "clinic_health_check": return None report = finding_source_report(finding) report_id = report_value( report, "result_uuid", "resultUuid", "report_id", "reportId", "strategy_uuid", "strategyUuid", ) if report_id: return report_id source_run_id = finding.get("source_run_id") if isinstance(source_run_id, str): match = re.search( r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}", source_run_id, ) if match: return match.group(0) return None def build_finding_source_url(finding: dict[str, Any]) -> str | None: report_id = finding_source_report_id(finding) if not report_id: return None report = finding_source_report(finding) org_id = report_value(report, "portal_org_id", "portalOrgId") cluster_id = report_value(report, "cluster_id", "clusterId") or finding.get("cluster_id") start = report_value(report, "time_range_a_start", "timeRangeAStart") or finding.get("time_window_start") end = report_value(report, "time_range_a_end", "timeRangeAEnd") or finding.get("time_window_end") if not all(isinstance(value, str) and value for value in (org_id, cluster_id, start, end)): return None query = urlencode({"from": start, "to": end}) return ( f"{CLINIC_PORTAL_BASE}/orgs/{quote(org_id, safe='')}" f"/clusters/{quote(cluster_id, safe='')}/health-check/{quote(report_id, safe='')}?{query}" ) def row_to_cluster_metadata(row: sqlite3.Row) -> dict[str, Any]: org_id = row["clinic_org_id"] or row["tenant_id"] dbaas_org_id = row["tenant_id"] or row["clinic_org_id"] return { "cluster_id": row["cluster_id"], "org_id": org_id, "dbaas_org_id": dbaas_org_id, "tenant_id": dbaas_org_id, "org_name": row["org_name"], "cluster_name": row["cluster_name"], "deploy_type": row["deploy_type"], "metadata": json_loads(row["metadata_json"], {}), "fetched_at": row["fetched_at"], "resolved": True, } def clinic_data_proxy_get( path: str, query_params: list[tuple[str, str]] | None = None ) -> tuple[int, Any | None]: if not CLINIC_API_KEY: return 503, None query = urlencode(query_params or []) url = f"{CLINIC_DATA_PROXY_API_BASE}/{path.lstrip('/')}" if query: url = f"{url}?{query}" request = Request( url, headers={ "Accept": "application/json", "Authorization": f"Bearer {CLINIC_API_KEY}", }, ) try: with urlopen( request, timeout=CLINIC_API_TIMEOUT_SECONDS ) as response: # noqa: S310 - fixed trusted host. payload = json.loads(response.read().decode("utf-8")) except HTTPError as error: if error.code != HTTPStatus.NOT_FOUND: print(f"Clinic Data Proxy request failed with HTTP {error.code}", file=sys.stderr) return error.code, None except (URLError, TimeoutError) as error: print(f"Clinic Data Proxy request failed: {type(error).__name__}", file=sys.stderr) return 0, None except json.JSONDecodeError: print("Clinic Data Proxy returned invalid JSON", file=sys.stderr) return 502, None return 200, payload def clinic_portal_cluster_identity_from_payload( payload: Any, cluster_id: str, canonical_org_id: str, ) -> dict[str, Any] | None: if not isinstance(payload, dict) or not isinstance(payload.get("items"), list): return None matches = [ item for item in payload["items"] if isinstance(item, dict) and optional_metadata_value(item.get("clusterID")) == cluster_id and optional_metadata_value(item.get("tenantID")) == canonical_org_id and optional_metadata_value(item.get("orgID")) ] portal_org_ids = { str(item["orgID"]).strip() for item in matches if str(item.get("orgID") or "").strip() } if len(portal_org_ids) != 1: return None item = matches[0] return { "cluster_id": cluster_id, "clinic_org_id": next(iter(portal_org_ids)), "tenant_id": canonical_org_id, "org_name": optional_metadata_value(item.get("tenantName")), "cluster_name": optional_metadata_value(item.get("clusterName")), "deploy_type": optional_metadata_value( item.get("clusterDeployTypeV2") or item.get("clusterDeployType") ), "metadata": { "identity_source": "clinic_dashboard_exact_cluster_lookup", "project_id": optional_metadata_value(item.get("projectID")), "parent_id": optional_metadata_value(item.get("parentID")), "cloud_provider": optional_metadata_value( item.get("clusterProviderName") ), "region": optional_metadata_value(item.get("clusterRegionName")), "status": optional_metadata_value(item.get("clusterStatus")), }, "fetched_at": now_iso(), } def clinic_portal_cluster_identity( cluster_id: str, canonical_org_id: str ) -> dict[str, Any] | None: """Resolve the Clinic-internal org ID used only by Portal routes.""" if not CLINIC_API_KEY: return None query = urlencode( [ ("cluster_id", cluster_id), ("show_deleted", "true"), ("limit", "20"), ("page", "1"), ] ) request = Request( f"{CLINIC_API_BASE}/dashboard/clusters?{query}", headers={ "Accept": "application/json", "Authorization": f"Bearer {CLINIC_API_KEY}", }, ) try: with urlopen( request, timeout=CLINIC_API_TIMEOUT_SECONDS ) as response: # noqa: S310 - configured Clinic host. payload = json.loads(response.read().decode("utf-8")) except HTTPError as error: print( f"Clinic Portal identity lookup failed with HTTP {error.code}", file=sys.stderr, ) return None except (URLError, TimeoutError) as error: print( f"Clinic Portal identity lookup failed: {type(error).__name__}", file=sys.stderr, ) return None except json.JSONDecodeError: print("Clinic Portal identity lookup returned invalid JSON", file=sys.stderr) return None return clinic_portal_cluster_identity_from_payload( payload, cluster_id, canonical_org_id ) def clinic_get_cluster_by_id(cluster_id: str) -> tuple[int, dict[str, Any] | None]: status, payload = clinic_data_proxy_get( f"clusters/{quote(cluster_id, safe='')}" ) return status, payload if isinstance(payload, dict) else None def clinic_list_org_clusters( org_id: str, *, query: str | None = None, limit: int = 20, page: int = 1, ) -> tuple[int, dict[str, Any] | None]: query_params = [ ("page", str(max(page, 1))), ("pageSize", str(min(max(limit, 1), 200))), ("showDeleted", "false"), ] if query: query_params.append(("query", query)) status, payload = clinic_data_proxy_get( f"orgs/{quote(org_id, safe='')}/clusters", query_params ) if not isinstance(payload, dict) or not isinstance(payload.get("items"), list): return status, None items = [item for item in payload["items"] if isinstance(item, dict)] return status, { "items": items, "total": positive_int(payload.get("total"), len(items), 10_000_000), "page": positive_int(payload.get("page"), page, 1_000_000), "page_size": positive_int(payload.get("pageSize"), limit, 200), } def clinic_cluster_metadata_from_item(cluster: dict[str, Any]) -> dict[str, Any] | None: cluster_id = optional_metadata_value(cluster.get("clusterId")) if not cluster_id: return None diagnostic_context = ensure_dict(cluster.get("diagnosticContext")) return { "cluster_id": cluster_id, "clinic_org_id": None, "tenant_id": optional_metadata_value(cluster.get("orgId")), "org_name": optional_metadata_value(cluster.get("orgName")), "cluster_name": optional_metadata_value(cluster.get("name")), "deploy_type": optional_metadata_value( cluster.get("deployTypeV2") or cluster.get("deployType") ), "metadata": { "project_id": optional_metadata_value(diagnostic_context.get("projectId")), "parent_id": optional_metadata_value(diagnostic_context.get("parentId")), "cloud_provider": optional_metadata_value(cluster.get("provider")), "region": optional_metadata_value(cluster.get("region")), "status": optional_metadata_value(cluster.get("status")), "version": optional_metadata_value(cluster.get("version")), "deleted": bool(cluster.get("deleted", False)), }, "fetched_at": now_iso(), "resolved": True, } def clinic_cluster_scope_candidate_from_metadata( metadata: dict[str, Any] ) -> dict[str, Any] | None: org_id = ( metadata.get("org_id") or metadata.get("clinic_org_id") or metadata.get("tenant_id") ) if not org_id: return None cluster_id = metadata["cluster_id"] return { "id": cluster_id, "name": metadata.get("cluster_name") or cluster_id, "org_id": org_id, "org_name": metadata.get("org_name"), "tenant_id": metadata.get("dbaas_org_id") or metadata.get("tenant_id"), "deploy_type": metadata.get("deploy_type"), "status": metadata.get("metadata", {}).get("status"), } def meaningful_scope_name(value: Any, resource_id: str) -> str | None: name = optional_metadata_value(value) return name if name and name != resource_id else None def known_org_display_name(org_id: str) -> str | None: with get_conn() as conn: metadata = conn.execute( "SELECT org_name FROM cluster_metadata WHERE (clinic_org_id = ? OR tenant_id = ?) " "AND org_name IS NOT NULL AND org_name != '' ORDER BY fetched_at DESC LIMIT 1", (org_id, org_id), ).fetchone() if metadata and meaningful_scope_name(metadata["org_name"], org_id): return str(metadata["org_name"]) followed = conn.execute( "SELECT scope_type, scope_id, scope_name, org_id, org_name, tenant_id " "FROM followed_scopes WHERE scope_id = ? OR org_id = ? OR tenant_id = ? " "ORDER BY updated_at DESC", (org_id, org_id, org_id), ).fetchall() return next( ( name for row in followed if ( name := meaningful_scope_name( row["scope_name"] if row["scope_type"] == "organization" else row["org_name"], org_id, ) ) ), None, ) def resolve_dbaas_org_id(org_id: str, hint: str | None = None) -> str: """Map a page/domain Org identity to the canonical Data Proxy Org identity.""" with get_conn() as conn: metadata = conn.execute( "SELECT tenant_id FROM cluster_metadata " "WHERE clinic_org_id = ? OR tenant_id = ? " "ORDER BY fetched_at DESC LIMIT 1", (org_id, org_id), ).fetchone() if metadata and optional_metadata_value(metadata["tenant_id"]): return str(metadata["tenant_id"]) followed = conn.execute( "SELECT tenant_id FROM followed_scopes " "WHERE owner_id = ? AND (scope_id = ? OR org_id = ? OR tenant_id = ?) " "AND tenant_id IS NOT NULL AND tenant_id != '' " "ORDER BY updated_at DESC LIMIT 1", (current_user_id(), org_id, org_id, org_id), ).fetchone() if followed and optional_metadata_value(followed["tenant_id"]): return str(followed["tenant_id"]) return optional_metadata_value(hint) or org_id def local_scope_candidates(scope_type: str, query: str) -> list[dict[str, Any]]: with get_conn() as conn: known = known_scope_candidates(conn) rows = conn.execute( "SELECT * FROM followed_scopes WHERE owner_id = ? AND scope_type = ?", (current_user_id(), scope_type), ).fetchall() key = "organizations" if scope_type == "organization" else "clusters" candidates = {item["id"]: item for item in known[key]} for row in rows: followed = row_to_followed_scope(row) candidates[followed["resource_id"]] = { "id": followed["resource_id"], "name": followed["name"], "org_id": followed["org_id"], "org_name": followed.get("org_name"), "tenant_id": followed.get("tenant_id"), } needle = query.casefold() return sorted( ( item for item in candidates.values() if needle in " ".join( str(value) for value in ( item.get("id"), item.get("name"), item.get("org_id"), item.get("org_name"), ) if value ).casefold() ), key=lambda item: (item.get("name") or item["id"], item["id"]), ) def clinic_scope_search(params: dict[str, list[str]]) -> tuple[int, dict[str, Any]]: scope_type = params.get("type", ["cluster"])[0] if scope_type not in {"organization", "cluster"}: return 400, {"error": "invalid_scope_type"} query = params.get("q", [""])[0].strip() if len(query) > 200: return 400, {"error": "invalid_query", "message": "q must be at most 200 characters"} if not CLINIC_API_KEY: return 503, {"error": "clinic_api_not_configured"} limit = min(max(positive_int(params.get("limit", ["20"])[0], 20, 50), 1), 50) page = max(positive_int(params.get("page", ["1"])[0], 1, 10_000), 1) items = local_scope_candidates(scope_type, query)[:limit] remote_status = HTTPStatus.NOT_FOUND if scope_type == "cluster": remote_status, cluster = clinic_get_cluster_by_id(query) if cluster and (metadata := clinic_cluster_metadata_from_item(cluster)): dbaas_org_id = metadata.get("tenant_id") or "" metadata["org_name"] = known_org_display_name(dbaas_org_id) stored = upsert_cluster_metadata(metadata) if candidate := clinic_cluster_scope_candidate_from_metadata(stored): items = [candidate, *[item for item in items if item["id"] != candidate["id"]]] elif query.isdigit(): dbaas_org_id = resolve_dbaas_org_id(query) remote_status, payload = clinic_list_org_clusters(dbaas_org_id, limit=1, page=1) if payload is not None: known_name = known_org_display_name(query) or known_org_display_name(dbaas_org_id) candidate = { "id": query, "name": known_name or query, "org_id": query, "org_name": known_name, "tenant_id": dbaas_org_id, } items = [candidate, *[item for item in items if item["id"] != query]] if remote_status not in {200, HTTPStatus.NOT_FOUND} and not items: return 502, {"error": "clinic_api_unavailable"} items = items[:limit] return 200, { "items": items, "total": len(items), "page": page, "limit": limit, "source": "clinic", } def clinic_organization_clusters( org_id: str, params: dict[str, list[str]] ) -> tuple[int, dict[str, Any]]: allowed = {"page", "page_size", "q", "dbaas_org_id"} unexpected = sorted(set(params) - allowed) if unexpected: return 400, { "error": "invalid_clinic_organization_cluster_query", "message": f"unsupported query parameters: {', '.join(unexpected)}", } try: org_id = validate_health_check_resource_id(org_id, "org_id") page = strict_positive_query_int(params, "page", 1, 1_000_000) page_size = strict_positive_query_int(params, "page_size", 50, 200) query = params.get("q", [""])[0].strip() if len(query) > 200: raise ValueError("q must be at most 200 characters") dbaas_hint = optional_metadata_value( params.get("dbaas_org_id", [None])[0] ) except ValueError as exc: return 400, { "error": "invalid_clinic_organization_cluster_query", "message": str(exc), } if not CLINIC_API_KEY: return 503, {"error": "clinic_api_not_configured"} dbaas_org_id = resolve_dbaas_org_id(org_id, dbaas_hint) status, payload = clinic_list_org_clusters( dbaas_org_id, query=query or None, limit=page_size, page=page, ) if status == HTTPStatus.NOT_FOUND: return 404, {"error": "scope_candidate_not_found"} if status != 200 or payload is None: return 502, {"error": "clinic_organization_clusters_unavailable"} org_name = known_org_display_name(org_id) or known_org_display_name(dbaas_org_id) items: list[dict[str, Any]] = [] for cluster in payload["items"]: metadata = clinic_cluster_metadata_from_item(cluster) if not metadata: continue metadata["clinic_org_id"] = org_id metadata["tenant_id"] = dbaas_org_id metadata["org_name"] = optional_metadata_value(cluster.get("orgName")) or org_name stored = upsert_cluster_metadata(metadata) candidate = clinic_cluster_scope_candidate_from_metadata(stored) if candidate: items.append(candidate) org_name = org_name or candidate.get("org_name") return 200, { "items": items, "total": payload["total"], "page": payload["page"], "page_size": payload["page_size"], "organization": { "id": org_id, "name": org_name or org_id, "tenant_id": dbaas_org_id, }, "source": "clinic", } def clinic_scope_resolve(params: dict[str, list[str]]) -> tuple[int, dict[str, Any]]: scope_type = params.get("type", [""])[0] if scope_type not in {"organization", "cluster"}: return 400, {"error": "invalid_scope_type"} resource_id = params.get("id", [""])[0].strip() if not resource_id or len(resource_id) > 255: return 400, {"error": "invalid_scope_id"} if not CLINIC_API_KEY: return 503, {"error": "clinic_api_not_configured"} if scope_type == "cluster": status, cluster = clinic_get_cluster_by_id(resource_id) if status == HTTPStatus.NOT_FOUND: return 404, {"error": "scope_candidate_not_found"} if status != 200 or not cluster: return 502, {"error": "clinic_api_unavailable"} metadata = clinic_cluster_metadata_from_item(cluster) if not metadata or not metadata.get("tenant_id"): return 502, {"error": "clinic_metadata_invalid"} metadata["org_name"] = known_org_display_name(metadata["tenant_id"]) stored = upsert_cluster_metadata(metadata) candidate = clinic_cluster_scope_candidate_from_metadata(stored) if not candidate: return 502, {"error": "clinic_metadata_invalid"} return 200, { "scope": candidate, "resolved": True, "name_source": "clinic", } dbaas_hint = optional_metadata_value( params.get("dbaas_org_id", params.get("tenant_id", [None]))[0] ) dbaas_org_id = resolve_dbaas_org_id(resource_id, dbaas_hint) status, payload = clinic_list_org_clusters(dbaas_org_id, limit=1, page=1) if status == HTTPStatus.NOT_FOUND: return 404, {"error": "scope_candidate_not_found"} if status != 200 or payload is None: return 502, {"error": "clinic_api_unavailable"} org_name = known_org_display_name(resource_id) or known_org_display_name(dbaas_org_id) for cluster in payload.get("items", []): metadata = clinic_cluster_metadata_from_item(cluster) if not metadata: continue metadata["org_name"] = optional_metadata_value(cluster.get("orgName")) or org_name upsert_cluster_metadata(metadata) return 200, { "scope": { "id": resource_id, "name": org_name or resource_id, "org_id": resource_id, "org_name": org_name, "tenant_id": dbaas_org_id, }, "resolved": True, "name_source": "catalog_cache" if org_name else "unavailable", } def fetch_clinic_cluster_metadata(cluster_id: str) -> dict[str, Any] | None: _, cluster = clinic_get_cluster_by_id(cluster_id) if not cluster: return None metadata = clinic_cluster_metadata_from_item(cluster) if metadata and metadata.get("tenant_id"): metadata["org_name"] = known_org_display_name(metadata["tenant_id"]) return metadata def optional_metadata_value(value: Any) -> str | None: if value is None or value == "": return None return str(value) def upsert_cluster_metadata(metadata: dict[str, Any]) -> dict[str, Any]: with get_conn() as conn: return upsert_cluster_metadata_with_conn(conn, metadata) def sync_cluster_identity_references( conn: sqlite3.Connection, metadata: dict[str, Any], ) -> None: timestamp = now_iso() conn.execute( """ UPDATE followed_scopes SET scope_name = COALESCE(?, scope_name), org_id = COALESCE(?, org_id), org_name = ?, tenant_id = ?, updated_at = ? WHERE scope_type = 'cluster' AND scope_id = ? """, ( metadata.get("cluster_name"), metadata.get("clinic_org_id"), metadata.get("org_name"), metadata.get("tenant_id"), timestamp, metadata["cluster_id"], ), ) conn.execute( """ UPDATE followed_scopes SET scope_name = COALESCE(?, scope_name), org_name = COALESCE(?, org_name), tenant_id = COALESCE(?, tenant_id), updated_at = ? WHERE scope_type = 'organization' AND (scope_id = ? OR scope_id = ?) """, ( metadata.get("org_name"), metadata.get("org_name"), metadata.get("tenant_id"), timestamp, metadata.get("clinic_org_id"), metadata.get("tenant_id"), ), ) conn.execute( """ UPDATE group_members SET member_name = COALESCE(?, member_name), org_id = COALESCE(?, org_id), org_name = ? WHERE member_type = 'cluster' AND member_id = ? """, ( metadata.get("cluster_name"), metadata.get("clinic_org_id"), metadata.get("org_name"), metadata["cluster_id"], ), ) conn.execute( """ UPDATE cluster_scope_members SET cluster_name = COALESCE(?, cluster_name), org_id = COALESCE(?, org_id), org_name = ? WHERE cluster_id = ? """, ( metadata.get("cluster_name"), metadata.get("clinic_org_id"), metadata.get("org_name"), metadata["cluster_id"], ), ) def cache_reported_cluster_metadata_with_conn( conn: sqlite3.Connection, *, org_id: str, project_id: str | None, cluster_id: str, dimensions: dict[str, Any], ) -> None: cluster = ensure_dict(dimensions.get("cluster")) cluster_name = optional_metadata_value(cluster.get("name")) org_name = optional_metadata_value(cluster.get("org_name")) dbaas_org_id = optional_metadata_value( cluster.get("dbaas_org_id") or cluster.get("tenant_id") ) deploy_type = optional_metadata_value(cluster.get("deploy_type")) if not any((cluster_name, org_name, dbaas_org_id, deploy_type)): return existing = conn.execute( "SELECT * FROM cluster_metadata WHERE cluster_id = ?", (cluster_id,), ).fetchone() if existing and all( ( existing["clinic_org_id"] == org_id, existing["tenant_id"] or not dbaas_org_id, existing["org_name"] or not org_name, existing["cluster_name"] or not cluster_name, ) ): sync_cluster_identity_references(conn, dict(existing)) return existing_metadata = ( ensure_dict(json_loads(existing["metadata_json"], {})) if existing else {} ) existing_clinic_org_id = ( optional_metadata_value(existing["clinic_org_id"]) if existing else None ) existing_tenant_id = ( optional_metadata_value(existing["tenant_id"]) if existing else None ) clinic_org_id = ( org_id if not existing_clinic_org_id or existing_clinic_org_id == existing_tenant_id else existing_clinic_org_id ) source_metadata = { "identity_source": "finding_dimensions", "project_id": project_id, "cloud_provider": optional_metadata_value(cluster.get("provider")), "region": optional_metadata_value(cluster.get("region")), } upsert_cluster_metadata_with_conn( conn, { "cluster_id": cluster_id, "clinic_org_id": clinic_org_id, "tenant_id": ( optional_metadata_value(existing["tenant_id"]) if existing else None ) or dbaas_org_id, "org_name": ( optional_metadata_value(existing["org_name"]) if existing else None ) or org_name, "cluster_name": ( optional_metadata_value(existing["cluster_name"]) if existing else None ) or cluster_name, "deploy_type": ( optional_metadata_value(existing["deploy_type"]) if existing else None ) or deploy_type, "metadata": { **{ key: value for key, value in source_metadata.items() if value is not None }, **existing_metadata, }, "fetched_at": now_iso(), }, ) def upsert_cluster_metadata_with_conn( conn: sqlite3.Connection, metadata: dict[str, Any] ) -> dict[str, Any]: existing = conn.execute( "SELECT * FROM cluster_metadata WHERE cluster_id = ?", (metadata["cluster_id"],), ).fetchone() incoming_dbaas_org_id = optional_metadata_value( metadata.get("tenant_id") or metadata.get("clinic_org_id") ) existing_dbaas_org_id = optional_metadata_value( (existing["tenant_id"] or existing["clinic_org_id"]) if existing else None ) same_org = bool( existing and incoming_dbaas_org_id and existing_dbaas_org_id == incoming_dbaas_org_id ) merged = dict(metadata) if same_org: merged["clinic_org_id"] = ( merged.get("clinic_org_id") or existing["clinic_org_id"] ) merged["org_name"] = merged.get("org_name") or existing["org_name"] merged["tenant_id"] = merged.get("tenant_id") or existing["tenant_id"] elif not merged.get("clinic_org_id"): merged["clinic_org_id"] = incoming_dbaas_org_id conn.execute( dialect_sql( conn, """ INSERT INTO cluster_metadata (cluster_id, clinic_org_id, tenant_id, org_name, cluster_name, deploy_type, metadata_json, fetched_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(cluster_id) DO UPDATE SET clinic_org_id = excluded.clinic_org_id, tenant_id = excluded.tenant_id, org_name = excluded.org_name, cluster_name = excluded.cluster_name, deploy_type = excluded.deploy_type, metadata_json = excluded.metadata_json, fetched_at = excluded.fetched_at """, """ INSERT INTO cluster_metadata (cluster_id, clinic_org_id, tenant_id, org_name, cluster_name, deploy_type, metadata_json, fetched_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON DUPLICATE KEY UPDATE clinic_org_id = VALUES(clinic_org_id), tenant_id = VALUES(tenant_id), org_name = VALUES(org_name), cluster_name = VALUES(cluster_name), deploy_type = VALUES(deploy_type), metadata_json = VALUES(metadata_json), fetched_at = VALUES(fetched_at) """, ), ( merged["cluster_id"], merged.get("clinic_org_id"), merged.get("tenant_id"), merged.get("org_name"), merged.get("cluster_name"), merged.get("deploy_type"), json_dumps(merged.get("metadata", {})), merged["fetched_at"], ), ) sync_cluster_identity_references(conn, merged) stored = conn.execute( "SELECT * FROM cluster_metadata WHERE cluster_id = ?", (merged["cluster_id"],) ).fetchone() return row_to_cluster_metadata(stored) def cluster_metadata(params: dict[str, list[str]]) -> dict[str, Any]: cluster_ids = list( dict.fromkeys( part.strip() for value in params.get("cluster_id", []) for part in value.split(",") if part.strip() ) )[:50] refresh = params.get("refresh", [""])[0].lower() in {"1", "true", "yes"} cached: dict[str, dict[str, Any]] = {} if cluster_ids: placeholders = ",".join("?" for _ in cluster_ids) with get_conn() as conn: rows = conn.execute( f"SELECT * FROM cluster_metadata WHERE cluster_id IN ({placeholders})", cluster_ids, ).fetchall() cached = {row["cluster_id"]: row_to_cluster_metadata(row) for row in rows} for cluster_id in cluster_ids: if cluster_id in cached and not refresh: continue metadata = fetch_clinic_cluster_metadata(cluster_id) if metadata: cached[cluster_id] = upsert_cluster_metadata(metadata) return { "items": [ cached.get( cluster_id, { "cluster_id": cluster_id, "org_id": None, "dbaas_org_id": None, "tenant_id": None, "org_name": None, "cluster_name": None, "deploy_type": None, "metadata": {}, "fetched_at": None, "resolved": False, }, ) for cluster_id in cluster_ids ] } def known_scope_candidates(conn: sqlite3.Connection) -> dict[str, list[dict[str, Any]]]: metadata_rows = conn.execute("SELECT * FROM cluster_metadata").fetchall() metadata_by_cluster = { row["cluster_id"]: row_to_cluster_metadata(row) for row in metadata_rows } metadata_by_org: dict[str, dict[str, Any]] = {} for metadata in metadata_by_cluster.values(): if not metadata.get("org_name"): continue for org_id in (metadata.get("org_id"), metadata.get("dbaas_org_id")): if org_id: metadata_by_org[str(org_id)] = metadata identities = conn.execute( """ SELECT org_id, cluster_id, dimensions_json FROM ( SELECT org_id, cluster_id, dimensions_json, ROW_NUMBER() OVER ( PARTITION BY org_id, cluster_id ORDER BY created_at DESC, id DESC ) AS identity_rank FROM findings ) ranked_identities WHERE identity_rank = 1 ORDER BY org_id, cluster_id """ ).fetchall() organizations: dict[str, dict[str, str | None]] = {} clusters: list[dict[str, str | None]] = [] for identity in identities: org_id = str(identity["org_id"]) cluster_id = str(identity["cluster_id"]) dimensions = ensure_dict(json_loads(identity["dimensions_json"], {})) fixture = ensure_dict(dimensions.get("fixture_derivation")) reported_cluster = ensure_dict(dimensions.get("cluster")) metadata_cluster_id = report_value(fixture, "source_cluster_id") or cluster_id metadata = metadata_by_cluster.get(metadata_cluster_id) or metadata_by_cluster.get(cluster_id) org_metadata = metadata_by_org.get(org_id) or metadata org_name = ( str(org_metadata["org_name"]) if org_metadata and org_metadata.get("org_name") else optional_metadata_value(reported_cluster.get("org_name")) or org_id ) cluster_name = optional_metadata_value(reported_cluster.get("name")) or cluster_id if metadata and metadata.get("cluster_name"): cluster_name = str(metadata["cluster_name"]) if cluster_id != metadata_cluster_id: suffix = cluster_id.removeprefix(str(metadata_cluster_id)).lstrip("-_") if suffix: cluster_name = f"{cluster_name} · {suffix}" tenant_id = ( optional_metadata_value(org_metadata.get("tenant_id")) if org_metadata else optional_metadata_value( reported_cluster.get("dbaas_org_id") or reported_cluster.get("tenant_id") ) ) organizations[org_id] = { "id": org_id, "name": org_name, "tenant_id": tenant_id, } clusters.append( { "id": cluster_id, "name": cluster_name, "org_id": org_id, "org_name": org_name, "tenant_id": tenant_id, } ) return { "organizations": sorted(organizations.values(), key=lambda item: (item["name"], item["id"])), "clusters": sorted(clusters, key=lambda item: (item["org_name"], item["name"], item["id"])), } def scope_string_list( value: Any, field: str, *, max_items: int = 200, max_length: int = 160 ) -> list[str]: if value is None: return [] if not isinstance(value, list) or len(value) > max_items: raise ValueError(f"{field} must be a list with at most {max_items} entries") result: list[str] = [] for raw in value: if not isinstance(raw, str) or not raw.strip() or len(raw.strip()) > max_length: raise ValueError(f"{field} contains an invalid value") result.append(raw.strip()) return list(dict.fromkeys(result)) def normalize_cluster_scope_definition(value: Any) -> dict[str, Any]: source = ensure_dict(value) cluster_ids = scope_string_list(source.get("cluster_ids"), "definition.cluster_ids") excluded = scope_string_list( source.get("excluded_cluster_ids"), "definition.excluded_cluster_ids" ) raw_conditions = source.get("conditions") if raw_conditions is None and any( key in source for key in ("org_ids", "providers", "regions", "customer_regions") ): raw_conditions = [source] if raw_conditions is None: raw_conditions = [] if not isinstance(raw_conditions, list) or len(raw_conditions) > 20: raise ValueError("definition.conditions must contain at most 20 conditions") conditions: list[dict[str, list[str]]] = [] for index, raw_condition in enumerate(raw_conditions): if not isinstance(raw_condition, dict): raise ValueError(f"definition.conditions[{index}] must be an object") condition = { "org_ids": scope_string_list( raw_condition.get("org_ids"), f"definition.conditions[{index}].org_ids", ), "providers": scope_string_list( raw_condition.get("providers"), f"definition.conditions[{index}].providers", max_length=64, ), "regions": scope_string_list( raw_condition.get("regions"), f"definition.conditions[{index}].regions", ), "customer_regions": scope_string_list( raw_condition.get("customer_regions"), f"definition.conditions[{index}].customer_regions", ), } if any(condition.values()): conditions.append(condition) return { "cluster_ids": cluster_ids, "conditions": conditions, "excluded_cluster_ids": excluded, } def cluster_directory_candidates(conn: sqlite3.Connection) -> dict[str, dict[str, Any]]: candidates: dict[str, dict[str, Any]] = {} for item in known_scope_candidates(conn)["clusters"]: candidates[item["id"]] = { "cluster_id": item["id"], "cluster_name": item["name"], "org_id": item.get("org_id"), "org_name": item.get("org_name"), "tenant_id": item.get("tenant_id"), "provider": None, "region": None, "customer_region": None, "lifecycle": "unknown", "last_seen_at": None, "metadata_updated_at": None, } for row in conn.execute("SELECT * FROM cluster_metadata").fetchall(): item = row_to_cluster_metadata(row) metadata = ensure_dict(item.get("metadata")) cluster_id = item["cluster_id"] candidate = candidates.setdefault( cluster_id, { "cluster_id": cluster_id, "cluster_name": item.get("cluster_name") or cluster_id, "org_id": item.get("org_id"), "org_name": item.get("org_name"), "tenant_id": item.get("tenant_id"), "provider": None, "region": None, "customer_region": None, "lifecycle": "unknown", "last_seen_at": None, "metadata_updated_at": None, }, ) candidate.update( { "cluster_name": item.get("cluster_name") or candidate["cluster_name"], "org_id": item.get("org_id") or candidate.get("org_id"), "org_name": item.get("org_name") or candidate.get("org_name"), "tenant_id": item.get("tenant_id") or candidate.get("tenant_id"), "provider": metadata.get("cloud_provider") or metadata.get("provider"), "region": metadata.get("region"), "customer_region": metadata.get("customer_region"), "lifecycle": str(metadata.get("lifecycle") or metadata.get("status") or "active").lower(), "metadata_updated_at": item.get("fetched_at"), } ) for row in conn.execute( "SELECT cluster_id, cluster_name, org_id, org_name FROM cluster_scope_members" ).fetchall(): candidates.setdefault( row["cluster_id"], { "cluster_id": row["cluster_id"], "cluster_name": row["cluster_name"], "org_id": row["org_id"], "org_name": row["org_name"], "tenant_id": None, "provider": None, "region": None, "customer_region": None, "lifecycle": "unknown", "last_seen_at": None, "metadata_updated_at": None, }, ) for row in conn.execute( "SELECT cluster_id, MAX(created_at) AS last_seen_at FROM findings " "WHERE deleted_at IS NULL GROUP BY cluster_id" ).fetchall(): candidate = candidates.get(row["cluster_id"]) if candidate: candidate["last_seen_at"] = row["last_seen_at"] return candidates def cluster_scope_condition_matches( candidate: dict[str, Any], condition: dict[str, list[str]] ) -> bool: org_ids = set(condition.get("org_ids") or []) if org_ids and not org_ids.intersection( str(value) for value in (candidate.get("org_id"), candidate.get("tenant_id")) if value ): return False for field, candidate_key in ( ("providers", "provider"), ("regions", "region"), ("customer_regions", "customer_region"), ): expected = {value.casefold() for value in condition.get(field) or []} actual = str(candidate.get(candidate_key) or "").casefold() if expected and actual not in expected: return False return True def resolve_cluster_scope_definition( conn: sqlite3.Connection, definition: dict[str, Any], *, include_deleted: bool, ) -> tuple[list[dict[str, Any]], list[str]]: candidates = cluster_directory_candidates(conn) explicit_ids = list(definition.get("cluster_ids") or []) unresolved = [cluster_id for cluster_id in explicit_ids if cluster_id not in candidates] if unresolved and CLINIC_API_KEY: for cluster_id in unresolved: _, cluster = clinic_get_cluster_by_id(cluster_id) metadata = clinic_cluster_metadata_from_item(cluster) if cluster else None if metadata: upsert_cluster_metadata_with_conn(conn, metadata) candidates = cluster_directory_candidates(conn) unresolved = [cluster_id for cluster_id in explicit_ids if cluster_id not in candidates] included = {cluster_id for cluster_id in explicit_ids if cluster_id in candidates} for condition in definition.get("conditions") or []: included.update( cluster_id for cluster_id, candidate in candidates.items() if cluster_scope_condition_matches(candidate, condition) ) included.difference_update(definition.get("excluded_cluster_ids") or []) members = [ candidates[cluster_id] for cluster_id in included if include_deleted or candidates[cluster_id].get("lifecycle") != "deleted" ] members.sort( key=lambda item: ( str(item.get("org_name") or item.get("org_id") or ""), str(item.get("cluster_name") or item["cluster_id"]), item["cluster_id"], ) ) return members, unresolved def replace_cluster_scope_members( conn: sqlite3.Connection, scope_id: str, members: list[dict[str, Any]], timestamp: str, ) -> None: conn.execute("DELETE FROM cluster_scope_members WHERE scope_id = ?", (scope_id,)) for member in members: conn.execute( """ INSERT INTO cluster_scope_members (id, scope_id, cluster_id, cluster_name, org_id, org_name, reason, created_at) VALUES (?, ?, ?, ?, ?, ?, 'scope_definition', ?) """, ( new_id("scope_member"), scope_id, member["cluster_id"], member.get("cluster_name") or member["cluster_id"], member.get("org_id") or "unknown", member.get("org_name"), timestamp, ), ) def cluster_scope_members( conn: sqlite3.Connection, row: sqlite3.Row ) -> list[dict[str, Any]]: definition = normalize_cluster_scope_definition(json_loads(row["definition_json"], {})) if row["membership_mode"] == "dynamic": members, _ = resolve_cluster_scope_definition( conn, definition, include_deleted=bool(row["include_deleted"]) ) return members directory = cluster_directory_candidates(conn) result: list[dict[str, Any]] = [] for member in conn.execute( "SELECT * FROM cluster_scope_members WHERE scope_id = ? " "ORDER BY org_name, cluster_name, cluster_id", (row["id"],), ).fetchall(): latest = directory.get(member["cluster_id"], {}) result.append( { **latest, "cluster_id": member["cluster_id"], "cluster_name": latest.get("cluster_name") or member["cluster_name"], "org_id": latest.get("org_id") or member["org_id"], "org_name": latest.get("org_name") or member["org_name"], "reason": member["reason"], } ) return result def row_to_cluster_scope( conn: sqlite3.Connection, row: sqlite3.Row, *, default_scope_id: str | None = None, ) -> dict[str, Any]: members = cluster_scope_members(conn, row) org_ids = sorted({str(member.get("org_id")) for member in members if member.get("org_id")}) return { "id": row["id"], "name": row["name"], "description": row["description"], "owner_id": row["owner_id"], "visibility": row["visibility"], "membership_mode": row["membership_mode"], "definition": normalize_cluster_scope_definition( json_loads(row["definition_json"], {}) ), "include_deleted": bool(row["include_deleted"]), "is_recommended": bool(row["is_recommended"]), "is_default": row["id"] == default_scope_id, "can_edit": row["owner_id"] == current_user_id() and not bool(row["is_recommended"]), "member_count": len(members), "organization_count": len(org_ids), "org_id": org_ids[0] if len(org_ids) == 1 else None, "is_cross_org": len(org_ids) > 1, "members": members, "created_at": row["created_at"], "updated_at": row["updated_at"], "resolved_at": now_iso(), } def visible_cluster_scope_row( conn: sqlite3.Connection, scope_id: str ) -> sqlite3.Row | None: return conn.execute( "SELECT * FROM cluster_scopes WHERE id = ? AND (owner_id = ? OR visibility = 'public')", (scope_id, current_user_id()), ).fetchone() def cluster_scope_library() -> dict[str, Any]: with get_conn() as conn: preference = conn.execute( "SELECT default_cluster_scope_id FROM user_preferences WHERE owner_id = ?", (current_user_id(),), ).fetchone() default_scope_id = preference["default_cluster_scope_id"] if preference else None rows = conn.execute( "SELECT * FROM cluster_scopes WHERE owner_id = ? OR visibility = 'public' " "ORDER BY is_recommended DESC, name, id", (current_user_id(),), ).fetchall() scopes = [ row_to_cluster_scope(conn, row, default_scope_id=default_scope_id) for row in rows ] recommended_scope_id = next( (scope["id"] for scope in scopes if scope["is_recommended"]), None ) return { "owner_id": current_user_id(), "default_scope_id": default_scope_id, "recommended_scope_id": recommended_scope_id, "my_scopes": [scope for scope in scopes if scope["owner_id"] == current_user_id()], "shared_scopes": [scope for scope in scopes if scope["owner_id"] != current_user_id()], } def cluster_scope_detail(scope_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = visible_cluster_scope_row(conn, scope_id) if not row: return 404, {"error": "cluster_scope_not_found"} preference = conn.execute( "SELECT default_cluster_scope_id FROM user_preferences WHERE owner_id = ?", (current_user_id(),), ).fetchone() default_scope_id = preference["default_cluster_scope_id"] if preference else None return 200, { "cluster_scope": row_to_cluster_scope( conn, row, default_scope_id=default_scope_id ) } def cluster_scope_payload( payload: dict[str, Any], existing: sqlite3.Row | None = None ) -> dict[str, Any]: name = ( require_string(payload, "name", max_length=160) if "name" in payload or existing is None else existing["name"] ) description = ( optional_string(payload.get("description"), "description", 2000) if "description" in payload or existing is None else existing["description"] ) visibility = str( payload.get("visibility", existing["visibility"] if existing else "private") ).lower() membership_mode = str( payload.get( "membership_mode", existing["membership_mode"] if existing else "snapshot" ) ).lower() if visibility not in CLUSTER_SCOPE_VISIBILITIES: raise ValueError("visibility must be private or public") if membership_mode not in CLUSTER_SCOPE_MEMBERSHIP_MODES: raise ValueError("membership_mode must be snapshot or dynamic") include_deleted_value = payload.get( "include_deleted", bool(existing["include_deleted"]) if existing else True ) if not isinstance(include_deleted_value, bool): raise ValueError("include_deleted must be a boolean") existing_definition = ( json_loads(existing["definition_json"], {}) if existing else {} ) definition = normalize_cluster_scope_definition( payload.get("definition", existing_definition) ) if "member_ids" in payload: definition["cluster_ids"] = scope_string_list( payload.get("member_ids"), "member_ids" ) if not definition["cluster_ids"] and not definition["conditions"]: raise ValueError("At least one Cluster or matching condition is required") return { "name": name, "description": description, "visibility": visibility, "membership_mode": membership_mode, "include_deleted": include_deleted_value, "definition": definition, } def cluster_scope_preview(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: parsed = cluster_scope_payload( {"name": payload.get("name") or "Preview", **payload} ) except ValueError as exc: return 400, {"error": "invalid_cluster_scope", "message": str(exc)} with get_conn() as conn: members, unresolved = resolve_cluster_scope_definition( conn, parsed["definition"], include_deleted=parsed["include_deleted"], ) org_ids = {member.get("org_id") for member in members if member.get("org_id")} return 200, { "member_count": len(members), "organization_count": len(org_ids), "unresolved_cluster_ids": unresolved, "members": members[:100], "definition": parsed["definition"], } def create_cluster_scope(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: parsed = cluster_scope_payload(payload) except ValueError as exc: return 400, {"error": "invalid_cluster_scope", "message": str(exc)} with get_conn() as conn: members, unresolved = resolve_cluster_scope_definition( conn, parsed["definition"], include_deleted=parsed["include_deleted"], ) if unresolved: return 400, { "error": "unknown_cluster_ids", "message": "Some selected Clusters could not be resolved.", "cluster_ids": unresolved, } if parsed["membership_mode"] == "snapshot" and not members: return 400, {"error": "empty_cluster_scope"} timestamp = now_iso() scope_id = new_id("scope") conn.execute( """ INSERT INTO cluster_scopes (id, name, description, owner_id, visibility, membership_mode, definition_json, include_deleted, is_recommended, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?) """, ( scope_id, parsed["name"], parsed["description"], current_user_id(), parsed["visibility"], parsed["membership_mode"], json_dumps(parsed["definition"]), int(parsed["include_deleted"]), timestamp, timestamp, ), ) if parsed["membership_mode"] == "snapshot": replace_cluster_scope_members(conn, scope_id, members, timestamp) row = conn.execute("SELECT * FROM cluster_scopes WHERE id = ?", (scope_id,)).fetchone() return 201, {"cluster_scope": row_to_cluster_scope(conn, row)} def update_cluster_scope( scope_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = conn.execute( "SELECT * FROM cluster_scopes WHERE id = ? AND owner_id = ? AND is_recommended = 0", (scope_id, current_user_id()), ).fetchone() if not row: return 404, {"error": "cluster_scope_not_found"} try: parsed = cluster_scope_payload(payload, row) except ValueError as exc: return 400, {"error": "invalid_cluster_scope", "message": str(exc)} members, unresolved = resolve_cluster_scope_definition( conn, parsed["definition"], include_deleted=parsed["include_deleted"], ) if unresolved: return 400, { "error": "unknown_cluster_ids", "cluster_ids": unresolved, } if parsed["membership_mode"] == "snapshot" and not members: return 400, {"error": "empty_cluster_scope"} timestamp = now_iso() conn.execute( """ UPDATE cluster_scopes SET name = ?, description = ?, visibility = ?, membership_mode = ?, definition_json = ?, include_deleted = ?, updated_at = ? WHERE id = ? """, ( parsed["name"], parsed["description"], parsed["visibility"], parsed["membership_mode"], json_dumps(parsed["definition"]), int(parsed["include_deleted"]), timestamp, scope_id, ), ) if parsed["membership_mode"] == "snapshot": replace_cluster_scope_members(conn, scope_id, members, timestamp) else: conn.execute("DELETE FROM cluster_scope_members WHERE scope_id = ?", (scope_id,)) updated = conn.execute("SELECT * FROM cluster_scopes WHERE id = ?", (scope_id,)).fetchone() return 200, {"cluster_scope": row_to_cluster_scope(conn, updated)} def delete_cluster_scope(scope_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = conn.execute( "SELECT id FROM cluster_scopes " "WHERE id = ? AND owner_id = ? AND is_recommended = 0", (scope_id, current_user_id()), ).fetchone() if not row: return 404, {"error": "cluster_scope_not_found"} conn.execute( "UPDATE user_preferences SET default_cluster_scope_id = NULL, updated_at = ? " "WHERE default_cluster_scope_id = ?", (now_iso(), scope_id), ) conn.execute( "DELETE FROM cluster_scope_members WHERE scope_id = ?", (scope_id,) ) conn.execute("DELETE FROM cluster_scopes WHERE id = ?", (scope_id,)) return 200, {"deleted": True, "id": scope_id} def set_default_cluster_scope(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: scope_id = payload.get("scope_id") if scope_id is not None and (not isinstance(scope_id, str) or not scope_id): return 400, {"error": "invalid_cluster_scope"} with get_conn() as conn: if scope_id and not visible_cluster_scope_row(conn, scope_id): return 404, {"error": "cluster_scope_not_found"} timestamp = now_iso() conn.execute( dialect_sql( conn, """ INSERT INTO user_preferences (owner_id, default_cluster_scope_id, updated_at) VALUES (?, ?, ?) ON CONFLICT(owner_id) DO UPDATE SET default_cluster_scope_id = excluded.default_cluster_scope_id, updated_at = excluded.updated_at """, """ INSERT INTO user_preferences (owner_id, default_cluster_scope_id, updated_at) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE default_cluster_scope_id = VALUES(default_cluster_scope_id), updated_at = VALUES(updated_at) """, ), (current_user_id(), scope_id, timestamp), ) return 200, {"default_scope_id": scope_id, "updated_at": timestamp} def row_to_followed_scope(row: sqlite3.Row) -> dict[str, Any]: return { "id": row["id"], "type": row["scope_type"], "resource_id": row["scope_id"], "name": row["scope_name"], "org_id": row["org_id"], "org_name": row["org_name"], "tenant_id": row["tenant_id"], "created_at": row["created_at"], "updated_at": row["updated_at"], } def ensure_default_followed_scopes(conn: sqlite3.Connection) -> None: initialized = conn.execute( "SELECT 1 FROM user_scope_settings WHERE owner_id = ?", (current_user_id(),), ).fetchone() if initialized: return timestamp = now_iso() candidates = known_scope_candidates(conn) for organization in candidates["organizations"]: conn.execute( insert_ignore_sql( conn, """ INSERT OR IGNORE INTO followed_scopes (id, owner_id, scope_type, scope_id, scope_name, org_id, org_name, tenant_id, created_at, updated_at) VALUES (?, ?, 'organization', ?, ?, ?, ?, ?, ?, ?) """, ), ( new_id("scope"), current_user_id(), organization["id"], organization["name"], organization["id"], organization["name"], organization.get("tenant_id"), timestamp, timestamp, ), ) for cluster in candidates["clusters"]: conn.execute( insert_ignore_sql( conn, """ INSERT OR IGNORE INTO followed_scopes (id, owner_id, scope_type, scope_id, scope_name, org_id, org_name, tenant_id, created_at, updated_at) VALUES (?, ?, 'cluster', ?, ?, ?, ?, ?, ?, ?) """, ), ( new_id("scope"), current_user_id(), cluster["id"], cluster["name"], cluster["org_id"], cluster["org_name"], cluster.get("tenant_id"), timestamp, timestamp, ), ) conn.execute( "INSERT INTO user_scope_settings (owner_id, initialized_at) VALUES (?, ?)", (current_user_id(), timestamp), ) def row_to_cluster_group(conn: sqlite3.Connection, row: sqlite3.Row) -> dict[str, Any]: members = [ { "id": member["id"], "cluster_id": member["member_id"], "cluster_name": member["member_name"], "org_id": member["org_id"], "org_name": member["org_name"], "reason": member["reason"], } for member in conn.execute( "SELECT * FROM group_members WHERE group_id = ? ORDER BY org_name, member_name, member_id", (row["id"],), ).fetchall() ] org_ids = sorted({member["org_id"] for member in members}) return { "id": row["id"], "name": row["name"], "description": row["description"], "status": row["status"], "org_id": org_ids[0] if len(org_ids) == 1 else None, "organization_count": len(org_ids), "is_cross_org": len(org_ids) > 1, "member_count": len(members), "members": members, "created_at": row["created_at"], "updated_at": row["updated_at"], } def scope_library() -> dict[str, Any]: with get_conn() as conn: ensure_default_followed_scopes(conn) organizations = [ row_to_followed_scope(row) for row in conn.execute( "SELECT * FROM followed_scopes WHERE owner_id = ? AND scope_type = 'organization' " "ORDER BY scope_name, scope_id", (current_user_id(),), ).fetchall() ] clusters = [ row_to_followed_scope(row) for row in conn.execute( "SELECT * FROM followed_scopes WHERE owner_id = ? AND scope_type = 'cluster' " "ORDER BY org_name, scope_name, scope_id", (current_user_id(),), ).fetchall() ] groups = [ row_to_cluster_group(conn, row) for row in conn.execute( "SELECT * FROM `groups` WHERE owner_id = ? AND group_type = 'cluster_group' " "AND status = 'active' ORDER BY name, id", (current_user_id(),), ).fetchall() ] return { "owner_id": current_user_id(), "organizations": organizations, "clusters": clusters, "cluster_groups": groups, } def resolve_followed_scope_candidate( scope_type: str, resource_id: str, tenant_id: str | None ) -> dict[str, Any] | None: with get_conn() as conn: candidates = known_scope_candidates(conn) candidate_key = "organizations" if scope_type == "organization" else "clusters" known = next( (item for item in candidates[candidate_key] if item["id"] == resource_id), None, ) if scope_type == "cluster": _, cluster = clinic_get_cluster_by_id(resource_id) if not cluster: return known metadata = clinic_cluster_metadata_from_item(cluster) if not metadata or not metadata.get("tenant_id"): return known metadata["org_name"] = known_org_display_name(metadata["tenant_id"]) stored = upsert_cluster_metadata(metadata) return clinic_cluster_scope_candidate_from_metadata(stored) dbaas_org_id = resolve_dbaas_org_id(resource_id, tenant_id) status, payload = clinic_list_org_clusters(dbaas_org_id, limit=1, page=1) if status != 200 or payload is None: return known known_name = meaningful_scope_name(known.get("name"), resource_id) if known else None org_name = ( known_name or known_org_display_name(resource_id) or known_org_display_name(dbaas_org_id) ) return { "id": resource_id, "name": org_name or resource_id, "org_id": resource_id, "org_name": org_name, "tenant_id": dbaas_org_id, } def create_followed_scope(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: scope_type = require_string(payload, "type", max_length=32) resource_id = require_string(payload, "resource_id", max_length=128) tenant_id = optional_string(payload.get("tenant_id"), "tenant_id", 128) except ValueError as exc: return 400, {"error": "invalid_followed_scope", "message": str(exc)} if scope_type not in {"organization", "cluster"}: return 400, {"error": "invalid_scope_type"} candidate = resolve_followed_scope_candidate(scope_type, resource_id, tenant_id) if not candidate: return 404, {"error": "scope_candidate_not_found"} with get_conn() as conn: existing = conn.execute( "SELECT * FROM followed_scopes WHERE owner_id = ? AND scope_type = ? AND scope_id = ?", (current_user_id(), scope_type, resource_id), ).fetchone() if existing: return 200, {"scope": row_to_followed_scope(existing), "created": False} timestamp = now_iso() scope_id = new_id("scope") org_id = candidate["id"] if scope_type == "organization" else candidate["org_id"] org_name = candidate["name"] if scope_type == "organization" else candidate["org_name"] conn.execute( """ INSERT INTO followed_scopes (id, owner_id, scope_type, scope_id, scope_name, org_id, org_name, tenant_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( scope_id, current_user_id(), scope_type, resource_id, candidate["name"], org_id, org_name, candidate.get("tenant_id"), timestamp, timestamp, ), ) row = conn.execute("SELECT * FROM followed_scopes WHERE id = ?", (scope_id,)).fetchone() return 201, {"scope": row_to_followed_scope(row), "created": True} def delete_followed_scope(scope_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: cursor = conn.execute( "DELETE FROM followed_scopes WHERE id = ? AND owner_id = ?", (scope_id, current_user_id()), ) if not cursor.rowcount: return 404, {"error": "followed_scope_not_found"} return 200, {"deleted": True, "id": scope_id} def resolve_group_members( conn: sqlite3.Connection, member_ids: Any ) -> tuple[list[dict[str, Any]] | None, dict[str, Any] | None]: if not isinstance(member_ids, list) or not member_ids or len(member_ids) > 100: return None, {"error": "invalid_group_members", "message": "member_ids must contain 1 to 100 clusters"} requested = list(dict.fromkeys(str(value) for value in member_ids if value)) candidates = {item["id"]: item for item in known_scope_candidates(conn)["clusters"]} unresolved = [cluster_id for cluster_id in requested if cluster_id not in candidates] if unresolved and CLINIC_API_KEY: for cluster_id in unresolved: _, cluster = clinic_get_cluster_by_id(cluster_id) metadata = clinic_cluster_metadata_from_item(cluster) if cluster else None if not metadata: continue stored = upsert_cluster_metadata_with_conn(conn, metadata) candidate = clinic_cluster_scope_candidate_from_metadata(stored) if candidate: candidates[candidate["id"]] = candidate if len(requested) != len(member_ids) or any(cluster_id not in candidates for cluster_id in requested): return None, {"error": "invalid_group_members", "message": "Every member must be a known cluster"} return [candidates[cluster_id] for cluster_id in requested], None def replace_group_members( conn: sqlite3.Connection, group_id: str, members: list[dict[str, Any]], timestamp: str ) -> None: conn.execute("DELETE FROM group_members WHERE group_id = ?", (group_id,)) for member in members: conn.execute( """ INSERT INTO group_members (id, group_id, member_type, member_id, member_name, org_id, org_name, reason, created_at) VALUES (?, ?, 'cluster', ?, ?, ?, ?, ?, ?) """, ( new_id("member"), group_id, member["id"], member["name"], member["org_id"], member["org_name"], "Included in this observation scope", timestamp, ), ) def create_cluster_group(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: name = require_string(payload, "name", max_length=160) description = optional_string(payload.get("description"), "description", 2000) except ValueError as exc: return 400, {"error": "invalid_cluster_group", "message": str(exc)} with get_conn() as conn: members, error = resolve_group_members(conn, payload.get("member_ids")) if error: return 400, error timestamp = now_iso() group_id = new_id("group") org_ids = {member["org_id"] for member in members or []} conn.execute( """ INSERT INTO `groups` (id, group_type, name, description, org_id, owner_id, status, created_at, updated_at) VALUES (?, 'cluster_group', ?, ?, ?, ?, 'active', ?, ?) """, ( group_id, name, description, next(iter(org_ids)) if len(org_ids) == 1 else None, current_user_id(), timestamp, timestamp, ), ) replace_group_members(conn, group_id, members or [], timestamp) row = conn.execute("SELECT * FROM `groups` WHERE id = ?", (group_id,)).fetchone() return 201, {"cluster_group": row_to_cluster_group(conn, row)} def cluster_group_detail(group_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = conn.execute( "SELECT * FROM `groups` WHERE id = ? AND owner_id = ? AND group_type = 'cluster_group'", (group_id, current_user_id()), ).fetchone() if not row: return 404, {"error": "cluster_group_not_found"} return 200, {"cluster_group": row_to_cluster_group(conn, row)} def update_cluster_group(group_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = conn.execute( "SELECT * FROM `groups` WHERE id = ? AND owner_id = ? AND group_type = 'cluster_group'", (group_id, current_user_id()), ).fetchone() if not row: return 404, {"error": "cluster_group_not_found"} try: name = require_string(payload, "name", max_length=160) if "name" in payload else row["name"] description = optional_string(payload.get("description"), "description", 2000) if "description" in payload else row["description"] except ValueError as exc: return 400, {"error": "invalid_cluster_group", "message": str(exc)} members = None if "member_ids" in payload: members, error = resolve_group_members(conn, payload.get("member_ids")) if error: return 400, error else: members = [ { "id": member["member_id"], "name": member["member_name"], "org_id": member["org_id"], "org_name": member["org_name"], } for member in conn.execute( "SELECT * FROM group_members WHERE group_id = ?", (group_id,) ).fetchall() ] timestamp = now_iso() org_ids = {member["org_id"] for member in members or []} conn.execute( "UPDATE `groups` SET name = ?, description = ?, org_id = ?, updated_at = ? WHERE id = ?", (name, description, next(iter(org_ids)) if len(org_ids) == 1 else None, timestamp, group_id), ) if "member_ids" in payload: replace_group_members(conn, group_id, members or [], timestamp) updated = conn.execute("SELECT * FROM `groups` WHERE id = ?", (group_id,)).fetchone() return 200, {"cluster_group": row_to_cluster_group(conn, updated)} def delete_cluster_group(group_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = conn.execute( "SELECT id FROM `groups` " "WHERE id = ? AND owner_id = ? AND group_type = 'cluster_group'", (group_id, current_user_id()), ).fetchone() if not row: return 404, {"error": "cluster_group_not_found"} conn.execute("DELETE FROM group_members WHERE group_id = ?", (group_id,)) conn.execute("DELETE FROM `groups` WHERE id = ?", (group_id,)) return 200, {"deleted": True, "id": group_id} def row_to_finding_run(row: sqlite3.Row) -> dict[str, Any]: result = dict(row) result.pop("idempotency_key", None) result["metadata"] = json_loads(result.pop("metadata_json", None), {}) return result def compact_finding( row: sqlite3.Row, symptoms: list[dict[str, Any]] | None = None ) -> dict[str, Any]: result = row_to_finding(row, symptoms) result["evidence_ref_count"] = len(result.get("evidence_refs", [])) result.pop("evidence_refs", None) result.pop("raw_payload", None) for symptom in result.get("symptoms", []): symptom["evidence_ref_count"] = len(symptom.get("evidence_refs", [])) symptom.pop("evidence_refs", None) return result def rows_to_findings( conn: sqlite3.Connection, rows: list[sqlite3.Row], *, compact: bool = False, ) -> list[dict[str, Any]]: symptom_map = load_finding_symptoms(conn, [row["id"] for row in rows]) converter = compact_finding if compact else row_to_finding return [converter(row, symptom_map.get(row["id"], [])) for row in rows] def attach_catalog_postures( conn: sqlite3.Connection, findings: list[dict[str, Any]] ) -> None: item_ids = list( dict.fromkeys( str(finding.get("catalog_item_id") or "") for finding in findings if finding.get("catalog_item_id") ) ) postures: dict[str, dict[str, Any] | None] = {} if item_ids: placeholders = ",".join("?" for _ in item_ids) rows = conn.execute( f"SELECT * FROM catalog_items WHERE id IN ({placeholders})", item_ids ).fetchall() projected, _ = project_catalog_items(conn, rows) postures = { str(item["id"]): item["current_posture"] for item in projected } for finding in findings: item_id = str(finding.get("catalog_item_id") or "") if not item_id: finding["catalog_posture"] = None continue finding["catalog_posture"] = postures.get(item_id) def attach_active_treatment_ids( conn: sqlite3.Connection, findings: list[dict[str, Any]] ) -> None: finding_ids = [str(finding["id"]) for finding in findings] treatments_by_finding: dict[str, list[str]] = { finding_id: [] for finding_id in finding_ids } if finding_ids: placeholders = ",".join("?" for _ in finding_ids) rows = conn.execute( f""" SELECT r.from_id AS finding_id, t.id FROM relations r JOIN treatments t ON t.id = r.to_id WHERE r.from_type = 'finding' AND r.relation_type = 'evidence_of' AND r.to_type = 'treatment' AND t.state = 'active' AND r.from_id IN ({placeholders}) ORDER BY r.from_id, t.updated_at DESC, t.id """, finding_ids, ).fetchall() for row in rows: treatments_by_finding[str(row["finding_id"])].append(str(row["id"])) for finding in findings: finding["linked_active_treatment_ids"] = treatments_by_finding.get( str(finding["id"]), [] ) def row_to_catalog_item(row: sqlite3.Row) -> dict[str, Any]: result = dict(row) result["labels"] = json_loads(result.pop("labels_json", None), []) result["is_orphaned"] = bool(result.get("orphaned_at")) result["lifecycle"] = "archived" if result.get("archived_at") else "active" return result def row_to_symptom_definition( row: sqlite3.Row, locale: str = "en" ) -> dict[str, Any]: result = dict(row) code = str(result.get("code") or "") if code in SYMPTOM_NAMES: result["name"] = translate( f"domain:symptom.{code}.name", locale, default=result["name"] ) result["description"] = translate( f"domain:symptom.{code}.description", locale, default=result["description"], ) result["category_name"] = translate( f"domain:symptom.categories.{result.get('category')}", locale, default=str(result.get("category") or ""), ) return result def row_to_treatment(row: sqlite3.Row) -> dict[str, Any]: result = dict(row) result["labels"] = json_loads(result.pop("labels_json", None), []) return result def row_to_record(row: sqlite3.Row) -> dict[str, Any]: result = dict(row) result["structured_fields"] = json_loads(result.pop("structured_fields_json", None), {}) return result def timeline_domain_label(locale: str, path: str, value: Any) -> str: if value is None or value == "": return translate("common:state.unknown", locale) code = str(value) return translate(f"domain:{path}.{code}", locale, default=code.replace("_", " ").title()) def localized_timeline_summary( event_type: str, payload: dict[str, Any], locale: str, fallback: str, ) -> str: known_events = { "catalog_item_created", "catalog_item_reappeared", "catalog_item_status_changed", "catalog_item_updated", "finding_deleted", "finding_ingested", "finding_linked", "finding_relation_review_needed", "finding_restored", "findings_deleted", "findings_restored", "observation_started", "recommendation_shared", "record_created", "record_updated", "treatment_cancelled", "treatment_completed", "treatment_created", "treatment_milestone", "treatment_record_created", "treatment_reopened", "treatment_stage_changed", "treatment_updated", } if event_type not in known_events: return fallback stage = payload.get("to") or payload.get("stage") outcome = payload.get("outcome") return translate( f"timeline:audit.summary.{event_type}", locale, params={ "stage": timeline_domain_label(locale, "treatment.stage", stage), "outcome": timeline_domain_label(locale, "treatment.outcome", outcome), "title": payload.get("record_title") or translate("domain:entity.record", locale), }, default=fallback, ) def row_to_timeline( row: sqlite3.Row, locale: str = "en" ) -> dict[str, Any]: result = dict(row) result["payload"] = json_loads(result.pop("payload_json", None), {}) result["summary"] = localized_timeline_summary( str(result.get("event_type") or "system_event"), result["payload"], locale, str(result.get("summary") or ""), ) return result def add_relation( conn: sqlite3.Connection, from_type: str, from_id: str, relation_type: str, to_type: str, to_id: str, created_at: str | None = None, ) -> None: conn.execute( insert_ignore_sql( conn, """ INSERT OR IGNORE INTO relations (id, from_type, from_id, relation_type, to_type, to_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?) """, ), ( new_id("rel"), from_type, from_id, relation_type, to_type, to_id, created_at or now_iso(), ), ) def add_timeline( conn: sqlite3.Connection, event_type: str, target_type: str, target_id: str, summary: str, payload: dict[str, Any] | None = None, actor: str | None = None, occurred_at: str | None = None, ) -> None: conn.execute( """ INSERT INTO timeline_events (id, event_type, target_type, target_id, actor, summary, payload_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) """, ( new_id("evt"), event_type, target_type, target_id, actor, summary, json_dumps(payload or {}), occurred_at or now_iso(), ), ) def get_catalog_item(conn: sqlite3.Connection, item_id: str) -> dict[str, Any] | None: row = conn.execute("SELECT * FROM catalog_items WHERE id = ?", (item_id,)).fetchone() return row_to_catalog_item(row) if row else None def catalog_item_registration( conn: sqlite3.Connection, item: dict[str, Any] ) -> dict[str, Any]: row = conn.execute( f""" SELECT actor, payload_json, created_at FROM timeline_events WHERE target_type = 'catalog_item' AND target_id = ? AND event_type = 'catalog_item_created' ORDER BY created_at ASC, {timeline_sequence_sql(conn)} ASC LIMIT 1 """, (item["id"],), ).fetchone() return catalog_registration_from_event(item, dict(row) if row else None) def catalog_registration_from_event( item: dict[str, Any], event: dict[str, Any] | None ) -> dict[str, Any]: if not event: return { "origin": "unknown", "reason": "unknown", "registered_by": None, "registered_at": item.get("created_at"), } payload = event.get("payload") if not isinstance(payload, dict): payload = json_loads(event.get("payload_json"), {}) return { "origin": payload.get("registration_origin") or "finding", "reason": payload.get("registration_reason") or "first_finding", "source_reference": payload.get("source_reference"), "source_url": payload.get("source_url"), "initial_action": payload.get("initial_action"), "registered_by": event.get("actor"), "registered_at": item.get("created_at") or event.get("created_at"), } def get_treatment(conn: sqlite3.Connection, treatment_id: str) -> dict[str, Any] | None: row = conn.execute("SELECT * FROM treatments WHERE id = ?", (treatment_id,)).fetchone() return row_to_treatment(row) if row else None def get_record(conn: sqlite3.Connection, record_id: str) -> dict[str, Any] | None: row = conn.execute("SELECT * FROM records WHERE id = ?", (record_id,)).fetchone() return row_to_record(row) if row else None def target_exists(conn: sqlite3.Connection, target_type: str, target_id: str) -> bool: if target_type == "catalog_item": return get_catalog_item(conn, target_id) is not None if target_type == "treatment": return get_treatment(conn, target_id) is not None if target_type == "finding": return ( conn.execute("SELECT 1 FROM findings WHERE id = ?", (target_id,)).fetchone() is not None ) return False def record_targets(conn: sqlite3.Connection, record_id: str) -> list[dict[str, str]]: return [ {"type": row["to_type"], "id": row["to_id"]} for row in conn.execute( """ SELECT to_type, to_id FROM relations WHERE from_type = 'record' AND from_id = ? AND relation_type = 'record_of' ORDER BY created_at """, (record_id,), ).fetchall() ] def record_is_linked( conn: sqlite3.Connection, record_id: str, target_type: str, target_id: str, ) -> bool: return ( conn.execute( """ SELECT 1 FROM relations WHERE from_type = 'record' AND from_id = ? AND relation_type = 'record_of' AND to_type = ? AND to_id = ? """, (record_id, target_type, target_id), ).fetchone() is not None ) def linked_catalog_item_ids(conn: sqlite3.Connection, treatment_id: str) -> list[str]: return [ row["to_id"] for row in conn.execute( """ SELECT to_id FROM relations WHERE from_type = 'treatment' AND from_id = ? AND relation_type = 'treatment_for' AND to_type = 'catalog_item' """, (treatment_id,), ).fetchall() ] RECORD_OUTPUT_REQUIREMENTS: dict[str, tuple[str, ...]] = { "triage_record": ("conclusion_type", "confidence"), "analysis_record": ("conclusion_type", "confidence"), "proposal_record": ("action_type", "risk_level"), "no_action_record": ("conclusion_type", "confidence"), } def markdown_has_substantive_content(value: str | None) -> bool: for raw_line in (value or "").splitlines(): line = raw_line.strip() if not line or line.startswith("#"): continue line = re.sub(r"^[>*+-]\s*", "", line).strip() line = line.strip("`*_~ ") if line: return True return False def record_content_error( record_type: str, structured_fields: dict[str, Any], body_markdown: str, visibility: str, review_status: str, ) -> dict[str, Any] | None: requires_complete_output = ( record_type in RECORD_OUTPUT_REQUIREMENTS and review_status in {"ready", "reviewed"} ) requires_customer_output = visibility == "customer_visible" if not requires_complete_output and not requires_customer_output: return None missing = [ field for field in RECORD_OUTPUT_REQUIREMENTS.get(record_type, ()) if structured_fields.get(field) is None or structured_fields.get(field) == "" ] if not markdown_has_substantive_content(body_markdown): missing.append("body_markdown") if not missing: return None return { "error": "record_content_required", "message": "Complete the required structured fields and add substantive notes before this Record is ready or customer-visible.", "details": {"record_type": record_type, "missing_fields": missing}, } def is_shared_recommendation(record: dict[str, Any] | None) -> bool: return bool( record and record.get("record_type") == "proposal_record" and record.get("visibility") == "customer_visible" and record.get("review_status") == "reviewed" and not record_content_error( str(record.get("record_type")), record.get("structured_fields") or {}, str(record.get("body_markdown") or ""), str(record.get("visibility")), str(record.get("review_status")), ) ) def record_recommendation_shared( conn: sqlite3.Connection, treatment_id: str, record: dict[str, Any], *, actor: str, occurred_at: str, ) -> None: if not is_shared_recommendation(record): return existing = conn.execute( """ SELECT payload_json FROM timeline_events WHERE target_type = 'treatment' AND target_id = ? AND event_type = 'recommendation_shared' """, (treatment_id,), ).fetchall() if any(json_loads(row["payload_json"], {}).get("record_id") == record["id"] for row in existing): return payload = {"record_id": record["id"], "record_title": record["title"]} treatment = get_treatment(conn, treatment_id) if treatment and treatment["state"] == "active" and treatment["stage"] in {"assessment", "planning"}: conn.execute( "UPDATE treatments SET stage = 'alignment', updated_at = ? WHERE id = ?", (occurred_at, treatment_id), ) add_timeline( conn, "treatment_stage_changed", "treatment", treatment_id, "Treatment moved to alignment", { "from": treatment["stage"], "to": "alignment", "trigger": "recommendation_shared", **payload, }, actor, occurred_at, ) for item_id in linked_catalog_item_ids(conn, treatment_id): add_timeline( conn, "treatment_milestone", "catalog_item", item_id, "Treatment moved to alignment", { "treatment_id": treatment_id, "stage": "alignment", "trigger": "recommendation_shared", **payload, }, actor, occurred_at, ) add_timeline( conn, "recommendation_shared", "treatment", treatment_id, f"Recommendation shared: {record['title']}", payload, actor, occurred_at, ) for item_id in linked_catalog_item_ids(conn, treatment_id): add_timeline( conn, "recommendation_shared", "catalog_item", item_id, f"Treatment recommendation shared: {record['title']}", {**payload, "treatment_id": treatment_id}, actor, occurred_at, ) def latest_catalog_event( conn: sqlite3.Connection, item_id: str, event_types: tuple[str, ...] ) -> dict[str, Any] | None: placeholders = ",".join("?" for _ in event_types) sequence_sql = timeline_sequence_sql(conn) row = conn.execute( f""" SELECT {sequence_sql} AS sequence, timeline_events.* FROM timeline_events WHERE target_type = 'catalog_item' AND target_id = ? AND event_type IN ({placeholders}) ORDER BY created_at DESC, {sequence_sql} DESC LIMIT 1 """, (item_id, *event_types), ).fetchone() if not row: return None result = dict(row) result["payload"] = json_loads(result.pop("payload_json", None), {}) return result def latest_preloaded_catalog_event( events: list[dict[str, Any]], event_types: tuple[str, ...] ) -> dict[str, Any] | None: matching = [event for event in events if event["event_type"] in event_types] if not matching: return None result = dict( max( matching, key=lambda event: ( event["created_at"], int(event.get("sequence") or event.get("event_sequence") or 0), ), ) ) result["sequence"] = int( result.get("sequence") or result.get("event_sequence") or 0 ) return result def max_severity(values: list[str | None]) -> str | None: present = [value for value in values if value in SEVERITY_RANK] return max(present, key=lambda value: SEVERITY_RANK[value]) if present else None def finding_dimensions(finding: dict[str, Any]) -> dict[str, Any]: value = finding.get("dimensions") if isinstance(value, dict): return value return ensure_dict(json_loads(finding.get("dimensions_json"), {})) def finding_signal_class(finding: dict[str, Any]) -> str: direct = str(finding.get("signal_class") or "").strip().lower() if direct in FINDING_SIGNAL_CLASSES: return direct dimensions = finding_dimensions(finding) source = str(finding.get("source") or "").strip().lower() explicit = str(dimensions.get("governance_signal_class") or "").strip().lower() if source == "clinic_health_check" and explicit in FINDING_SIGNAL_CLASSES: return explicit detector_code = str(finding.get("detector_code") or "").strip().lower() check_names = { str(value).strip() for value in ensure_list(dimensions.get("check_names")) if str(value).strip() } if source == "clinic_health_check" and ( check_names == {"slowlog_top_digest"} or (not check_names and detector_code == "clinic.slowlog_top_digest") ): return FINDING_SIGNAL_RANKING_OBSERVATION return FINDING_SIGNAL_ANOMALY def sql_statement_type(sql: Any) -> str | None: if not isinstance(sql, str) or not sql.strip(): return None text = re.sub( r"^(?:\s+|;+|/\*.*?\*/|--[^\r\n]*(?:\r?\n|$)|#[^\r\n]*(?:\r?\n|$))*", "", sql, flags=re.DOTALL, ) match = re.match(r"[A-Za-z]+", text) return match.group(0).lower() if match else None def catalog_governance_relevance(item: dict[str, Any]) -> dict[str, Any]: statement_type = sql_statement_type(item.get("normalized_sql")) review_eligible = statement_type not in NON_TUNABLE_SQL_STATEMENT_TYPES return { "review_eligible": review_eligible, "statement_type": statement_type, "reason": None if review_eligible else "non_tunable_statement", } def catalog_projection_review_eligible(item: dict[str, Any]) -> bool: posture = ensure_dict(item.get("current_posture")) relevance = ensure_dict(posture.get("governance_relevance")) projected = relevance.get("review_eligible") if isinstance(projected, bool): return projected return bool(catalog_governance_relevance(item)["review_eligible"]) def finding_review_eligible(finding: dict[str, Any]) -> bool: return catalog_governance_relevance(finding)["review_eligible"] def finding_best_impact_rank(finding: dict[str, Any]) -> int | None: ranks = ensure_dict(finding_dimensions(finding).get("top_digest_ranks")) values = [ int(value) for key, value in ranks.items() if key in IMPACT_RANK_DIMENSIONS and not isinstance(value, bool) and isinstance(value, (int, float)) and value > 0 ] return min(values, default=None) def finding_run_identity(finding: dict[str, Any]) -> str: return str( finding.get("finding_run_id") or finding.get("source_run_id") or finding.get("id") or "" ) def finding_metrics(finding: dict[str, Any]) -> dict[str, Any]: value = finding.get("metrics") if isinstance(value, dict): return value return ensure_dict(json_loads(finding.get("metrics_json"), {})) def finding_symptom_codes(finding: dict[str, Any]) -> set[str]: result: set[str] = set() for symptom in ensure_list(finding.get("symptoms")): if isinstance(symptom, dict) and symptom.get("code"): result.add(str(symptom["code"])) elif isinstance(symptom, str) and symptom: result.add(symptom) return result def numeric_finding_metric(finding: dict[str, Any], key: str) -> float | None: value = finding_metrics(finding).get(key) if isinstance(value, bool) or not isinstance(value, (int, float)): return None number = float(value) return number if isfinite(number) else None def normalize_metric_guardrails(value: Any) -> dict[str, dict[str, float]]: if value is None or value == "": return {} if not isinstance(value, dict) or len(value) > 32: raise ValueError("metric_guardrails must be an object with at most 32 metrics") result: dict[str, dict[str, float]] = {} for raw_key, raw_rule in value.items(): key = str(raw_key).strip() if not key or len(key) > 160: raise ValueError("metric_guardrails keys must be non-empty and at most 160 characters") rule = ( {"increase_percent": raw_rule} if isinstance(raw_rule, (int, float)) and not isinstance(raw_rule, bool) else raw_rule ) if not isinstance(rule, dict): raise ValueError( f"metric_guardrails.{key} must be a number or an object" ) unknown = set(rule) - {"increase_percent", "above"} if unknown or not rule: raise ValueError( f"metric_guardrails.{key} supports increase_percent and above" ) normalized: dict[str, float] = {} for field in ("increase_percent", "above"): if field not in rule: continue raw_number = rule[field] if ( isinstance(raw_number, bool) or not isinstance(raw_number, (int, float)) or not isfinite(float(raw_number)) ): raise ValueError(f"metric_guardrails.{key}.{field} must be a number") number = float(raw_number) if field == "increase_percent" and (number < 0 or number > 10000): raise ValueError( f"metric_guardrails.{key}.increase_percent must be between 0 and 10000" ) normalized[field] = number result[key] = normalized return result def governance_memory_fields(record: dict[str, Any]) -> dict[str, Any]: fields = ensure_dict(record.get("structured_fields")) conclusion_type = str(fields.get("conclusion_type") or "").strip() if conclusion_type not in GOVERNANCE_MEMORY_CONCLUSIONS: raise ValueError( "conclusion_type must describe an observation or no-action conclusion" ) reopen_policy = str(fields.get("reopen_policy") or "").strip() if reopen_policy not in GOVERNANCE_REOPEN_POLICIES: raise ValueError( "reopen_policy must be any_anomaly, meaningful_change, or manual_review" ) review_after = str(fields.get("review_after") or "").strip() or None if review_after and try_datetime(review_after) is None: raise ValueError("review_after must be an ISO-8601 timestamp") baseline_override = ensure_dict(fields.get("baseline")) baseline_severity = str(baseline_override.get("severity") or "").strip() or None if baseline_severity and baseline_severity not in SEVERITIES: raise ValueError("baseline.severity must be a valid severity") baseline_symptoms = sorted( { str(value).strip() for value in ensure_list(baseline_override.get("symptom_codes")) if str(value).strip() } ) if len(baseline_symptoms) > 100: raise ValueError("baseline.symptom_codes supports at most 100 values") return { "conclusion_type": conclusion_type, "confidence": str(fields.get("confidence") or "").strip() or None, "reopen_policy": reopen_policy, "review_after": review_after, "metric_guardrails": normalize_metric_guardrails( fields.get("metric_guardrails") ), "baseline_override": { "severity": baseline_severity, "symptom_codes": baseline_symptoms, }, } def build_catalog_governance_memory( findings: list[dict[str, Any]], record: dict[str, Any] ) -> dict[str, Any]: fields = governance_memory_fields(record) baseline_override = fields.pop("baseline_override") anomalies = sorted( ( finding for finding in findings if finding_signal_class(finding) == FINDING_SIGNAL_ANOMALY ), key=lambda finding: ( try_datetime(finding.get("event_at")) or datetime.min.replace(tzinfo=timezone.utc), str(finding.get("id") or ""), ), ) latest = anomalies[-1] if anomalies else None known_symptoms = sorted( { code for finding in anomalies for code in finding_symptom_codes(finding) } ) baseline_metrics: dict[str, float] = {} for key in fields["metric_guardrails"]: for finding in reversed(anomalies): value = numeric_finding_metric(finding, key) if value is not None: baseline_metrics[key] = value break return { "record_id": record["id"], **fields, "baseline": { "finding_id": latest.get("id") if latest else None, "severity": baseline_override.get("severity") or max_severity( [finding.get("severity") for finding in anomalies] ), "symptom_codes": ( baseline_override.get("symptom_codes") or known_symptoms ), "metrics": baseline_metrics, }, } def evaluate_catalog_governance_memory( latest_decision: dict[str, Any] | None, new_anomaly_findings: list[dict[str, Any]], ) -> dict[str, Any] | None: if not latest_decision: return None payload = ensure_dict(latest_decision.get("payload")) configured = isinstance(payload.get("governance_memory"), dict) memory = ensure_dict(payload.get("governance_memory")) reopen_policy = str(memory.get("reopen_policy") or "any_anomaly") if reopen_policy not in GOVERNANCE_REOPEN_POLICIES: reopen_policy = "any_anomaly" baseline = ensure_dict(memory.get("baseline")) metric_guardrails = ensure_dict(memory.get("metric_guardrails")) ordered = sorted( new_anomaly_findings, key=lambda finding: ( try_datetime(finding.get("event_at")) or datetime.min.replace(tzinfo=timezone.utc), str(finding.get("id") or ""), ), ) review_after = str(memory.get("review_after") or "").strip() or None review_due = bool( review_after and (review_at := try_datetime(review_after)) is not None and review_at <= datetime.now(timezone.utc) ) result = { "status": "active", "configured": configured, "action": payload.get("action"), "record_id": memory.get("record_id") or payload.get("record_id"), "conclusion_type": memory.get("conclusion_type"), "confidence": memory.get("confidence"), "reopen_policy": reopen_policy, "review_after": review_after, "decided_at": latest_decision.get("created_at"), "new_evidence_count": len(ordered), "covered_finding_count": 0, "trigger_finding_id": None, "trigger_reasons": [], "new_symptom_codes": [], "metric_changes": [], "baseline": baseline, } if review_due: result["status"] = "review_due" result["trigger_reasons"] = ["review_due"] return result if not ordered: return result if reopen_policy == "manual_review": result["covered_finding_count"] = len(ordered) return result if reopen_policy == "any_anomaly": result["status"] = "change_detected" result["trigger_finding_id"] = ordered[0].get("id") result["trigger_reasons"] = ["new_anomaly_after_decision"] return result baseline_severity = str(baseline.get("severity") or "") baseline_symptoms = { str(value) for value in ensure_list(baseline.get("symptom_codes")) } baseline_metrics = ensure_dict(baseline.get("metrics")) for index, finding in enumerate(ordered): reasons: list[str] = [] severity = str(finding.get("severity") or "") if SEVERITY_RANK.get(severity, -1) > SEVERITY_RANK.get( baseline_severity, -1 ): reasons.append("severity_increase") new_symptom_codes = sorted( finding_symptom_codes(finding) - baseline_symptoms ) if new_symptom_codes: reasons.append("new_symptom") metric_changes: list[dict[str, Any]] = [] for key, raw_rule in metric_guardrails.items(): rule = ensure_dict(raw_rule) current = numeric_finding_metric(finding, key) if current is None: continue baseline_value = baseline_metrics.get(key) triggered_by: list[str] = [] above = rule.get("above") if isinstance(above, (int, float)) and current > float(above): triggered_by.append("above") increase_percent = rule.get("increase_percent") if isinstance(increase_percent, (int, float)) and isinstance( baseline_value, (int, float) ): baseline_number = float(baseline_value) threshold = baseline_number * (1 + float(increase_percent) / 100) if (baseline_number == 0 and current > 0) or current > threshold: triggered_by.append("increase_percent") if triggered_by: metric_changes.append( { "metric": key, "baseline": baseline_value, "current": current, "rule": rule, "triggered_by": triggered_by, } ) if metric_changes: reasons.append("metric_guardrail_breached") if reasons: result["status"] = "change_detected" result["covered_finding_count"] = index result["trigger_finding_id"] = finding.get("id") result["trigger_reasons"] = reasons result["new_symptom_codes"] = new_symptom_codes result["metric_changes"] = metric_changes return result result["covered_finding_count"] = len(ordered) return result def cluster_sql_review_policy( conn: sqlite3.Connection, cluster_id: str ) -> dict[str, Any]: row = conn.execute( "SELECT * FROM cluster_sql_review_policies WHERE cluster_id = ?", (cluster_id,), ).fetchone() if not row: return { **DEFAULT_SQL_REVIEW_POLICY, "source": "system_default", "updated_by": None, "created_at": None, "updated_at": None, } return { "critical_finding_triggers_review": bool( row["critical_finding_triggers_review"] ), "finding_count_threshold": int(row["finding_count_threshold"]), "finding_window_days": int(row["finding_window_days"]), "source": "cluster", "updated_by": row["updated_by"], "created_at": row["created_at"], "updated_at": row["updated_at"], } def parse_sql_review_policy(value: Any) -> dict[str, Any]: if not isinstance(value, dict): raise ValueError("sql_review_policy must be an object") reject_unknown_fields( value, frozenset( { "critical_finding_triggers_review", "finding_count_threshold", "finding_window_days", } ), "sql_review_policy", ) critical_trigger = value.get("critical_finding_triggers_review") if not isinstance(critical_trigger, bool): raise ValueError( "sql_review_policy.critical_finding_triggers_review must be a boolean" ) threshold = value.get("finding_count_threshold") if isinstance(threshold, bool) or not isinstance(threshold, int): raise ValueError("sql_review_policy.finding_count_threshold must be an integer") if threshold < 1 or threshold > 1000: raise ValueError( "sql_review_policy.finding_count_threshold must be between 1 and 1000" ) window_days = value.get("finding_window_days") if isinstance(window_days, bool) or not isinstance(window_days, int): raise ValueError("sql_review_policy.finding_window_days must be an integer") if window_days < 1 or window_days > 90: raise ValueError( "sql_review_policy.finding_window_days must be between 1 and 90" ) return { "critical_finding_triggers_review": critical_trigger, "finding_count_threshold": threshold, "finding_window_days": window_days, } def catalog_review_admission( findings: list[dict[str, Any]], policy: dict[str, Any] ) -> dict[str, Any]: evaluated = sorted( ( (timestamp, finding) for finding in findings if (timestamp := try_datetime(finding.get("event_at"))) is not None ), key=lambda entry: entry[0], ) ordered = [ (timestamp, finding) for timestamp, finding in evaluated if finding_signal_class(finding) == FINDING_SIGNAL_ANOMALY ] critical_findings = [ (timestamp, finding) for timestamp, finding in ordered if finding.get("severity") == "critical" ] window = timedelta(days=int(policy["finding_window_days"])) threshold = int(policy["finding_count_threshold"]) left = 0 max_count = 0 frequency_trigger_at: datetime | None = None for right, (timestamp, _) in enumerate(ordered): while left <= right and timestamp - ordered[left][0] > window: left += 1 count = right - left + 1 max_count = max(max_count, count) if count >= threshold and frequency_trigger_at is None: frequency_trigger_at = timestamp critical_trigger_at = ( critical_findings[0][0] if policy["critical_finding_triggers_review"] and critical_findings else None ) matched_rules: list[str] = [] if critical_trigger_at: matched_rules.append("critical_finding") if frequency_trigger_at: matched_rules.append("finding_frequency") trigger_at = min( ( timestamp for timestamp in (critical_trigger_at, frequency_trigger_at) if timestamp is not None ), default=None, ) return { "required": bool(matched_rules), "matched_rules": matched_rules, "triggered_at": iso_datetime(trigger_at) if trigger_at else None, "evaluated_finding_count": len(evaluated), "eligible_finding_count": len(ordered), "ranking_observation_count": len(evaluated) - len(ordered), "critical_finding_count": len(critical_findings), "max_findings_in_window": max_count, "policy": dict(policy), } def catalog_review_priority( item: dict[str, Any], findings: list[dict[str, Any]], *, state: str, risk: str | None, unreviewed_peak_risk: str | None, reappeared: bool, review_admission: dict[str, Any], governance_memory: dict[str, Any] | None = None, latest_treatment_outcome: str | None = None, focus_anchor: datetime | None = None, ) -> dict[str, Any]: if review_admission.get("review_eligible") is False: findings = [] anomaly_findings = [ finding for finding in findings if finding_signal_class(finding) == FINDING_SIGNAL_ANOMALY ] ranking_observations = [ finding for finding in findings if finding_signal_class(finding) == FINDING_SIGNAL_RANKING_OBSERVATION ] anomaly_run_count = len( { identity for finding in anomaly_findings if (identity := finding_run_identity(finding)) } ) best_impact_rank = min( ( rank for finding in findings if (rank := finding_best_impact_rank(finding)) is not None ), default=None, ) reasons: list[str] = [] tier: str | None = None memory_status = str((governance_memory or {}).get("status") or "") memory_reasons = [ str(reason) for reason in ensure_list((governance_memory or {}).get("trigger_reasons")) if str(reason) ] # Admission answers whether a dossier is worth retaining as a review # candidate. The Workbench is narrower: it only interrupts a person for a # newly admitted SQL or a material change in the current weekly window. dated_anomalies = sorted( ( (event_at, finding) for finding in anomaly_findings if (event_at := try_datetime(finding.get("event_at"))) is not None ), key=lambda entry: (entry[0], str(entry[1].get("id") or "")), ) latest_evidence_at = dated_anomalies[-1][0] if dated_anomalies else None focus_window_end = max( focus_anchor or latest_evidence_at or datetime.now(timezone.utc), datetime.now(timezone.utc), ) focus_window_start = focus_window_end - timedelta(days=REVIEW_FOCUS_WINDOW_DAYS) previous_window_start = focus_window_start - timedelta( days=REVIEW_FOCUS_WINDOW_DAYS ) first_seen_at = try_datetime(item.get("first_seen_at")) new_this_week = bool( first_seen_at and first_seen_at >= focus_window_start and review_admission.get("required") ) current_window_findings = [ finding for event_at, finding in dated_anomalies if focus_window_start <= event_at <= focus_window_end ] previous_window_findings = [ finding for event_at, finding in dated_anomalies if previous_window_start <= event_at < focus_window_start ] current_window_risk = max_severity( [finding.get("severity") for finding in current_window_findings] ) previous_window_risk = max_severity( [finding.get("severity") for finding in previous_window_findings] ) current_peak_count = sum( 1 for finding in current_window_findings if finding.get("severity") == current_window_risk ) latest_evidence_day = ( dated_anomalies[-1][0].date() if dated_anomalies else None ) latest_day_findings = [ finding for event_at, finding in dated_anomalies if latest_evidence_day and event_at.date() == latest_evidence_day ] latest_current_risk = ( max_severity([finding.get("severity") for finding in latest_day_findings]) if latest_day_findings else None ) weekly_severity_worsened = bool( current_window_risk and previous_window_risk and SEVERITY_RANK[current_window_risk] > SEVERITY_RANK[previous_window_risk] and current_peak_count >= 2 and latest_current_risk == current_window_risk ) known_conclusion_changed = memory_status == "change_detected" or reappeared focus_kind = ( "worsened" if known_conclusion_changed or weekly_severity_worsened else "new" if new_this_week else None ) focus_reasons: list[str] = [] if known_conclusion_changed: focus_reasons.append( "known_conclusion_changed" if memory_status == "change_detected" else "reappeared_after_treatment" ) focus_reasons.extend(memory_reasons) elif weekly_severity_worsened: focus_reasons.append("weekly_severity_worsened") elif new_this_week: focus_reasons.append("new_this_week") if state == "needs_review": if str(item.get("priority") or "").lower() in {"urgent", "critical"}: tier = "p0" reasons.append("manual_escalation") if tier is None and latest_treatment_outcome: tier = "p1" reasons.append("treatment_requires_decision") if tier is None and focus_kind: tier = ( "p0" if risk == "critical" and (focus_kind == "worsened" or current_peak_count >= 2) else "p1" ) reasons.extend(focus_reasons) if tier is None: # Historical admission is retained as evidence, not promoted into a # human queue. A priority exists only when a person needs to make a # decision in the current weekly focus. reasons.append("not_in_weekly_focus") return { "tier": tier, "recommended": tier in {"p0", "p1"}, "reasons": list(dict.fromkeys(reasons)), "anomaly_finding_count": len(anomaly_findings), "anomaly_run_count": anomaly_run_count, "ranking_observation_count": len(ranking_observations), "best_impact_rank": best_impact_rank, "governance_memory_status": memory_status or None, "focus": { "kind": focus_kind, "window_days": REVIEW_FOCUS_WINDOW_DAYS, "window_start": iso_datetime(focus_window_start), "window_end": iso_datetime(focus_window_end), "reasons": list(dict.fromkeys(focus_reasons)), "previous_risk": previous_window_risk, "current_risk": current_window_risk, "latest_risk": latest_current_risk, "previous_finding_count": len(previous_window_findings), "current_finding_count": len(current_window_findings), "current_peak_count": current_peak_count, }, } def treatment_next_action(stage: str | None) -> str: return { "assessment": "continue_assessment", "planning": "prepare_plan", "alignment": "follow_up_customer", "execution": "record_execution", "observation": "evaluate_outcome", }.get(str(stage or ""), "open_treatment") def catalog_current_posture( conn: sqlite3.Connection, item: dict[str, Any], *, registration: dict[str, Any] | None = None, findings: list[dict[str, Any]] | None = None, treatments: list[dict[str, Any]] | None = None, catalog_events: list[dict[str, Any]] | None = None, review_policy: dict[str, Any] | None = None, review_focus_anchor: datetime | None = None, ) -> dict[str, Any]: registration = registration or catalog_item_registration(conn, item) governance_relevance = catalog_governance_relevance(item) review_eligible = bool(governance_relevance["review_eligible"]) if findings is None: finding_rows = conn.execute( """ SELECT id, source, detector_code, severity, created_at, reported_at, observed_at, source_run_id, finding_run_id, dimensions_json, metrics_json, COALESCE(reported_at, created_at) AS event_at FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL ORDER BY COALESCE(reported_at, created_at), created_at, id """, (item["id"],), ).fetchall() findings = [dict(row) for row in finding_rows] symptom_map = load_finding_symptoms( conn, [str(finding["id"]) for finding in findings] ) for finding in findings: finding["symptoms"] = symptom_map.get(str(finding["id"]), []) if treatments is None: treatment_rows = conn.execute( """ SELECT t.* FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? ORDER BY CASE t.state WHEN 'active' THEN 0 ELSE 1 END, t.updated_at DESC, t.id """, (item["id"],), ).fetchall() treatments = [row_to_treatment(row) for row in treatment_rows] active_treatments = [treatment for treatment in treatments if treatment["state"] == "active"] completed_treatments = [ treatment for treatment in treatments if treatment["state"] in {"completed", "cancelled"} ] latest_completed = max( completed_treatments, key=lambda treatment: treatment.get("completed_at") or treatment["updated_at"], default=None, ) if catalog_events is None: latest_decision = latest_catalog_event( conn, item["id"], ("catalog_decision_recorded",) ) latest_treatment_event = latest_catalog_event( conn, item["id"], ("treatment_completed", "treatment_cancelled") ) else: latest_decision = latest_preloaded_catalog_event( catalog_events, ("catalog_decision_recorded",) ) latest_treatment_event = latest_preloaded_catalog_event( catalog_events, ("treatment_completed", "treatment_cancelled") ) latest_treatment_outcome = ( latest_treatment_event["payload"].get("outcome") if latest_treatment_event else latest_completed.get("outcome") if latest_completed else None ) decision_at = latest_decision["created_at"] if latest_decision else None decision_evidence_at = ( latest_decision["payload"].get("reviewed_through_finding_at") if latest_decision else None ) or decision_at completed_at = ( latest_treatment_event["created_at"] if latest_treatment_event else ( latest_completed.get("completed_at") or latest_completed.get("updated_at") if latest_completed else None ) ) checkpoint_candidates = [ (parsed, value) for value in (decision_evidence_at, completed_at) if value and (parsed := try_datetime(value)) is not None ] checkpoint_time, checkpoint_at = max( checkpoint_candidates, key=lambda candidate: candidate[0], default=(None, None), ) unreviewed_findings = [ finding for finding in findings if not checkpoint_time or (finding_time := try_datetime(finding.get("event_at"))) is None or finding_time > checkpoint_time ] raw_unreviewed_anomaly_findings = [ finding for finding in unreviewed_findings if finding_signal_class(finding) == FINDING_SIGNAL_ANOMALY ] raw_anomaly_findings = [ finding for finding in findings if finding_signal_class(finding) == FINDING_SIGNAL_ANOMALY ] unreviewed_anomaly_findings = ( raw_unreviewed_anomaly_findings if review_eligible else [] ) anomaly_findings = raw_anomaly_findings if review_eligible else [] latest_unreviewed_anomaly = ( unreviewed_anomaly_findings[-1] if unreviewed_anomaly_findings else None ) latest_finding = anomaly_findings[-1] if anomaly_findings else None effective_unreviewed = list(unreviewed_findings) decision_time = try_datetime(decision_at) completed_time = try_datetime(completed_at) decision_is_checkpoint = bool( latest_decision and decision_time and (not completed_time or decision_time >= completed_time) ) governance_memory = evaluate_catalog_governance_memory( latest_decision if decision_is_checkpoint and review_eligible else None, unreviewed_anomaly_findings, ) memory_status = str((governance_memory or {}).get("status") or "") memory_requires_review = memory_status in {"change_detected", "review_due"} memory_covers_evidence = bool( governance_memory and memory_status == "active" ) reappeared = bool( review_eligible and not active_treatments and ( memory_status == "change_detected" or (item.get("reappeared_at") and not governance_memory) ) ) review_policy = review_policy or cluster_sql_review_policy( conn, item["cluster_id"] ) review_admission = catalog_review_admission( effective_unreviewed if review_eligible else [], review_policy ) review_admission.update( { "review_eligible": review_eligible, "evaluated_finding_count": len(effective_unreviewed), "excluded_non_tunable_finding_count": ( 0 if review_eligible else len(effective_unreviewed) ), } ) if memory_covers_evidence: covered_rules = list(review_admission["matched_rules"]) review_admission.update( { "required": False, "matched_rules": [], "triggered_at": None, "covered_matched_rules": covered_rules, "suppressed_by_governance_memory": True, "actionable_finding_count": 0, } ) elif memory_requires_review: memory_rule = ( "governance_memory_review_due" if memory_status == "review_due" else "governance_memory_change" ) review_admission.update( { "required": True, "matched_rules": list( dict.fromkeys([memory_rule, *review_admission["matched_rules"]]) ), "triggered_at": ( next( ( finding.get("event_at") for finding in unreviewed_anomaly_findings if finding.get("id") == governance_memory.get("trigger_finding_id") ), None, ) or review_admission.get("triggered_at") or governance_memory.get("review_after") ), "suppressed_by_governance_memory": False, "actionable_finding_count": len(unreviewed_anomaly_findings), } ) elif reappeared: review_admission.update( { "required": True, "matched_rules": list( dict.fromkeys( ["governance_reappearance", *review_admission["matched_rules"]] ) ), "triggered_at": ( item.get("reappeared_at") or review_admission.get("triggered_at") ), "suppressed_by_governance_memory": False, "actionable_finding_count": len(unreviewed_anomaly_findings), } ) else: review_admission["suppressed_by_governance_memory"] = False review_admission["actionable_finding_count"] = len( unreviewed_anomaly_findings ) activity_candidates: list[tuple[str, int, str]] = [] if latest_decision: activity_candidates.append( (latest_decision["created_at"], latest_decision["sequence"], "decision") ) if latest_treatment_event: activity_candidates.append( ( latest_treatment_event["created_at"], latest_treatment_event["sequence"], "treatment", ) ) latest_activity = max(activity_candidates, default=(None, 0, None))[2] automatic_admission_state = False if item.get("archived_at"): state = "archived" elif active_treatments: state = "in_treatment" elif not review_eligible: state = ( "no_intervention" if latest_activity == "decision" and latest_decision["payload"].get("action") == "no_action" else "registered" ) elif review_admission["required"]: state = "needs_review" automatic_admission_state = True elif latest_activity == "decision": state = ( "watching" if latest_decision["payload"].get("action") == "watch" else "no_intervention" ) elif latest_activity == "treatment": if latest_treatment_outcome in {"fixed", "improved"}: state = "watching" elif latest_treatment_outcome in {"not_optimizable", "accepted_risk"}: state = "no_intervention" else: state = "needs_review" elif registration.get("initial_action") == "watch": state = "watching" else: state = "registered" historical_risk = max_severity( [finding.get("severity") for finding in anomaly_findings] ) unreviewed_peak_risk = max_severity( [finding.get("severity") for finding in unreviewed_anomaly_findings] ) last_known_risk = latest_finding.get("severity") if latest_finding else None memory_trigger_finding = next( ( finding for finding in unreviewed_anomaly_findings if finding.get("id") == (governance_memory or {}).get("trigger_finding_id") ), None, ) current_risk_finding = ( memory_trigger_finding if memory_status == "change_detected" else None if memory_status == "review_due" else latest_unreviewed_anomaly ) if state == "in_treatment": risk = max_severity( [treatment.get("severity") for treatment in active_treatments] + ( [unreviewed_anomaly_findings[-1].get("severity")] if unreviewed_anomaly_findings else [] ) ) or historical_risk elif state == "needs_review": risk = current_risk_finding.get("severity") if current_risk_finding else None if not risk and latest_treatment_outcome: risk = last_known_risk else: risk = None primary_treatment = active_treatments[0] if active_treatments else None observation_due = bool( primary_treatment and primary_treatment.get("stage") == "observation" and primary_treatment.get("observation_due_at") and primary_treatment["observation_due_at"] <= now_iso() ) recurring = sum( 1 for finding in anomaly_findings if finding["event_at"] >= since_iso(7) ) >= 2 reasons: list[str] = [] if not review_eligible: reasons.append("non_tunable_statement") if reappeared: reasons.append("reappeared") if memory_status == "change_detected": reasons.extend( str(reason) for reason in ensure_list(governance_memory.get("trigger_reasons")) ) elif memory_status == "review_due": reasons.append("review_due") elif memory_covers_evidence and governance_memory.get("covered_finding_count"): reasons.append("covered_by_governance_memory") if risk == "critical" and state == "needs_review": reasons.append("critical_without_treatment") elif ( unreviewed_peak_risk == "critical" and state == "needs_review" ): reasons.append("critical_peak_unreviewed") elif risk == "high" and state == "needs_review": reasons.append("high_risk") if ( review_admission["required"] and review_admission["eligible_finding_count"] and not active_treatments ): reasons.append("new_findings") if "critical_finding" in review_admission["matched_rules"]: reasons.append("review_threshold_critical") if "finding_frequency" in review_admission["matched_rules"]: reasons.append("review_threshold_frequency") if ( review_eligible and unreviewed_anomaly_findings and not review_admission["required"] and not memory_covers_evidence ): reasons.append("below_review_threshold") if ( review_eligible and effective_unreviewed and not unreviewed_anomaly_findings ): reasons.append("ranking_observation_only") if recurring and state == "needs_review": reasons.append("recurring") if not item.get("owner") and state in { "needs_review", "in_treatment", "watching", }: reasons.append("unowned") if len(active_treatments) > 1: reasons.append("multiple_active_treatments") if observation_due: reasons.append("observation_due") review_priority = catalog_review_priority( item, effective_unreviewed, state=state, risk=risk, unreviewed_peak_risk=unreviewed_peak_risk, reappeared=reappeared, review_admission=review_admission, governance_memory=governance_memory, latest_treatment_outcome=latest_treatment_outcome, focus_anchor=review_focus_anchor, ) if automatic_admission_state and not review_priority["recommended"]: # Reaching the cluster's historical admission threshold is useful # evidence, but it is not itself a standing task. Only a newly admitted # SQL, a material week-over-week regression, or an invalidated prior # conclusion should interrupt a person. state = "registered" risk = None reasons = [ reason for reason in reasons if reason in { "below_review_threshold", "covered_by_governance_memory", "ranking_observation_only", } ] reasons.append("no_new_or_worsening_signal") if state == "needs_review": attention = "urgent" if review_priority["tier"] == "p0" else "attention" elif observation_due: attention = "urgent" elif state == "in_treatment" and primary_treatment.get("stage") == "alignment": attention = "attention" elif state in {"in_treatment", "watching"}: attention = "normal" else: attention = "none" next_action = { "needs_review": "review", "watching": "monitor", "no_intervention": "none", "registered": "none", "archived": "none", }.get(state, treatment_next_action(primary_treatment.get("stage") if primary_treatment else None)) return { "state": state, "risk": risk, "last_known_risk": last_known_risk, "unreviewed_peak_risk": unreviewed_peak_risk, "historical_peak_risk": historical_risk, "attention": attention, "reasons": reasons, "next_action": next_action, "unreviewed_finding_count": len(effective_unreviewed), "unreviewed_anomaly_count": review_admission["actionable_finding_count"], "new_anomaly_count": len(unreviewed_anomaly_findings), "excluded_non_tunable_finding_count": ( 0 if review_eligible else len(effective_unreviewed) ), "current_signal_finding_id": ( current_risk_finding.get("id") if current_risk_finding else latest_finding.get("id") if latest_finding else None ), "ranking_observation_count": review_admission[ "ranking_observation_count" ], "review_admission": review_admission, "review_priority": review_priority, "governance_relevance": governance_relevance, "governance_memory": governance_memory, "active_treatment_count": len(active_treatments), "active_treatment": ( { "id": primary_treatment["id"], "treatment_no": primary_treatment["treatment_no"], "title": primary_treatment["title"], "stage": primary_treatment["stage"], "owner": primary_treatment.get("owner"), "updated_at": primary_treatment["updated_at"], } if primary_treatment else None ), "latest_decision": ( { "action": latest_decision["payload"].get("action"), "record_id": latest_decision["payload"].get("record_id"), "decided_by": latest_decision.get("actor"), "decided_at": latest_decision["created_at"], "governance_memory": governance_memory, } if latest_decision else None ), "latest_treatment_outcome": latest_treatment_outcome, } def next_treatment_no(conn: sqlite3.Connection) -> str: value = conn.execute( "SELECT COALESCE(MAX(CAST(SUBSTR(treatment_no, 5) AS UNSIGNED)), 0) FROM treatments" ).fetchone()[0] # TiDB returns CAST(... AS UNSIGNED) aggregates as Decimal, while SQLite # returns int. Normalize before applying the integer display format. return f"TRT-{int(value) + 1:04d}" def higher_severity(current: str | None, incoming: str | None) -> str | None: if not current: return incoming if not incoming: return current return incoming if SEVERITY_RANK.get(incoming, 0) > SEVERITY_RANK.get(current, 0) else current def code_list( value: Any, field: str, *, maximum: int = 64, max_length: int = 128 ) -> list[str]: if value is None: return [] if not isinstance(value, list): raise ValueError(f"{field} must be an array") values = value if len(values) > maximum or any( not isinstance(item, str) or not item.strip() or len(item.strip()) > max_length for item in values ): raise ValueError( f"{field} must contain at most {maximum} non-empty strings of {max_length} characters" ) return list(dict.fromkeys(item.strip() for item in values)) def evidence_list(value: Any, field: str) -> list[dict[str, Any]]: if value is None: return [] if not isinstance(value, list) or len(value) > 100: raise ValueError(f"{field} must be an array with at most 100 objects") result: list[dict[str, Any]] = [] for index, entry in enumerate(value): if not isinstance(entry, dict): raise ValueError(f"{field}[{index}] must be an object") evidence_type = entry.get("type") if not isinstance(evidence_type, str) or not evidence_type.strip(): raise ValueError(f"{field}[{index}].type is required") result.append(entry) return result def parse_assessment(value: Any, field: str) -> dict[str, Any]: if value is None: return {} if not isinstance(value, dict): raise ValueError(f"{field} must be an object") reject_unknown_fields(value, FINDING_ASSESSMENT_INPUT_FIELDS, field) method = optional_string(value.get("method"), f"{field}.method", 32) if method and method not in ASSESSMENT_METHODS: raise ValueError( f"{field}.method must be one of {', '.join(sorted(ASSESSMENT_METHODS))}" ) result: dict[str, Any] = {} if method: result["method"] = method for key, maximum in { "summary": 2000, "rule_code": 256, "rule_version": 128, "policy_id": 256, "policy_version": 128, "policy_url": 2000, }.items(): parsed = optional_string(value.get(key), f"{field}.{key}", maximum) if parsed: result[key] = parsed parameters = value.get("parameters") if parameters is not None: if not isinstance(parameters, dict): raise ValueError(f"{field}.parameters must be an object") result["parameters"] = parameters return result def parse_finding_symptoms( value: Any, metrics: dict[str, Any] ) -> list[dict[str, Any]]: if not isinstance(value, list) or not value: raise ValueError("symptoms must be a non-empty array") if len(value) > 32: raise ValueError("symptoms must contain at most 32 entries") symptoms: list[dict[str, Any]] = [] seen_codes: set[str] = set() for index, entry in enumerate(value): if not isinstance(entry, dict): raise ValueError(f"symptoms[{index}] must be an object") reject_unknown_fields(entry, FINDING_SYMPTOM_INPUT_FIELDS, f"symptoms[{index}]") code = require_string(entry, "code", max_length=128) if code in seen_codes: raise ValueError(f"symptoms contains duplicate code {code}") seen_codes.add(code) severity = require_string(entry, "severity", max_length=16).lower() if severity not in SEVERITIES: raise ValueError( f"symptoms[{index}].severity must be one of {', '.join(sorted(SEVERITIES))}" ) confidence_value = entry.get("confidence") confidence = None if confidence_value is not None: if isinstance(confidence_value, bool) or not isinstance(confidence_value, (int, float)): raise ValueError(f"symptoms[{index}].confidence must be a number from 0 to 1") confidence = float(confidence_value) if not 0 <= confidence <= 1: raise ValueError(f"symptoms[{index}].confidence must be a number from 0 to 1") signal_codes = code_list(entry.get("signal_codes"), f"symptoms[{index}].signal_codes") metric_keys = code_list(entry.get("metric_keys"), f"symptoms[{index}].metric_keys") unknown_metric_keys = [key for key in metric_keys if key not in metrics] if unknown_metric_keys: raise ValueError( f"symptoms[{index}].metric_keys reference unknown metrics: {', '.join(unknown_metric_keys)}" ) symptoms.append( { "code": code, "severity": severity, "confidence": confidence, "signal_codes": signal_codes, "metric_keys": metric_keys, "evidence_refs": evidence_list( entry.get("evidence_refs"), f"symptoms[{index}].evidence_refs" ), "assessment": parse_assessment( entry.get("assessment"), f"symptoms[{index}].assessment" ), } ) return symptoms def validate_registered_symptoms( conn: sqlite3.Connection, symptoms: list[dict[str, Any]], source_type: str ) -> None: codes = [str(symptom["code"]) for symptom in symptoms] placeholders = ",".join("?" for _ in codes) rows = conn.execute( f"SELECT code, status FROM symptom_definitions WHERE code IN ({placeholders})", codes, ).fetchall() registered = {row["code"]: row["status"] for row in rows} unknown = [code for code in codes if code not in registered] if unknown: raise ValueError(f"symptoms contain unregistered codes: {', '.join(unknown)}") inactive = [code for code in codes if registered.get(code) != "active"] if inactive: raise ValueError(f"symptoms contain inactive codes: {', '.join(inactive)}") for index, symptom in enumerate(symptoms): if symptom["code"] != "unclassified_sql_anomaly": continue assessment = ensure_dict(symptom.get("assessment")) if source_type != "manual" or not assessment.get("summary"): raise ValueError( f"symptoms[{index}] unclassified_sql_anomaly is only allowed for manual intake " "with assessment.summary" ) def finding_severity(symptoms: list[dict[str, Any]]) -> str: return max( (str(symptom["severity"]) for symptom in symptoms), key=lambda value: SEVERITY_RANK[value], ) def recompute_first_observation( conn: sqlite3.Connection, org_id: str, cluster_id: str, sql_digest: str, ) -> None: conn.execute( """ UPDATE findings SET is_first_observation = 0 WHERE org_id = ? AND cluster_id = ? AND sql_digest = ? """, (org_id, cluster_id, sql_digest), ) first = conn.execute( """ SELECT id FROM findings WHERE org_id = ? AND cluster_id = ? AND sql_digest = ? AND deleted_at IS NULL ORDER BY COALESCE(observed_at, time_window_end, time_window_start, created_at), COALESCE(ingested_at, created_at), id LIMIT 1 """, (org_id, cluster_id, sql_digest), ).fetchone() if first: conn.execute( "UPDATE findings SET is_first_observation = 1 WHERE id = ?", (first["id"],), ) def list_symptom_definitions( params: dict[str, list[str]], locale: str = "en" ) -> dict[str, Any]: requested_status = params.get("status", ["active"])[0].strip().lower() where_sql = "" values: list[Any] = [] if requested_status != "all": if requested_status not in SYMPTOM_DEFINITION_STATUSES: requested_status = "active" where_sql = " WHERE status = ?" values.append(requested_status) with get_conn() as conn: rows = conn.execute( "SELECT * FROM symptom_definitions" + where_sql + " ORDER BY category, name, code", values, ).fetchall() return { "items": [row_to_symptom_definition(row, locale) for row in rows], "total": len(rows), } def create_finding_run( payload: dict[str, Any], *, received_at: str | None = None, ) -> tuple[int, dict[str, Any]]: try: reject_unknown_fields(payload, FINDING_RUN_INPUT_FIELDS, "finding run") source = require_string(payload, "source", max_length=128) source_run_id = require_string(payload, "source_run_id", max_length=512) org_id = require_string(payload, "org_id", max_length=128) cluster_id = require_string(payload, "cluster_id", max_length=128) source_type = require_string(payload, "source_type", max_length=32).lower() if source_type not in SOURCE_TYPES: raise ValueError(f"source_type must be one of {', '.join(sorted(SOURCE_TYPES))}") status = require_string(payload, "status", max_length=16).lower() if status not in FINDING_RUN_STATUSES: raise ValueError(f"status must be one of {', '.join(sorted(FINDING_RUN_STATUSES))}") timestamp = intake_timestamp(received_at) window_start = parse_iso( payload.get("time_window_start"), "time_window_start", required=True, ) window_end = parse_iso( payload.get("time_window_end"), "time_window_end", required=True, ) if window_start and window_end and window_end < window_start: raise ValueError("time_window_end must not be before time_window_start") project_id = optional_string(payload.get("project_id"), "project_id", 128) detector_version = optional_string( payload.get("detector_version"), "detector_version", 128 ) started_at = parse_iso(payload.get("started_at") or window_start, "started_at") completed_at = parse_iso(payload.get("completed_at") or window_end, "completed_at") expected_detector_count = positive_int( payload.get("expected_detector_count"), 0, 10_000 ) completed_detector_count = positive_int( payload.get("completed_detector_count"), expected_detector_count, 10_000 ) metadata = payload.get("metadata") or {} if not isinstance(metadata, dict): raise ValueError("metadata must be an object") except ValueError as exc: return 400, {"error": "invalid_finding_run", "message": str(exc)} with get_conn() as conn: existing = conn.execute( """ SELECT * FROM finding_runs WHERE org_id = ? AND cluster_id = ? AND source = ? AND source_run_id = ? """, (org_id, cluster_id, source, source_run_id), ).fetchone() if existing: return 200, {"created": False, "run": row_to_finding_run(existing)} run_id = new_id("run") columns = ( "id, source, source_type, source_run_id, org_id, project_id, cluster_id, " "time_window_start, time_window_end, status, detector_version, " "expected_detector_count, completed_detector_count, metadata_json, " "started_at, completed_at, ingested_at" ) values: tuple[Any, ...] = ( run_id, source, source_type, source_run_id, org_id, project_id, cluster_id, window_start, window_end, status, detector_version, expected_detector_count, completed_detector_count, json_dumps(metadata), started_at, completed_at, timestamp, ) if connection_dialect(conn) == "mysql": columns += ", idempotency_key" values += ( finding_run_idempotency_key( org_id, cluster_id, source, source_run_id ), ) placeholders = ", ".join("?" for _ in values) conn.execute( f"INSERT INTO finding_runs ({columns}) VALUES ({placeholders})", values, ) run = conn.execute("SELECT * FROM finding_runs WHERE id = ?", (run_id,)).fetchone() return 201, {"created": True, "run": row_to_finding_run(run)} def create_finding( payload: dict[str, Any], *, received_at: str | None = None, compact_response: bool = False, ) -> tuple[int, dict[str, Any]]: try: reject_unknown_fields(payload, FINDING_INPUT_FIELDS, "finding") source = require_string(payload, "source", max_length=128) source_event_id = require_string(payload, "source_event_id", max_length=512) org_id = require_string(payload, "org_id", max_length=128) cluster_id = require_string(payload, "cluster_id", max_length=128) sql_digest = require_string(payload, "sql_digest", max_length=256) timestamp = intake_timestamp(received_at) source_type = require_string(payload, "source_type", max_length=32).lower() if source_type not in SOURCE_TYPES: raise ValueError(f"source_type must be one of {', '.join(sorted(SOURCE_TYPES))}") detector_code = require_string(payload, "detector_code", max_length=128) observed_at = parse_iso(payload.get("observed_at"), "observed_at", required=True) reported_at = parse_iso( payload.get("reported_at") or timestamp, "reported_at", required=True, ) time_window_start = parse_iso(payload.get("time_window_start"), "time_window_start") time_window_end = parse_iso(payload.get("time_window_end"), "time_window_end") if bool(time_window_start) != bool(time_window_end): raise ValueError("time_window_start and time_window_end must be provided together") if time_window_start and time_window_end and time_window_end < time_window_start: raise ValueError("time_window_end must not be before time_window_start") project_id = optional_string(payload.get("project_id"), "project_id", 128) created_by = optional_string(payload.get("created_by"), "created_by", 128) or current_actor() normalized_sql = optional_string( payload.get("normalized_sql"), "normalized_sql", 200_000, ) or "" source_batch_id = optional_string( payload.get("source_batch_id"), "source_batch_id", 512 ) source_run_id = optional_string(payload.get("source_run_id"), "source_run_id", 512) detector_version = optional_string( payload.get("detector_version"), "detector_version", 128 ) metric_schema_version = optional_string( payload.get("metric_schema_version"), "metric_schema_version", 64 ) metrics_value = payload.get("metrics", {}) dimensions_value = payload.get("dimensions", {}) if not isinstance(metrics_value, dict): raise ValueError("metrics must be an object") if not isinstance(dimensions_value, dict): raise ValueError("dimensions must be an object") metrics = metrics_value if metrics and not metric_schema_version: raise ValueError("metric_schema_version is required when metrics is not empty") dimensions = dimensions_value evidence_refs = evidence_list(payload.get("evidence_refs"), "evidence_refs") symptoms = parse_finding_symptoms(payload.get("symptoms"), metrics) severity = finding_severity(symptoms) raw_payload = payload.get("raw_payload", {}) if not isinstance(raw_payload, dict): raise ValueError("raw_payload must be an object") except ValueError as exc: return 400, {"error": "invalid_finding", "message": str(exc)} with get_conn() as validation_conn: try: validate_registered_symptoms(validation_conn, symptoms, source_type) except ValueError as exc: return 400, {"error": "invalid_finding", "message": str(exc)} with get_conn() as conn: cache_reported_cluster_metadata_with_conn( conn, org_id=org_id, project_id=project_id, cluster_id=cluster_id, dimensions=dimensions, ) existing = conn.execute( "SELECT * FROM findings WHERE source = ? AND source_event_id = ?", (source, source_event_id), ).fetchone() if existing: if compact_response: return 200, { "created": False, "finding": { "id": existing["id"], "catalog_item_id": existing["catalog_item_id"], "is_new_digest": bool(existing["is_new_digest"]), }, } symptom_map = load_finding_symptoms(conn, [existing["id"]]) finding = row_to_finding(existing, symptom_map[existing["id"]]) item = get_catalog_item(conn, finding["catalog_item_id"]) return 200, { "created": False, "finding": finding, "catalog_item": enrich_catalog_item(conn, item) if item else None, } item_row = conn.execute( """ SELECT * FROM catalog_items WHERE org_id = ? AND cluster_id = ? AND sql_digest = ? """, (org_id, cluster_id, sql_digest), ).fetchone() is_new_digest = item_row is None had_previous_findings = bool( item_row and conn.execute( """ SELECT 1 FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL LIMIT 1 """, (item_row["id"],), ).fetchone() ) run_row = None if source_run_id: run_row = conn.execute( """ SELECT * FROM finding_runs WHERE org_id = ? AND cluster_id = ? AND source = ? AND source_run_id = ? """, (org_id, cluster_id, source, source_run_id), ).fetchone() if item_row is None: catalog_item_id = new_id("cat") conn.execute( """ INSERT INTO catalog_items (id, org_id, project_id, cluster_id, sql_digest, normalized_sql, owner, priority, labels_json, first_seen_at, last_seen_at, latest_finding_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( catalog_item_id, org_id, project_id, cluster_id, sql_digest, normalized_sql, None, "normal", json_dumps([]), time_window_start or observed_at, time_window_end or observed_at, reported_at, timestamp, timestamp, ), ) add_timeline( conn, "catalog_item_created", "catalog_item", catalog_item_id, "Catalog item created from incoming finding", { "registration_origin": "finding", "registration_reason": "first_finding", "source": source, "source_event_id": source_event_id, }, created_by, timestamp, ) else: item = row_to_catalog_item(item_row) catalog_item_id = item["id"] next_sql = item.get("normalized_sql") or normalized_sql next_first_seen = min( value for value in [item.get("first_seen_at"), time_window_start or observed_at] if value ) next_last_seen = max( value for value in [item.get("last_seen_at"), time_window_end or observed_at] if value ) next_latest_finding = max( value for value in [item.get("latest_finding_at"), reported_at] if value ) conn.execute( """ UPDATE catalog_items SET normalized_sql = ?, first_seen_at = ?, last_seen_at = ?, latest_finding_at = ?, archived_at = NULL, orphaned_at = NULL, updated_at = ? WHERE id = ? """, ( next_sql, next_first_seen, next_last_seen, next_latest_finding, timestamp, catalog_item_id, ), ) if item.get("archived_at"): add_timeline( conn, "catalog_item_reactivated", "catalog_item", catalog_item_id, "Catalog item reactivated by a new Finding", {"finding_source_event_id": source_event_id}, created_by, timestamp, ) finding_id = new_id("fnd") conn.execute( """ INSERT INTO findings (id, source, source_type, source_event_id, source_batch_id, source_run_id, finding_run_id, org_id, project_id, cluster_id, sql_digest, normalized_sql, time_window_start, time_window_end, reported_at, observed_at, ingested_at, severity, detector_code, detector_version, metric_schema_version, metrics_json, dimensions_json, evidence_refs_json, raw_payload_json, catalog_item_id, is_new_digest, is_first_observation, created_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( finding_id, source, source_type, source_event_id, source_batch_id, source_run_id, run_row["id"] if run_row else None, org_id, project_id, cluster_id, sql_digest, normalized_sql, time_window_start, time_window_end, reported_at, observed_at, timestamp, severity, detector_code, detector_version, metric_schema_version, json_dumps(metrics), json_dumps(dimensions), json_dumps(evidence_refs), json_dumps(raw_payload), catalog_item_id, 1 if is_new_digest else 0, 0, created_by, timestamp, ), ) for symptom in symptoms: symptom_id = new_id("sym") conn.execute( """ INSERT INTO finding_symptoms (id, finding_id, symptom_code, severity, confidence, signal_codes_json, metric_keys_json, evidence_refs_json, assessment_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( symptom_id, finding_id, symptom["code"], symptom["severity"], symptom["confidence"], json_dumps(symptom["signal_codes"]), json_dumps(symptom["metric_keys"]), json_dumps(symptom["evidence_refs"]), json_dumps(symptom["assessment"]), ), ) recompute_first_observation(conn, org_id, cluster_id, sql_digest) add_relation( conn, "finding", finding_id, "discovered", "catalog_item", catalog_item_id, timestamp, ) signal_class = finding_signal_class( { "source": source, "detector_code": detector_code, "dimensions": dimensions, } ) current_catalog_item = get_catalog_item(conn, catalog_item_id) review_eligible = bool( current_catalog_item and catalog_governance_relevance(current_catalog_item)["review_eligible"] ) add_timeline( conn, "finding_ingested", "catalog_item", catalog_item_id, f"Finding ingested from {source}", { "finding_id": finding_id, "source": source, "source_event_id": source_event_id, "severity": severity, "signal_class": signal_class, "review_eligible": review_eligible, "symptoms": [symptom["code"] for symptom in symptoms], "detector_code": detector_code, "observed_at": observed_at, "is_new_digest": is_new_digest, }, created_by, timestamp, ) add_timeline( conn, "finding_ingested", "finding", finding_id, f"Finding ingested from {source}", { "catalog_item_id": catalog_item_id, "is_new_digest": is_new_digest, "signal_class": signal_class, }, created_by, timestamp, ) active_treatments = conn.execute( """ SELECT t.* FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? WHERE t.state = 'active' """, (catalog_item_id,), ).fetchall() prior_decision = latest_catalog_event( conn, catalog_item_id, ("catalog_decision_recorded",) ) prior_terminal_treatment = bool( conn.execute( """ SELECT 1 FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? WHERE t.state IN ('completed', 'cancelled') LIMIT 1 """, (catalog_item_id,), ).fetchone() ) prior_governance = bool( not is_new_digest and had_previous_findings and not active_treatments and (prior_decision or prior_terminal_treatment) ) reappearance_reasons: list[str] = [] should_reappear = False if ( prior_governance and signal_class == FINDING_SIGNAL_ANOMALY and review_eligible ): current_posture = ( catalog_current_posture(conn, current_catalog_item) if current_catalog_item else None ) memory = ensure_dict( (current_posture or {}).get("governance_memory") ) memory_status = str(memory.get("status") or "") should_reappear = memory_status == "change_detected" or ( not memory and prior_terminal_treatment ) reappearance_reasons = [ str(reason) for reason in ensure_list(memory.get("trigger_reasons")) if str(reason) ] if should_reappear and not reappearance_reasons: reappearance_reasons = ["new_anomaly_after_treatment"] if should_reappear: conn.execute( "UPDATE catalog_items SET reappeared_at = ?, updated_at = ? WHERE id = ?", (timestamp, timestamp, catalog_item_id), ) add_timeline( conn, "catalog_item_reappeared", "catalog_item", catalog_item_id, "A meaningful change arrived after prior governance", { "finding_id": finding_id, "trigger_reasons": reappearance_reasons, }, created_by, timestamp, ) if len(active_treatments) == 1: treatment_id = active_treatments[0]["id"] add_relation( conn, "finding", finding_id, "evidence_of", "treatment", treatment_id, timestamp, ) add_timeline( conn, "finding_linked", "treatment", treatment_id, "New Finding linked to active Treatment", {"finding_id": finding_id, "catalog_item_id": catalog_item_id}, created_by, timestamp, ) elif len(active_treatments) > 1: add_timeline( conn, "finding_relation_review_needed", "catalog_item", catalog_item_id, "Finding needs Treatment relation review because multiple Treatments are active", {"finding_id": finding_id, "treatment_ids": [row["id"] for row in active_treatments]}, created_by, timestamp, ) if compact_response: return 201, { "created": True, "finding": { "id": finding_id, "catalog_item_id": catalog_item_id, "is_new_digest": is_new_digest, }, } symptom_map = load_finding_symptoms(conn, [finding_id]) finding = row_to_finding( conn.execute("SELECT * FROM findings WHERE id = ?", (finding_id,)).fetchone(), symptom_map[finding_id], ) item = get_catalog_item(conn, catalog_item_id) return 201, { "created": True, "finding": finding, "catalog_item": enrich_catalog_item(conn, item) if item else None, } def create_finding_batch( payload: dict[str, Any], *, received_at: str | None = None, ) -> tuple[int, dict[str, Any]]: try: reject_unknown_fields(payload, FINDING_BATCH_INPUT_FIELDS, "finding batch") source = require_string(payload, "source", max_length=128) source_type = require_string(payload, "source_type", max_length=32).lower() if source_type not in SOURCE_TYPES: raise ValueError(f"source_type must be one of {', '.join(sorted(SOURCE_TYPES))}") source_batch_id = require_string(payload, "source_batch_id", max_length=512) defaults = payload.get("defaults") or {} if not isinstance(defaults, dict): raise ValueError("defaults must be an object") entries = payload.get("findings") if not isinstance(entries, list) or not entries: raise ValueError("findings must be a non-empty array") if len(entries) > 500: raise ValueError("findings must contain at most 500 entries") if any(not isinstance(entry, dict) for entry in entries): raise ValueError("every findings entry must be an object") created_by = optional_string(payload.get("created_by"), "created_by", 128) timestamp = intake_timestamp(received_at) except ValueError as exc: return 400, {"error": "invalid_finding_batch", "message": str(exc)} results: list[dict[str, Any]] = [] created_count = 0 duplicate_count = 0 rejected_count = 0 for index, entry in enumerate(entries): finding_payload = {**defaults, **entry} finding_payload["source"] = source finding_payload["source_type"] = source_type finding_payload["source_batch_id"] = source_batch_id if created_by and not finding_payload.get("created_by"): finding_payload["created_by"] = created_by status, body = create_finding(finding_payload, received_at=timestamp) source_event_id = finding_payload.get("source_event_id") if status == 201: created_count += 1 results.append( { "index": index, "source_event_id": source_event_id, "status": "created", "finding_id": body["finding"]["id"], "catalog_item_id": body["catalog_item"]["id"], } ) elif status == 200 and body.get("finding"): duplicate_count += 1 results.append( { "index": index, "source_event_id": source_event_id, "status": "duplicate", "finding_id": body["finding"]["id"], "catalog_item_id": body["catalog_item"]["id"], } ) else: rejected_count += 1 results.append( { "index": index, "source_event_id": source_event_id, "status": "rejected", "error": body.get("error") or "invalid_finding", "message": body.get("message") or "Finding was rejected", } ) response_status = 207 if rejected_count else 201 if created_count else 200 return response_status, { "source": source, "source_type": source_type, "source_batch_id": source_batch_id, "summary": { "submitted": len(entries), "created": created_count, "duplicate": duplicate_count, "rejected": rejected_count, }, "items": results, } def param_values(params: dict[str, list[str]], key: str) -> list[str]: values: list[str] = [] for raw_value in params.get(key, []): values.extend(part.strip() for part in raw_value.split(",") if part.strip()) return list(dict.fromkeys(values)) def merge_query_params( params: dict[str, list[str]], **overrides: str | list[str] ) -> dict[str, list[str]]: merged = {key: list(values) for key, values in params.items()} for key, value in overrides.items(): merged[key] = list(value) if isinstance(value, list) else [value] return merged def finding_filter_sql(params: dict[str, list[str]]) -> tuple[str, list[Any]]: where: list[str] = [] values: list[Any] = [] deletion_state = params.get("deletion_state", ["active"])[0].strip().lower() if deletion_state == "deleted": where.append("f.deleted_at IS NOT NULL") elif deletion_state != "all": where.append("f.deleted_at IS NULL") filters = { "org_id": "f.org_id", "project_id": "f.project_id", "cluster_id": "f.cluster_id", "source": "f.source", "source_type": "f.source_type", "severity": "f.severity", "detector_code": "f.detector_code", } for key, column in filters.items(): selected = param_values(params, key) if selected: placeholders = ",".join("?" for _ in selected) where.append(f"{column} IN ({placeholders})") values.extend(selected) for key, column in { "sql_digest": "f.sql_digest", "source_event_id": "f.source_event_id", "source_batch_id": "f.source_batch_id", "source_run_id": "f.source_run_id", }.items(): value = params.get(key, [""])[0].strip() if value: where.append(f"{column} = ?") values.append(value) query = params.get("q", [""])[0].strip() if query: where.append("(f.sql_digest LIKE ? OR f.normalized_sql LIKE ? OR f.source_event_id LIKE ?)") like = f"%{query}%" values.extend([like, like, like]) symptom_codes = param_values(params, "symptom_code") symptom_severities = param_values(params, "symptom_severity") if symptom_codes or symptom_severities: symptom_where = ["fs.finding_id = f.id"] if symptom_codes: placeholders = ",".join("?" for _ in symptom_codes) symptom_where.append(f"fs.symptom_code IN ({placeholders})") values.extend(symptom_codes) if symptom_severities: placeholders = ",".join("?" for _ in symptom_severities) symptom_where.append(f"fs.severity IN ({placeholders})") values.extend(symptom_severities) where.append( "EXISTS (SELECT 1 FROM finding_symptoms fs WHERE " + " AND ".join(symptom_where) + ")" ) if params.get("new_digest", [""])[0]: where.append("f.is_first_observation = ?") values.append(1 if params["new_digest"][0].lower() in {"1", "true", "yes"} else 0) if params.get("created_catalog_item", [""])[0]: where.append("f.is_new_digest = ?") values.append( 1 if params["created_catalog_item"][0].lower() in {"1", "true", "yes"} else 0 ) if params.get("created_from", [""])[0]: where.append("COALESCE(f.reported_at, f.created_at) >= ?") values.append(params["created_from"][0]) if params.get("created_to", [""])[0]: where.append("COALESCE(f.reported_at, f.created_at) < ?") values.append(params["created_to"][0]) time_basis = params.get("time_basis", ["created"])[0] time_column = finding_time_column(time_basis) if params.get("from", [""])[0]: where.append(f"{time_column} >= ?") values.append(params["from"][0]) if params.get("to", [""])[0]: where.append(f"{time_column} < ?") values.append(params["to"][0]) if params.get("has_active_treatment", [""])[0]: expected = params["has_active_treatment"][0].lower() in {"1", "true", "yes"} where.append( ("" if expected else "NOT ") + "EXISTS (SELECT 1 FROM relations r JOIN treatments t ON t.id = r.to_id " "WHERE r.from_type = 'finding' AND r.from_id = f.id " "AND r.relation_type = 'evidence_of' AND r.to_type = 'treatment' AND t.state = 'active')" ) if params.get("has_triage_record", [""])[0]: expected = params["has_triage_record"][0].lower() in {"1", "true", "yes"} where.append( ("" if expected else "NOT ") + "EXISTS (SELECT 1 FROM relations rr JOIN records rec ON rec.id = rr.from_id " "WHERE rr.from_type = 'record' AND rr.relation_type = 'record_of' " "AND rr.to_type = 'catalog_item' AND rr.to_id = f.catalog_item_id " "AND rec.record_type IN ('triage_record', 'no_action_record'))" ) return (" WHERE " + " AND ".join(where)) if where else "", values def list_findings(params: dict[str, list[str]]) -> dict[str, Any]: where_sql, values = finding_filter_sql(params) limit = positive_int(params.get("limit", ["100"])[0], 100, 500) offset = positive_int(params.get("offset", ["0"])[0], 0, 1_000_000) base = " FROM findings f LEFT JOIN catalog_items ci ON ci.id = f.catalog_item_id" with get_conn() as conn: total = conn.execute("SELECT COUNT(*)" + base + where_sql, values).fetchone()[0] order_column = finding_time_column(params.get("time_basis", ["created"])[0]) rows = conn.execute( "SELECT f.*, ci.owner AS catalog_owner" + base + where_sql + f" ORDER BY {order_column} DESC, f.created_at DESC LIMIT ? OFFSET ?", [*values, limit, offset], ).fetchall() items = rows_to_findings(conn, rows, compact=True) attach_catalog_postures(conn, items) attach_active_treatment_ids(conn, items) return {"items": items, "total": total, "limit": limit, "offset": offset} def normalize_finding_selection(value: Any) -> dict[str, Any]: if not isinstance(value, dict): raise ValueError("selection must be an object") ids_value = value.get("ids") filter_value = value.get("filter") if bool(ids_value) == bool(filter_value): raise ValueError("selection must contain exactly one of ids or filter") excluded_ids = code_list( value.get("exclude_ids"), "selection.exclude_ids", maximum=5000, max_length=256 ) if ids_value: ids = code_list(ids_value, "selection.ids", maximum=5000, max_length=256) if not ids: raise ValueError("selection.ids must not be empty") if len(ids) > 5000: raise ValueError("selection.ids must contain at most 5000 entries") return {"ids": ids, "exclude_ids": excluded_ids} if not isinstance(filter_value, dict) or not filter_value: raise ValueError("selection.filter must be a non-empty object") unknown = sorted(set(filter_value) - FINDING_DELETION_FILTER_FIELDS) if unknown: raise ValueError(f"selection.filter contains unsupported fields: {', '.join(unknown)}") normalized_filter: dict[str, list[str]] = {} for key, raw in filter_value.items(): values = raw if isinstance(raw, list) else [raw] normalized = [str(item).strip() for item in values if str(item).strip()] if normalized: normalized_filter[key] = normalized if not normalized_filter: raise ValueError("selection.filter must contain at least one value") return {"filter": normalized_filter, "exclude_ids": excluded_ids} def selected_active_findings( conn: sqlite3.Connection, selection: dict[str, Any] ) -> list[sqlite3.Row]: excluded = set(selection.get("exclude_ids") or []) if selection.get("ids"): ids = [finding_id for finding_id in selection["ids"] if finding_id not in excluded] if not ids: return [] placeholders = ",".join("?" for _ in ids) return conn.execute( f""" SELECT f.id, f.catalog_item_id, f.org_id, f.cluster_id, f.sql_digest, f.severity, f.source, f.source_event_id FROM findings f WHERE f.deleted_at IS NULL AND f.id IN ({placeholders}) ORDER BY COALESCE(f.reported_at, f.created_at) DESC, f.created_at DESC """, ids, ).fetchall() params = {key: list(values) for key, values in selection["filter"].items()} params["deletion_state"] = ["active"] where_sql, values = finding_filter_sql(params) rows = conn.execute( """ SELECT f.id, f.catalog_item_id, f.org_id, f.cluster_id, f.sql_digest, f.severity, f.source, f.source_event_id FROM findings f LEFT JOIN catalog_items ci ON ci.id = f.catalog_item_id """ + where_sql + " ORDER BY COALESCE(f.reported_at, f.created_at) DESC, f.created_at DESC", values, ).fetchall() return [row for row in rows if row["id"] not in excluded] def finding_deletion_preview(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: selection = normalize_finding_selection(payload.get("selection")) except ValueError as exc: return 400, {"error": "invalid_finding_selection", "message": str(exc)} with get_conn() as conn: rows = selected_active_findings(conn, selection) severity_counts: dict[str, int] = defaultdict(int) source_counts: dict[str, int] = defaultdict(int) for row in rows: severity_counts[row["severity"]] += 1 source_counts[row["source"]] += 1 return 200, { "selection": selection, "matched_count": len(rows), "sample_ids": [row["id"] for row in rows[:10]], "severity_counts": dict(severity_counts), "source_counts": dict(source_counts), } def catalog_item_should_persist_without_findings( conn: sqlite3.Connection, item_id: str ) -> bool: item = get_catalog_item(conn, item_id) if item and catalog_item_registration(conn, item).get("origin") == "manual": return True return bool( conn.execute( """ SELECT 1 FROM relations WHERE (to_type = 'catalog_item' AND to_id = ? AND from_type IN ('treatment', 'record')) OR (from_type = 'catalog_item' AND from_id = ? AND to_type IN ('treatment', 'record')) OR ( from_type = 'record' AND relation_type = 'record_of' AND to_type = 'finding' AND to_id IN (SELECT id FROM findings WHERE catalog_item_id = ?) ) LIMIT 1 """, (item_id, item_id, item_id), ).fetchone() ) def recompute_catalog_item_facts(conn: sqlite3.Connection, item_id: str) -> None: rows = conn.execute( """ SELECT * FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL ORDER BY created_at """, (item_id,), ).fetchall() timestamp = now_iso() if not rows: item = get_catalog_item(conn, item_id) registration = catalog_item_registration(conn, item) if item else {} manually_registered = registration.get("origin") == "manual" orphaned_at = ( None if catalog_item_should_persist_without_findings(conn, item_id) else timestamp ) conn.execute( """ UPDATE catalog_items SET first_seen_at = NULL, last_seen_at = NULL, latest_finding_at = NULL, reappeared_at = NULL, orphaned_at = ?, updated_at = ? WHERE id = ? """, ( orphaned_at, timestamp, item_id, ), ) return first_seen_at = min(str(row["time_window_start"] or row["observed_at"]) for row in rows) last_seen_at = max(str(row["time_window_end"] or row["observed_at"]) for row in rows) latest_finding_at = max( str(row["reported_at"] or row["created_at"]) for row in rows ) conn.execute( """ UPDATE catalog_items SET first_seen_at = ?, last_seen_at = ?, latest_finding_at = ?, orphaned_at = NULL, updated_at = ? WHERE id = ? """, (first_seen_at, last_seen_at, latest_finding_at, timestamp, item_id), ) def delete_findings(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: selection = normalize_finding_selection(payload.get("selection")) reason = require_string(payload, "reason", max_length=1000) deleted_by = optional_string(payload.get("deleted_by"), "deleted_by", 128) or current_user_id() expected_count_value = payload.get("expected_count") if isinstance(expected_count_value, bool) or not isinstance(expected_count_value, int): raise ValueError("expected_count must be an integer from deletion preview") expected_count = expected_count_value if expected_count < 0: raise ValueError("expected_count must not be negative") except ValueError as exc: return 400, {"error": "invalid_finding_deletion", "message": str(exc)} with get_conn() as conn: rows = selected_active_findings(conn, selection) if len(rows) != expected_count: return 409, { "error": "finding_selection_changed", "message": "The matching Finding count changed after preview. Preview again before deleting.", "expected_count": expected_count, "actual_count": len(rows), } deletion_id = new_id("del") timestamp = now_iso() conn.execute( """ INSERT INTO finding_deletions (id, requested_by, reason, selection_json, finding_count, created_at) VALUES (?, ?, ?, ?, ?, ?) """, (deletion_id, deleted_by, reason, json_dumps(selection), len(rows), timestamp), ) identities: set[tuple[str, str, str]] = set() item_ids: set[str] = set() for row in rows: conn.execute( """ UPDATE findings SET deleted_at = ?, deleted_by = ?, deletion_reason = ?, deletion_id = ? WHERE id = ? AND deleted_at IS NULL """, (timestamp, deleted_by, reason, deletion_id, row["id"]), ) identities.add((row["org_id"], row["cluster_id"], row["sql_digest"])) item_ids.add(row["catalog_item_id"]) add_timeline( conn, "finding_deleted", "finding", row["id"], "Finding deleted", {"deletion_id": deletion_id, "reason": reason}, deleted_by, ) for org_id, cluster_id, sql_digest in identities: recompute_first_observation(conn, org_id, cluster_id, sql_digest) for item_id in item_ids: recompute_catalog_item_facts(conn, item_id) add_timeline( conn, "findings_deleted", "catalog_item", item_id, "Related Findings deleted", {"deletion_id": deletion_id, "reason": reason}, deleted_by, ) return 200, { "deletion_id": deletion_id, "deleted_count": len(rows), "deleted_at": timestamp, } def restore_findings(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: ids = code_list(payload.get("ids"), "ids", maximum=5000, max_length=256) if not ids: raise ValueError("ids must be a non-empty array") if len(ids) > 5000: raise ValueError("ids must contain at most 5000 entries") restored_by = optional_string(payload.get("restored_by"), "restored_by", 128) or current_user_id() reason = optional_string(payload.get("reason"), "reason", 1000) or "Finding restored" except ValueError as exc: return 400, {"error": "invalid_finding_restoration", "message": str(exc)} placeholders = ",".join("?" for _ in ids) with get_conn() as conn: rows = conn.execute( f""" SELECT id, catalog_item_id, org_id, cluster_id, sql_digest, deletion_id FROM findings WHERE deleted_at IS NOT NULL AND id IN ({placeholders}) """, ids, ).fetchall() timestamp = now_iso() identities: set[tuple[str, str, str]] = set() item_ids: set[str] = set() for row in rows: conn.execute( """ UPDATE findings SET deleted_at = NULL, deleted_by = NULL, deletion_reason = NULL, deletion_id = NULL WHERE id = ? """, (row["id"],), ) identities.add((row["org_id"], row["cluster_id"], row["sql_digest"])) item_ids.add(row["catalog_item_id"]) add_timeline( conn, "finding_restored", "finding", row["id"], "Finding restored", {"previous_deletion_id": row["deletion_id"], "reason": reason}, restored_by, ) for org_id, cluster_id, sql_digest in identities: recompute_first_observation(conn, org_id, cluster_id, sql_digest) for item_id in item_ids: recompute_catalog_item_facts(conn, item_id) add_timeline( conn, "findings_restored", "catalog_item", item_id, "Related Findings restored", {"finding_ids": [row["id"] for row in rows if row["catalog_item_id"] == item_id]}, restored_by, ) return 200, {"restored_count": len(rows), "restored_at": timestamp} def finding_period_bounds( params: dict[str, list[str]], ) -> tuple[str | None, str | None, str]: time_basis = params.get("time_basis", ["created"])[0] if time_basis not in {"created", "observed", "ingested"}: time_basis = "created" start = params.get("from", [""])[0] or params.get("created_from", [""])[0] or None end = params.get("to", [""])[0] or params.get("created_to", [""])[0] or None return start, end, time_basis def finding_time_column(time_basis: str) -> str: if time_basis == "observed": return "COALESCE(f.observed_at, f.time_window_end, f.created_at)" if time_basis == "ingested": return "COALESCE(f.ingested_at, f.created_at)" return "COALESCE(f.reported_at, f.created_at)" def try_datetime(value: str | None) -> datetime | None: if not value: return None try: parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) except ValueError: return None if parsed.tzinfo is None: parsed = parsed.replace(tzinfo=timezone.utc) return parsed.astimezone(timezone.utc) def iso_datetime(value: datetime) -> str: return value.isoformat().replace("+00:00", "Z") def params_for_period( params: dict[str, list[str]], start: str, end: str ) -> dict[str, list[str]]: result = { key: list(value) for key, value in params.items() if key not in {"from", "to", "created_from", "created_to", "compare", "compare_from", "compare_to"} } result["from"] = [start] result["to"] = [end] return result def load_finding_data( conn: sqlite3.Connection, params: dict[str, list[str]] ) -> list[dict[str, Any]]: where_sql, values = finding_filter_sql(params) rows = conn.execute( "SELECT f.* " "FROM findings f LEFT JOIN catalog_items ci ON ci.id = f.catalog_item_id" + where_sql, values, ).fetchall() items = rows_to_findings(conn, rows) attach_catalog_postures(conn, items) return items def metric_breakdown( data: list[dict[str, Any]], key: str, *, multiple: bool = False ) -> list[dict[str, Any]]: grouped: dict[str, dict[str, Any]] = {} for item in data: raw_values = item.get(key) or [] if multiple else [item.get(key) or "unknown"] for raw_value in raw_values: value = str(raw_value) entry = grouped.setdefault( value, {"key": value, "count": 0, "critical_count": 0, "first_seen_count": 0}, ) entry["count"] += 1 entry["critical_count"] += int(item.get("severity") == "critical") entry["first_seen_count"] += int(bool(item.get("is_first_observation"))) return sorted(grouped.values(), key=lambda entry: (-entry["count"], entry["key"])) def symptom_breakdown(data: list[dict[str, Any]]) -> list[dict[str, Any]]: grouped: dict[str, dict[str, Any]] = {} for item in data: for symptom in item.get("symptoms", []): code = str(symptom.get("code") or "unknown") entry = grouped.setdefault( code, { "key": code, "count": 0, "critical_count": 0, "first_seen_count": 0, "finding_ids": set(), }, ) entry["count"] += 1 entry["critical_count"] += int(symptom.get("severity") == "critical") entry["first_seen_count"] += int(bool(item.get("is_first_observation"))) entry["finding_ids"].add(item["id"]) result = [] for entry in grouped.values(): finding_ids = entry.pop("finding_ids") entry["finding_count"] = len(finding_ids) result.append(entry) return sorted(result, key=lambda entry: (-entry["count"], entry["key"])) def timezone_offset_minutes(params: dict[str, list[str]]) -> int: try: value = int(params.get("timezone_offset_minutes", ["0"])[0]) except (TypeError, ValueError): return 0 return max(-14 * 60, min(14 * 60, value)) def day_bucket_start( value: datetime, timezone_offset_minutes: int ) -> datetime: offset_seconds = timezone_offset_minutes * 60 shifted_epoch = value.timestamp() + offset_seconds bucket_epoch = (int(shifted_epoch) // DAY_BUCKET_SECONDS) * DAY_BUCKET_SECONDS return datetime.fromtimestamp(bucket_epoch - offset_seconds, tz=timezone.utc) def empty_finding_bucket(bucket: str) -> dict[str, Any]: return { "bucket": bucket, "count": 0, "critical_count": 0, "first_seen_count": 0, "symptom_count": 0, "digests": set(), } def aggregate_findings( data: list[dict[str, Any]], *, time_basis: str, period_start: str | None, period_end: str | None, timezone_offset_minutes: int = 0, ) -> dict[str, Any]: severity_counts: dict[str, int] = defaultdict(int) source_counts: dict[str, int] = defaultdict(int) symptom_counts: dict[str, int] = defaultdict(int) detector_counts: dict[str, int] = defaultdict(int) cluster_counts: dict[str, int] = defaultdict(int) org_counts: dict[str, int] = defaultdict(int) buckets: dict[str, dict[str, Any]] = {} for item in data: severity_counts[item.get("severity") or "unknown"] += 1 source_counts[item.get("source") or "unknown"] += 1 cluster_counts[item.get("cluster_id") or "unknown"] += 1 org_counts[item.get("org_id") or "unknown"] += 1 detector_counts[item.get("detector_code") or "unspecified"] += 1 for symptom in item.get("symptoms", []): symptom_counts[str(symptom.get("code") or "unknown")] += 1 timestamp = ( item.get("observed_at") if time_basis == "observed" else item.get("ingested_at") if time_basis == "ingested" else item.get("reported_at") or item.get("created_at") ) timestamp_value = try_datetime(str(timestamp)) if timestamp else None bucket = iso_datetime( day_bucket_start(timestamp_value, timezone_offset_minutes) ) if timestamp_value else "" if bucket: entry = buckets.setdefault(bucket, empty_finding_bucket(bucket)) entry["count"] += 1 entry["critical_count"] += int(item.get("severity") == "critical") entry["first_seen_count"] += int(bool(item.get("is_first_observation"))) entry["symptom_count"] += len(item.get("symptoms", [])) entry["digests"].add((item.get("org_id"), item.get("cluster_id"), item.get("sql_digest"))) start_value = try_datetime(period_start) end_value = try_datetime(period_end) if start_value and end_value and end_value > start_value: cursor = day_bucket_start(start_value, timezone_offset_minutes) while cursor < end_value: key = iso_datetime(cursor) buckets.setdefault(key, empty_finding_bucket(key)) cursor += timedelta(seconds=DAY_BUCKET_SECONDS) time_series = [] for key in sorted(buckets): entry = buckets[key] time_series.append( { "bucket": key, "count": entry["count"], "critical_count": entry["critical_count"], "first_seen_count": entry["first_seen_count"], "symptom_count": entry["symptom_count"], "distinct_digest_count": len(entry["digests"]), } ) digest_identities = { (item.get("org_id"), item.get("cluster_id"), item.get("sql_digest")) for item in data } summary = { "total_findings": len(data), "symptom_occurrences": sum(len(item.get("symptoms", [])) for item in data), "critical_findings": severity_counts.get("critical", 0), "high_findings": severity_counts.get("high", 0), "distinct_digests": len(digest_identities), "first_seen_digests": sum(1 for item in data if item.get("is_first_observation")), "catalog_items_created": sum(1 for item in data if item.get("is_new_digest")), "affected_clusters": len({item.get("cluster_id") for item in data}), "affected_orgs": len({item.get("org_id") for item in data}), } return { "summary": summary, "severity_counts": dict(severity_counts), "source_counts": dict(source_counts), "symptom_counts": dict(symptom_counts), "detector_counts": dict(detector_counts), "cluster_counts": dict(cluster_counts), "org_counts": dict(org_counts), "time_series": time_series, "breakdowns": { "organizations": metric_breakdown(data, "org_id"), "clusters": metric_breakdown(data, "cluster_id"), "detectors": metric_breakdown(data, "detector_code"), "symptoms": symptom_breakdown(data), "sources": metric_breakdown(data, "source"), }, } def finding_run_filter_sql( params: dict[str, list[str]], start: str | None, end: str | None, time_basis: str ) -> tuple[str, list[Any]]: where: list[str] = [] values: list[Any] = [] for key, column in { "org_id": "r.org_id", "project_id": "r.project_id", "cluster_id": "r.cluster_id", "source": "r.source", "source_type": "r.source_type", }.items(): selected = param_values(params, key) if selected: placeholders = ",".join("?" for _ in selected) where.append(f"{column} IN ({placeholders})") values.extend(selected) time_column = "r.time_window_end" if time_basis == "observed" else "r.ingested_at" if start: where.append(f"{time_column} >= ?") values.append(start) if end: where.append(f"{time_column} < ?") values.append(end) return (" WHERE " + " AND ".join(where)) if where else "", values def finding_run_coverage( conn: sqlite3.Connection, params: dict[str, list[str]], start: str | None, end: str | None, time_basis: str, ) -> dict[str, Any]: where_sql, values = finding_run_filter_sql(params, start, end, time_basis) rows = conn.execute( """ SELECT r.*, COUNT(f.id) AS finding_count FROM finding_runs r LEFT JOIN findings f ON f.finding_run_id = r.id AND f.deleted_at IS NULL """ + where_sql + " GROUP BY r.id ORDER BY r.time_window_end", values, ).fetchall() selected_clusters = param_values(params, "cluster_id") if not selected_clusters: fallback_where, fallback_values = finding_run_filter_sql(params, None, None, time_basis) selected_clusters = [ row[0] for row in conn.execute( "SELECT DISTINCT r.cluster_id FROM finding_runs r" + fallback_where + " ORDER BY r.cluster_id", fallback_values, ).fetchall() ] start_value = try_datetime(start) end_value = try_datetime(end) period_days = ( max(1, ceil((end_value - start_value).total_seconds() / 86_400)) if start_value and end_value and end_value > start_value else 0 ) expected_runs = period_days * len(selected_clusters) if period_days else len(rows) completed_rows = [row for row in rows if row["status"] in {"success", "partial"}] coverage_percent = ( round(min(1, len(completed_rows) / expected_runs) * 100, 1) if expected_runs else None ) expected_detectors = sum(row["expected_detector_count"] for row in completed_rows) completed_detectors = sum(row["completed_detector_count"] for row in completed_rows) detector_coverage_percent = ( round(min(1, completed_detectors / expected_detectors) * 100, 1) if expected_detectors else None ) status_counts: dict[str, int] = defaultdict(int) for row in rows: status_counts[row["status"]] += 1 return { "selected_cluster_count": len(selected_clusters), "expected_runs": expected_runs, "reported_runs": len(rows), "completed_runs": len(completed_rows), "missing_runs": max(0, expected_runs - len(completed_rows)), "zero_finding_runs": sum( 1 for row in completed_rows if int(row["finding_count"] or 0) == 0 ), "coverage_percent": coverage_percent, "detector_coverage_percent": detector_coverage_percent, "status_counts": dict(status_counts), } def list_finding_runs(params: dict[str, list[str]]) -> dict[str, Any]: start, end, time_basis = finding_period_bounds(params) where_sql, values = finding_run_filter_sql(params, start, end, time_basis) limit = positive_int(params.get("limit", ["100"])[0], 100, 500) offset = positive_int(params.get("offset", ["0"])[0], 0, 1_000_000) with get_conn() as conn: total = conn.execute( "SELECT COUNT(*) FROM finding_runs r" + where_sql, values ).fetchone()[0] rows = conn.execute( """ SELECT r.*, COUNT(f.id) AS finding_count FROM finding_runs r LEFT JOIN findings f ON f.finding_run_id = r.id AND f.deleted_at IS NULL """ + where_sql + " GROUP BY r.id ORDER BY r.time_window_end DESC LIMIT ? OFFSET ?", [*values, limit, offset], ).fetchall() items = [] for row in rows: item = row_to_finding_run(row) item["finding_count"] = int(item.get("finding_count") or 0) items.append(item) return {"items": items, "total": total, "limit": limit, "offset": offset} def finding_facets(conn: sqlite3.Connection) -> dict[str, list[str]]: facets: dict[str, list[str]] = {} for key, column in { "organizations": "org_id", "clusters": "cluster_id", "sources": "source", "source_types": "source_type", "detectors": "detector_code", }.items(): facets[key] = [ row[0] for row in conn.execute( f"SELECT DISTINCT {column} FROM findings WHERE deleted_at IS NULL AND {column} IS NOT NULL AND {column} != '' ORDER BY {column}" ).fetchall() ] facets["symptoms"] = [ row[0] for row in conn.execute( """ SELECT DISTINCT fs.symptom_code FROM finding_symptoms fs JOIN findings f ON f.id = fs.finding_id WHERE f.deleted_at IS NULL ORDER BY fs.symptom_code """ ).fetchall() ] facets["symptom_severities"] = [ row[0] for row in conn.execute( """ SELECT DISTINCT fs.severity FROM finding_symptoms fs JOIN findings f ON f.id = fs.finding_id WHERE f.deleted_at IS NULL ORDER BY fs.severity """ ).fetchall() ] return facets def metric_delta(current: int | float, previous: int | float) -> dict[str, Any]: absolute = current - previous percent = round(absolute / previous * 100, 1) if previous else None return {"absolute": absolute, "percent": percent} def format_optional_percent(value: int | float | None) -> str: return "unknown" if value is None else f"{value}%" def inspection_comparison_quality( current: dict[str, Any], comparison: dict[str, Any] | None, ) -> dict[str, Any]: if comparison is None: return { "comparable": True, "code": "none", "reason": "No comparison period is available.", } current_completed = int(current.get("completed_runs") or 0) comparison_completed = int(comparison.get("completed_runs") or 0) current_reported = int(current.get("reported_runs") or 0) comparison_reported = int(comparison.get("reported_runs") or 0) current_pct = current.get("coverage_percent") comparison_pct = comparison.get("coverage_percent") details = { "current_completed_runs": current_completed, "comparison_completed_runs": comparison_completed, "current_coverage_percent": current_pct, "comparison_coverage_percent": comparison_pct, } if not (current_reported or comparison_reported): return { "comparable": True, "code": "no_run_expectation", "reason": "Neither period contains inspection-run data; event counts are compared directly.", **details, } if current_completed > 0 and comparison_completed == 0: return { "comparable": False, "code": "no_baseline", "reason": "The comparison period has no completed inspection run.", **details, } comparable = ( current_pct is not None and comparison_pct is not None and current_pct >= 80 and comparison_pct >= 80 and abs(current_pct - comparison_pct) <= 10 ) if comparable: return { "comparable": True, "code": "comparable", "reason": "Both periods have comparable inspection coverage.", **details, } code = ( "coverage_mismatch" if current_pct is not None and comparison_pct is not None and abs(current_pct - comparison_pct) > 10 else "incomplete_coverage" ) return { "comparable": False, "code": code, "reason": ( "Inspection coverage is incomplete or differs between the two periods " f"(current {format_optional_percent(current_pct)}, " f"comparison {format_optional_percent(comparison_pct)})." ), **details, } def finding_stats(params: dict[str, list[str]]) -> dict[str, Any]: period_start, period_end, time_basis = finding_period_bounds(params) timezone_offset = timezone_offset_minutes(params) compare_start = params.get("compare_from", [""])[0] or None compare_end = params.get("compare_to", [""])[0] or None compare_mode = params.get("compare", ["previous"])[0] comparison_mode = "custom" if compare_start and compare_end else compare_mode if compare_mode != "none" and not (compare_start and compare_end): start_value = try_datetime(period_start) end_value = try_datetime(period_end) if start_value and end_value and end_value > start_value: duration = end_value - start_value compare_start = iso_datetime(start_value - duration) compare_end = iso_datetime(start_value) comparison_mode = "previous" with get_conn() as conn: data = load_finding_data(conn, params) current = aggregate_findings( data, time_basis=time_basis, period_start=period_start, period_end=period_end, timezone_offset_minutes=timezone_offset, ) comparison = None comparison_coverage = None if compare_start and compare_end and compare_mode != "none": comparison_data = load_finding_data( conn, params_for_period(params, compare_start, compare_end) ) comparison = aggregate_findings( comparison_data, time_basis=time_basis, period_start=compare_start, period_end=compare_end, timezone_offset_minutes=timezone_offset, ) comparison_coverage = finding_run_coverage( conn, params, compare_start, compare_end, time_basis ) coverage = finding_run_coverage(conn, params, period_start, period_end, time_basis) facets = finding_facets(conn) linked_active = 0 if data: finding_ids = [item["id"] for item in data] placeholders = ",".join("?" for _ in finding_ids) linked_active = conn.execute( f""" SELECT COUNT(DISTINCT r.from_id) FROM relations r JOIN treatments t ON t.id = r.to_id WHERE r.from_type = 'finding' AND r.from_id IN ({placeholders}) AND r.relation_type = 'evidence_of' AND r.to_type = 'treatment' AND t.state = 'active' """, finding_ids, ).fetchone()[0] untriaged = len( { item["catalog_item_id"] for item in data if (item.get("catalog_posture") or {}).get("state") == "needs_review" } ) summary = current["summary"] deltas = {} if comparison: for key in ( "total_findings", "symptom_occurrences", "critical_findings", "distinct_digests", "first_seen_digests", "affected_clusters", ): deltas[key] = metric_delta(summary[key], comparison["summary"][key]) comparison_quality = inspection_comparison_quality( coverage, comparison_coverage if comparison else None, ) return { "time_basis": time_basis, "timezone_offset_minutes": timezone_offset, "period": {"from": period_start, "to": period_end}, "comparison_period": ( {"from": compare_start, "to": compare_end} if comparison else None ), "comparison_mode": comparison_mode if comparison else "none", "summary": summary, "comparison": comparison, "deltas": deltas, "coverage": coverage, "comparison_coverage": comparison_coverage, "comparison_quality": comparison_quality, "breakdowns": current["breakdowns"], "facets": facets, "total_findings": summary["total_findings"], "severity_counts": current["severity_counts"], "source_counts": current["source_counts"], "symptom_counts": current["symptom_counts"], "total_symptom_occurrences": summary["symptom_occurrences"], "detector_counts": current["detector_counts"], "cluster_counts": current["cluster_counts"], "org_counts": current["org_counts"], "new_digest_count": summary["first_seen_digests"], "catalog_created_count": summary["catalog_items_created"], "existing_digest_count": summary["total_findings"] - summary["first_seen_digests"], "linked_active_treatment_count": linked_active, "untriaged_catalog_item_count": untriaged, "time_series": current["time_series"], } def finding_detail( finding_id: str, locale: str = "en" ) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = conn.execute("SELECT * FROM findings WHERE id = ?", (finding_id,)).fetchone() if not row: return 404, {"error": "finding_not_found"} symptom_map = load_finding_symptoms(conn, [finding_id]) finding = row_to_finding(row, symptom_map[finding_id]) item = get_catalog_item(conn, finding["catalog_item_id"]) metric_finding_rows = conn.execute( """ SELECT * FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL ORDER BY observed_at, created_at, id """, (finding["catalog_item_id"],), ).fetchall() metric_findings = rows_to_findings(conn, metric_finding_rows) treatments = [ enrich_treatment(conn, row_to_treatment(treatment_row)) for treatment_row in conn.execute( """ SELECT t.* FROM treatments t JOIN relations r ON r.to_type = 'treatment' AND r.to_id = t.id WHERE r.from_type = 'finding' AND r.from_id = ? AND r.relation_type = 'evidence_of' ORDER BY t.updated_at DESC """, (finding_id,), ).fetchall() ] records = [ row_to_record(record_row) for record_row in conn.execute( """ SELECT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id WHERE r.relation_type = 'record_of' AND r.to_type = 'finding' AND r.to_id = ? ORDER BY rec.updated_at DESC """, (finding_id,), ).fetchall() ] sequence_sql = timeline_sequence_sql(conn) timeline = [ row_to_timeline(event_row, locale) for event_row in conn.execute( f""" SELECT * FROM timeline_events WHERE target_type = 'finding' AND target_id = ? ORDER BY created_at DESC, {sequence_sql} DESC """, (finding_id,), ).fetchall() ] return 200, { "finding": finding, "catalog_item": enrich_catalog_item(conn, item) if item else None, "treatments": treatments, "records": records, "timeline": timeline, "metric_history": project_catalog_metric_history( metric_findings, { code: translate( f"domain:symptom.{code}.name", locale, default=name ) for code, name in SYMPTOM_NAMES.items() }, ), } def create_catalog_item(payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: try: reject_unknown_fields(payload, CATALOG_ITEM_INPUT_FIELDS, "catalog item") org_id = require_string(payload, "org_id", max_length=128) cluster_id = require_string(payload, "cluster_id", max_length=128) sql_digest = require_string(payload, "sql_digest", max_length=256) registration_reason = require_string( payload, "registration_reason", max_length=64 ).lower() if registration_reason not in CATALOG_REGISTRATION_REASONS: raise ValueError( "registration_reason must be one of " + ", ".join(sorted(CATALOG_REGISTRATION_REASONS)) ) initial_action = optional_string( payload.get("initial_action"), "initial_action", 64 ) or "register_only" if initial_action not in CATALOG_INITIAL_ACTIONS: raise ValueError( "initial_action must be one of " + ", ".join(sorted(CATALOG_INITIAL_ACTIONS)) ) project_id = optional_string(payload.get("project_id"), "project_id", 128) normalized_sql = optional_string( payload.get("normalized_sql"), "normalized_sql", 200_000 ) or "" source_reference = optional_string( payload.get("source_reference"), "source_reference", 512 ) source_url = optional_string(payload.get("source_url"), "source_url", 2_000) if source_url: parsed_url = urlparse(source_url) if parsed_url.scheme not in {"http", "https"} or not parsed_url.netloc: raise ValueError("source_url must be an absolute HTTP or HTTPS URL") note = optional_string(payload.get("note"), "note", 10_000) if registration_reason == "other" and not note: raise ValueError("note is required when registration_reason is other") owner = optional_string(payload.get("owner"), "owner", 128) created_by = optional_string(payload.get("created_by"), "created_by", 128) or current_actor() except ValueError as exc: return 400, {"error": "invalid_catalog_item", "message": str(exc)} governance_relevance = catalog_governance_relevance( {"normalized_sql": normalized_sql} ) if initial_action == "watch" and not governance_relevance["review_eligible"]: return 409, { "error": "catalog_item_not_review_eligible", "governance_relevance": governance_relevance, } with get_conn() as conn: existing_row = conn.execute( """ SELECT * FROM catalog_items WHERE org_id = ? AND cluster_id = ? AND sql_digest = ? """, (org_id, cluster_id, sql_digest), ).fetchone() if existing_row: existing = enrich_catalog_item(conn, row_to_catalog_item(existing_row)) return 409, { "error": "catalog_item_exists", "message": "This SQL digest is already registered for the selected cluster.", "catalog_item": existing, } timestamp = now_iso() item_id = new_id("cat") conn.execute( """ INSERT INTO catalog_items (id, org_id, project_id, cluster_id, sql_digest, normalized_sql, owner, priority, labels_json, first_seen_at, last_seen_at, latest_finding_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( item_id, org_id, project_id, cluster_id, sql_digest, normalized_sql, owner, "normal", json_dumps([]), None, None, None, timestamp, timestamp, ), ) add_timeline( conn, "catalog_item_created", "catalog_item", item_id, "Catalog item manually registered", { "registration_origin": "manual", "registration_reason": registration_reason, "source_reference": source_reference, "source_url": source_url, "note": note, "initial_action": initial_action, "owner": owner, }, created_by, timestamp, ) item = enrich_catalog_item(conn, get_catalog_item(conn, item_id)) return 201, {"created": True, "catalog_item": item} def catalog_filter_sql(params: dict[str, list[str]]) -> tuple[str, list[Any]]: where: list[str] = [] values: list[Any] = [] if params.get("include_orphaned", [""])[0].lower() not in {"1", "true", "yes"}: where.append("ci.orphaned_at IS NULL") for key in ["org_id", "project_id", "cluster_id", "sql_digest", "owner"]: selected = param_values(params, key) if selected: placeholders = ",".join("?" for _ in selected) where.append(f"ci.{key} IN ({placeholders})") values.extend(selected) lifecycle = param_values(params, "lifecycle") if lifecycle: lifecycle_conditions = [] if "active" in lifecycle: lifecycle_conditions.append("ci.archived_at IS NULL") if "archived" in lifecycle: lifecycle_conditions.append("ci.archived_at IS NOT NULL") if lifecycle_conditions: where.append("(" + " OR ".join(lifecycle_conditions) + ")") query = params.get("q", [""])[0].strip() if query: where.append("(ci.sql_digest LIKE ? OR ci.normalized_sql LIKE ?)") values.extend([f"%{query}%", f"%{query}%"]) if params.get("has_active_treatment", [""])[0]: expected = params["has_active_treatment"][0].lower() in {"1", "true", "yes"} where.append( ("" if expected else "NOT ") + "EXISTS (SELECT 1 FROM relations r JOIN treatments t ON t.id = r.from_id " "WHERE r.from_type = 'treatment' AND r.relation_type = 'treatment_for' " "AND r.to_type = 'catalog_item' AND r.to_id = ci.id AND t.state = 'active')" ) if params.get("source", [""])[0]: where.append( "EXISTS (SELECT 1 FROM findings f WHERE f.catalog_item_id = ci.id AND f.deleted_at IS NULL AND f.source = ?)" ) values.append(params["source"][0]) if params.get("symptom_code", [""])[0]: where.append( """ EXISTS ( SELECT 1 FROM findings f JOIN finding_symptoms fs ON fs.finding_id = f.id WHERE f.catalog_item_id = ci.id AND f.deleted_at IS NULL AND fs.symptom_code = ? ) """ ) values.append(params["symptom_code"][0]) return (" WHERE " + " AND ".join(where)) if where else "", values def enrich_catalog_item(conn: sqlite3.Connection, item: dict[str, Any]) -> dict[str, Any]: item["registration"] = catalog_item_registration(conn, item) finding_counts = conn.execute( """ SELECT COUNT(*) AS finding_count, COALESCE(SUM(CASE WHEN COALESCE(reported_at, created_at) >= ? THEN 1 ELSE 0 END), 0) AS finding_count_7d, COALESCE(SUM(CASE WHEN COALESCE(reported_at, created_at) >= ? THEN 1 ELSE 0 END), 0) AS finding_count_30d, COUNT(DISTINCT COALESCE(finding_run_id, id)) AS finding_run_count, COUNT(DISTINCT CASE WHEN COALESCE(reported_at, created_at) >= ? THEN COALESCE(finding_run_id, id) END) AS finding_run_count_7d FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL """, (since_iso(7), since_iso(30), since_iso(7), item["id"]), ).fetchone() item["finding_count"] = finding_counts["finding_count"] item["finding_count_7d"] = finding_counts["finding_count_7d"] item["finding_count_30d"] = finding_counts["finding_count_30d"] item["finding_run_count"] = finding_counts["finding_run_count"] item["finding_run_count_7d"] = finding_counts["finding_run_count_7d"] item["symptom_codes"] = [ row["symptom_code"] for row in conn.execute( """ SELECT fs.symptom_code, COUNT(*) AS occurrence_count FROM finding_symptoms fs JOIN findings f ON f.id = fs.finding_id WHERE f.catalog_item_id = ? AND f.deleted_at IS NULL GROUP BY fs.symptom_code ORDER BY occurrence_count DESC, fs.symptom_code LIMIT 3 """, (item["id"],), ).fetchall() ] treatment_counts = conn.execute( """ SELECT COUNT(DISTINCT t.id) AS treatment_count, COUNT(DISTINCT CASE WHEN t.state = 'active' THEN t.id END) AS active_treatment_count FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? """, (item["id"],), ).fetchone() item["treatment_count"] = treatment_counts["treatment_count"] item["active_treatment_count"] = treatment_counts["active_treatment_count"] item["record_count"] = conn.execute( """ SELECT COUNT(DISTINCT rec.id) FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' WHERE (r.to_type = 'catalog_item' AND r.to_id = ?) OR (r.to_type = 'treatment' AND r.to_id IN ( SELECT t.id FROM treatments t JOIN relations treatment_relation ON treatment_relation.from_type = 'treatment' AND treatment_relation.from_id = t.id AND treatment_relation.relation_type = 'treatment_for' AND treatment_relation.to_type = 'catalog_item' AND treatment_relation.to_id = ? )) """, (item["id"], item["id"]), ).fetchone()[0] latest_record = conn.execute( """ SELECT DISTINCT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' WHERE (r.to_type = 'catalog_item' AND r.to_id = ?) OR (r.to_type = 'treatment' AND r.to_id IN ( SELECT t.id FROM treatments t JOIN relations treatment_relation ON treatment_relation.from_type = 'treatment' AND treatment_relation.from_id = t.id AND treatment_relation.relation_type = 'treatment_for' AND treatment_relation.to_type = 'catalog_item' AND treatment_relation.to_id = ? )) ORDER BY rec.updated_at DESC, rec.id DESC LIMIT 1 """, (item["id"], item["id"]), ).fetchone() item["latest_record"] = row_to_record(latest_record) if latest_record else None item["current_posture"] = catalog_current_posture( conn, item, registration=item["registration"] ) item["active_treatment_count"] = item["current_posture"]["active_treatment_count"] item["is_reappeared"] = "reappeared" in item["current_posture"]["reasons"] return item def project_catalog_items( conn: sqlite3.Connection, catalog_rows: list[sqlite3.Row], catalog_events: list[dict[str, Any]] | None = None, *, include_records: bool = False, ) -> tuple[list[dict[str, Any]], dict[str, dict[str, Any]]]: items = [row_to_catalog_item(row) for row in catalog_rows] if not items: return [], {} item_ids = [item["id"] for item in items] placeholders = ",".join("?" for _ in item_ids) finding_rows = conn.execute( f""" SELECT catalog_item_id, id, source, detector_code, severity, created_at, reported_at, observed_at, source_run_id, finding_run_id, dimensions_json, metrics_json, COALESCE(reported_at, created_at) AS event_at FROM findings WHERE deleted_at IS NULL AND catalog_item_id IN ({placeholders}) ORDER BY catalog_item_id, COALESCE(reported_at, created_at), created_at, id """, item_ids, ).fetchall() findings_by_item: dict[str, list[dict[str, Any]]] = defaultdict(list) findings_by_id: dict[str, dict[str, Any]] = {} for row in finding_rows: finding = dict(row) finding["dimensions"] = ensure_dict( json_loads(finding.get("dimensions_json"), {}) ) finding["metrics"] = ensure_dict( json_loads(finding.get("metrics_json"), {}) ) finding["signal_class"] = finding_signal_class(finding) finding["symptoms"] = [] findings_by_item[row["catalog_item_id"]].append(finding) findings_by_id[str(row["id"])] = finding focus_anchor = max( ( event_at for finding in findings_by_id.values() if (event_at := try_datetime(finding.get("event_at"))) is not None ), default=None, ) symptom_rows = conn.execute( f""" SELECT f.catalog_item_id, fs.finding_id, fs.symptom_code, fs.severity FROM finding_symptoms fs JOIN findings f ON f.id = fs.finding_id WHERE f.deleted_at IS NULL AND f.catalog_item_id IN ({placeholders}) ORDER BY f.catalog_item_id, fs.finding_id, fs.symptom_code """, item_ids, ).fetchall() symptom_counts_by_item: dict[str, dict[str, int]] = defaultdict( lambda: defaultdict(int) ) for row in symptom_rows: symptom_counts_by_item[row["catalog_item_id"]][row["symptom_code"]] += 1 finding = findings_by_id.get(str(row["finding_id"])) if finding is not None: finding["symptoms"].append( {"code": row["symptom_code"], "severity": row["severity"]} ) symptoms_by_item: dict[str, list[str]] = defaultdict(list) for item_id, counts in symptom_counts_by_item.items(): symptoms_by_item[item_id] = [ code for code, _ in sorted( counts.items(), key=lambda entry: (-entry[1], entry[0]) )[:3] ] treatment_rows = conn.execute( f""" SELECT r.to_id AS catalog_item_id, t.* FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' WHERE r.to_id IN ({placeholders}) ORDER BY r.to_id, CASE t.state WHEN 'active' THEN 0 ELSE 1 END, t.updated_at DESC, t.id """, item_ids, ).fetchall() treatments_by_item: dict[str, list[dict[str, Any]]] = defaultdict(list) for row in treatment_rows: treatment = row_to_treatment(row) item_id = str(treatment.pop("catalog_item_id")) treatments_by_item[item_id].append(treatment) records_by_item: dict[str, list[dict[str, Any]]] = defaultdict(list) if include_records: record_rows = conn.execute( f""" WITH record_links AS ( SELECT r.to_id AS catalog_item_id, r.from_id AS record_id FROM relations r WHERE r.from_type = 'record' AND r.relation_type = 'record_of' AND r.to_type = 'catalog_item' AND r.to_id IN ({placeholders}) UNION SELECT treatment_relation.to_id AS catalog_item_id, record_relation.from_id AS record_id FROM relations record_relation JOIN relations treatment_relation ON treatment_relation.from_type = 'treatment' AND treatment_relation.from_id = record_relation.to_id AND treatment_relation.relation_type = 'treatment_for' AND treatment_relation.to_type = 'catalog_item' WHERE record_relation.from_type = 'record' AND record_relation.relation_type = 'record_of' AND record_relation.to_type = 'treatment' AND treatment_relation.to_id IN ({placeholders}) ) SELECT links.catalog_item_id, rec.* FROM record_links links JOIN records rec ON rec.id = links.record_id ORDER BY links.catalog_item_id, rec.updated_at DESC, rec.id DESC """, [*item_ids, *item_ids], ).fetchall() for row in record_rows: record = row_to_record(row) item_id = str(record.pop("catalog_item_id")) records_by_item[item_id].append(record) if catalog_events is None: event_sequence_sql = timeline_sequence_sql(conn, "e") event_types = ( "catalog_item_created", "catalog_decision_recorded", "treatment_completed", "treatment_cancelled", ) event_placeholders = ",".join("?" for _ in event_types) event_rows = conn.execute( f""" SELECT e.*, {event_sequence_sql} AS event_sequence FROM timeline_events e WHERE e.target_type = 'catalog_item' AND e.target_id IN ({placeholders}) AND e.event_type IN ({event_placeholders}) ORDER BY e.created_at, {event_sequence_sql} """, [*item_ids, *event_types], ).fetchall() catalog_events = [] for row in event_rows: event = dict(row) event["payload"] = json_loads(event.pop("payload_json", None), {}) catalog_events.append(event) events_by_item: dict[str, list[dict[str, Any]]] = defaultdict(list) for event in catalog_events: events_by_item[event["target_id"]].append(event) cluster_ids = list(dict.fromkeys(item["cluster_id"] for item in items)) cluster_placeholders = ",".join("?" for _ in cluster_ids) policy_rows = conn.execute( f"SELECT * FROM cluster_sql_review_policies " f"WHERE cluster_id IN ({cluster_placeholders})", cluster_ids, ).fetchall() policies_by_cluster: dict[str, dict[str, Any]] = { cluster_id: { **DEFAULT_SQL_REVIEW_POLICY, "source": "system_default", "updated_by": None, "created_at": None, "updated_at": None, } for cluster_id in cluster_ids } for row in policy_rows: policies_by_cluster[row["cluster_id"]] = { "critical_finding_triggers_review": bool( row["critical_finding_triggers_review"] ), "finding_count_threshold": int(row["finding_count_threshold"]), "finding_window_days": int(row["finding_window_days"]), "source": "cluster", "updated_by": row["updated_by"], "created_at": row["created_at"], "updated_at": row["updated_at"], } cutoff_7d = since_iso(7) cutoff_30d = since_iso(30) policies_by_item: dict[str, dict[str, Any]] = {} for item in items: findings = findings_by_item.get(item["id"], []) treatments = treatments_by_item.get(item["id"], []) events = events_by_item.get(item["id"], []) registration_event = next( ( event for event in events if event["event_type"] == "catalog_item_created" ), None, ) registration = catalog_registration_from_event(item, registration_event) run_ids = { str(finding.get("finding_run_id") or finding["id"]) for finding in findings } recent_run_ids = { str(finding.get("finding_run_id") or finding["id"]) for finding in findings if finding["event_at"] >= cutoff_7d } item["registration"] = registration item["finding_count"] = len(findings) item["finding_count_7d"] = sum( 1 for finding in findings if finding["event_at"] >= cutoff_7d ) item["finding_count_30d"] = sum( 1 for finding in findings if finding["event_at"] >= cutoff_30d ) item["finding_run_count"] = len(run_ids) item["finding_run_count_7d"] = len(recent_run_ids) item["symptom_codes"] = symptoms_by_item.get(item["id"], []) item["treatment_count"] = len(treatments) if include_records: records = records_by_item.get(item["id"], []) item["record_count"] = len(records) item["latest_record"] = records[0] if records else None policy = policies_by_cluster[item["cluster_id"]] policies_by_item[item["id"]] = policy item["current_posture"] = catalog_current_posture( conn, item, registration=registration, findings=findings, treatments=treatments, catalog_events=events, review_policy=policy, review_focus_anchor=focus_anchor, ) item["active_treatment_count"] = item["current_posture"][ "active_treatment_count" ] item["is_reappeared"] = "reappeared" in item["current_posture"]["reasons"] return items, policies_by_item def filter_catalog_projections( items: list[dict[str, Any]], params: dict[str, list[str]] ) -> list[dict[str, Any]]: posture_states = set(param_values(params, "posture")) risk_levels = set(param_values(params, "risk")) attention_levels = set(param_values(params, "attention")) queue = params.get("queue", [""])[0].strip().lower() reappeared = params.get("reappeared", [""])[0].lower() result = [] for item in items: posture = item["current_posture"] review_priority = posture.get("review_priority") or {} priority_tier = review_priority.get("tier") needs_review = posture["state"] == "needs_review" if queue == "review" and not needs_review: continue if queue == "recommended" and priority_tier not in {"p0", "p1"}: continue if queue in REVIEW_PRIORITY_TIERS and priority_tier != queue: continue if ( queue == "current_critical" and ( not needs_review or posture.get("risk") != "critical" or posture["active_treatment_count"] ) ): continue if ( queue == "critical_history" and ( not needs_review or posture.get("risk") == "critical" or posture.get("unreviewed_peak_risk") != "critical" or posture["active_treatment_count"] ) ): continue if ( queue == "recurring_high" and ( not needs_review or posture.get("risk") != "high" or int(item.get("finding_run_count") or 0) < 5 ) ): continue if ( queue == "one_off" and ( not needs_review or int(item.get("finding_run_count") or 0) > 1 ) ): continue if posture_states and posture["state"] not in posture_states: continue if risk_levels and (posture.get("risk") or "none") not in risk_levels: continue if attention_levels and posture["attention"] not in attention_levels: continue if reappeared in {"1", "true", "yes"} and not item["is_reappeared"]: continue if reappeared in {"0", "false", "no"} and item["is_reappeared"]: continue result.append(item) if queue == "recommended": return select_recommended_review_batch(result) return result def catalog_operational_sort_key(item: dict[str, Any]) -> tuple[Any, ...]: posture = item["current_posture"] priority_rank = {"p0": 0, "p1": 1, None: 2} attention_rank = {"urgent": 0, "attention": 1, "normal": 2, "none": 3} risk_rank = { "critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4, None: 5, } latest_at = try_datetime(item.get("latest_finding_at") or item.get("created_at")) latest_rank = -latest_at.timestamp() if latest_at else 0 return ( priority_rank.get( (posture.get("review_priority") or {}).get("tier"), 3 ), attention_rank.get(posture["attention"], 4), risk_rank.get(posture.get("risk"), 5), -int(item.get("finding_run_count") or 0), latest_rank, item["id"], ) def select_recommended_review_batch( items: list[dict[str, Any]], limit: int = RECOMMENDED_REVIEW_BATCH_SIZE ) -> list[dict[str, Any]]: candidates = [ item for item in items if catalog_projection_review_eligible(item) and item["current_posture"]["state"] == "needs_review" and not item["current_posture"]["active_treatment_count"] ] p0_items = [ item for item in candidates if item["current_posture"]["review_priority"]["tier"] == "p0" ] p1_items = [ item for item in candidates if item["current_posture"]["review_priority"]["tier"] == "p1" ] p0_items.sort(key=catalog_operational_sort_key) p1_items.sort(key=catalog_operational_sort_key) def fair_take( candidates: list[dict[str, Any]], count: int ) -> list[dict[str, Any]]: by_cluster: dict[str, list[dict[str, Any]]] = defaultdict(list) cluster_order: list[str] = [] for candidate in candidates: cluster_id = str(candidate["cluster_id"]) if cluster_id not in by_cluster: cluster_order.append(cluster_id) by_cluster[cluster_id].append(candidate) selected: list[dict[str, Any]] = [] while len(selected) < count and cluster_order: next_round: list[str] = [] for cluster_id in cluster_order: bucket = by_cluster[cluster_id] if bucket and len(selected) < count: selected.append(bucket.pop(0)) if bucket: next_round.append(cluster_id) cluster_order = next_round return selected selected = fair_take(p0_items, limit) remaining_slots = max(limit - len(selected), 0) if remaining_slots: selected.extend(fair_take(p1_items, remaining_slots)) return selected def list_catalog_items(params: dict[str, list[str]]) -> dict[str, Any]: where_sql, values = catalog_filter_sql(params) limit = positive_int(params.get("limit", ["100"])[0], 100, 500) offset = positive_int(params.get("offset", ["0"])[0], 0, 1_000_000) include_stats = params.get("include_stats", [""])[0].lower() in { "1", "true", "yes", } with get_conn() as conn: rows = conn.execute( "SELECT ci.* FROM catalog_items ci" + where_sql, values, ).fetchall() projected_items, _ = project_catalog_items(conn, rows, include_records=True) stats = None if include_stats: stats_params = dict(params) stats_params.pop("queue", None) stats = catalog_stats_from_items( filter_catalog_projections(projected_items, stats_params) ) items = filter_catalog_projections(projected_items, params) items.sort(key=catalog_operational_sort_key) total = len(items) result = { "items": items[offset : offset + limit], "total": total, "limit": limit, "offset": offset, } if stats is not None: result["stats"] = stats return result def catalog_stats(params: dict[str, list[str]]) -> dict[str, Any]: where_sql, values = catalog_filter_sql(params) with get_conn() as conn: rows = conn.execute("SELECT ci.* FROM catalog_items ci" + where_sql, values).fetchall() items, _ = project_catalog_items(conn, rows) items = filter_catalog_projections(items, params) return catalog_stats_from_items(items) def catalog_stats_from_items(items: list[dict[str, Any]]) -> dict[str, Any]: posture_counts: dict[str, int] = {state: 0 for state in CATALOG_POSTURE_STATES} attention_counts: dict[str, int] = {level: 0 for level in CATALOG_ATTENTION_LEVELS} for item in items: posture = item["current_posture"] posture_counts[posture["state"]] += 1 attention_counts[posture["attention"]] += 1 decision_items = [ item for item in items if catalog_projection_review_eligible(item) and item["current_posture"]["state"] == "needs_review" and not item["current_posture"]["active_treatment_count"] ] recommended_batch = select_recommended_review_batch(decision_items) priority_counts = { tier: sum( 1 for item in decision_items if item["current_posture"]["review_priority"]["tier"] == tier ) for tier in REVIEW_PRIORITY_TIERS } return { "total_items": len(items), "posture_counts": posture_counts, "attention_counts": attention_counts, "risk_counts": { severity: sum( 1 for item in items if item["current_posture"].get("risk") == severity ) for severity in SEVERITY_RANK }, "decision_required_count": len(decision_items), "recommended_review_count": len(recommended_batch), "review_priority_counts": priority_counts, "active_treatment_items": sum(1 for item in items if item["active_treatment_count"]), "reappeared_count": sum(1 for item in items if item["is_reappeared"]), "critical_without_active_treatment_count": sum( 1 for item in items if item["current_posture"].get("risk") == "critical" and not item["active_treatment_count"] ), "critical_history_without_active_treatment_count": sum( 1 for item in items if item["current_posture"].get("risk") != "critical" and item["current_posture"].get("unreviewed_peak_risk") == "critical" and not item["active_treatment_count"] ), "recurring_high_count": sum( 1 for item in items if item["current_posture"].get("risk") == "high" and int(item.get("finding_run_count") or 0) >= 5 ), "one_off_count": sum( 1 for item in items if int(item.get("finding_run_count") or 0) <= 1 ), "unowned_count": sum( 1 for item in items if "unowned" in item["current_posture"].get("reasons", []) ), "recurring_7d_count": sum(1 for item in items if item["finding_count_7d"] >= 2), "finding_count_7d": sum(item["finding_count_7d"] for item in items), "non_tunable_statement_count": sum( 1 for item in items if not catalog_projection_review_eligible(item) ), } def summarize_metrics(findings: list[dict[str, Any]]) -> dict[str, Any]: numeric_metrics: dict[str, list[float]] = {} ordered_findings = sorted( findings, key=lambda finding: ( try_datetime( finding.get("observed_at") or finding.get("reported_at") or finding.get("created_at") ) or datetime.min.replace(tzinfo=timezone.utc), finding.get("id") or "", ), ) for finding in ordered_findings: for key, value in finding.get("metrics", {}).items(): if isinstance(value, (int, float)) and not isinstance(value, bool): numeric_metrics.setdefault(key, []).append(float(value)) summary: dict[str, Any] = {"finding_count": len(findings)} for key, values in numeric_metrics.items(): aggregate = aggregate_metric_values(key, values) if aggregate is not None: summary[key] = aggregate return summary def catalog_metric_windows(findings: list[dict[str, Any]]) -> dict[str, dict[str, Any]]: windows: dict[str, dict[str, Any]] = {} for label, days in [("24h", 1), ("7d", 7), ("30d", 30)]: threshold = since_iso(days) windows[label] = summarize_metrics( [ finding for finding in findings if (finding.get("observed_at") or finding.get("created_at") or "") >= threshold ] ) windows["all"] = summarize_metrics(findings) return windows def catalog_item_detail( item_id: str, locale: str = "en" ) -> tuple[int, dict[str, Any]]: with get_conn() as conn: item = get_catalog_item(conn, item_id) if not item: return 404, {"error": "catalog_item_not_found"} finding_rows = conn.execute( "SELECT * FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL " "ORDER BY COALESCE(reported_at, created_at) DESC, created_at DESC", (item_id,), ).fetchall() findings = rows_to_findings(conn, finding_rows) sequence_sql = timeline_sequence_sql(conn) timeline_events = [ row_to_timeline(row, locale) for row in conn.execute( f""" SELECT {sequence_sql} AS sequence, timeline_events.* FROM timeline_events WHERE target_type = 'catalog_item' AND target_id = ? ORDER BY created_at DESC, {sequence_sql} DESC """, (item_id,), ).fetchall() ] records = [ row_to_record(row) for row in conn.execute( """ SELECT DISTINCT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' WHERE (r.to_type = 'catalog_item' AND r.to_id = ?) OR (r.to_type = 'treatment' AND r.to_id IN ( SELECT t.id FROM treatments t JOIN relations treatment_relation ON treatment_relation.from_type = 'treatment' AND treatment_relation.from_id = t.id AND treatment_relation.relation_type = 'treatment_for' AND treatment_relation.to_type = 'catalog_item' AND treatment_relation.to_id = ? )) ORDER BY rec.updated_at DESC """, (item_id, item_id), ).fetchall() ] treatments = [ row_to_treatment(row) for row in conn.execute( """ SELECT t.* FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? ORDER BY t.updated_at DESC """, (item_id,), ).fetchall() ] timeline, timeline_meta = project_catalog_timeline( timeline_events, findings, records, treatments, item, locale, ) item = enrich_catalog_item(conn, item) return 200, { "item": item, "findings": findings, "records": records, "treatments": treatments, "timeline": timeline, "timeline_meta": timeline_meta, "metric_windows": catalog_metric_windows(findings), "metric_history": project_catalog_metric_history( findings, { code: translate( f"domain:symptom.{code}.name", locale, default=name ) for code, name in SYMPTOM_NAMES.items() }, ), } def update_catalog_item(item_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: allowed = ["owner", "priority"] updates = {key: payload[key] for key in allowed if key in payload} if "labels" in payload: updates["labels_json"] = json_dumps(ensure_list(payload["labels"])) if not updates: return 400, {"error": "no_fields_to_update"} with get_conn() as conn: before = get_catalog_item(conn, item_id) if not before: return 404, {"error": "catalog_item_not_found"} timestamp = now_iso() updates["updated_at"] = timestamp assignments = ", ".join(f"{key} = ?" for key in updates) conn.execute( f"UPDATE catalog_items SET {assignments} WHERE id = ?", [*updates.values(), item_id], ) after = get_catalog_item(conn, item_id) add_timeline( conn, "catalog_item_updated", "catalog_item", item_id, "Catalog item updated", {"before": before, "after": after}, payload.get("actor") or current_actor(), timestamp, ) return 200, {"item": after} def triage_catalog_item(item_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: action = payload.get("action") allowed_actions = {"watch", "no_action", "archive"} if action not in allowed_actions: return 400, { "error": "invalid_triage_action", "allowed": sorted(allowed_actions), } actor = payload.get("actor") or current_actor() record_id = payload.get("record_id") reviewed_through_at = str(payload.get("reviewed_through_at") or "").strip() or None reviewed_through_time = try_datetime(reviewed_through_at) if reviewed_through_at and not reviewed_through_time: return 400, { "error": "invalid_reviewed_through_at", "message": "reviewed_through_at must be an ISO-8601 timestamp.", } with get_conn() as conn: item = get_catalog_item(conn, item_id) if not item: return 404, {"error": "catalog_item_not_found"} record: dict[str, Any] | None = None governance_memory: dict[str, Any] | None = None reviewed_findings: list[dict[str, Any]] = [] active_treatments = conn.execute( """ SELECT COUNT(*) FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ? WHERE t.state = 'active' """, (item_id,), ).fetchone()[0] if active_treatments: return 409, { "error": "active_treatment_exists", "message": "Complete, cancel, or unlink active Treatments before applying this disposition.", } if action in {"watch", "no_action", "archive"}: if not isinstance(record_id, str) or not record_is_linked( conn, record_id, "catalog_item", item_id ): return 409, { "error": "triage_record_required", "message": "A related triage or no-action Record is required.", } record = get_record(conn, record_id) allowed_types = ( {"no_action_record"} if action in {"no_action", "archive"} else {"triage_record", "no_action_record"} ) if not record or record["record_type"] not in allowed_types: return 409, { "error": "invalid_triage_record", "message": f"This action requires one of: {', '.join(sorted(allowed_types))}.", } if record["review_status"] not in {"ready", "reviewed"}: return 409, { "error": "triage_record_not_ready", "message": "The related Record must be ready or reviewed before applying this disposition.", } if action in {"watch", "no_action"}: finding_rows = conn.execute( """ SELECT *, COALESCE(reported_at, created_at) AS event_at FROM findings WHERE catalog_item_id = ? AND deleted_at IS NULL ORDER BY COALESCE(reported_at, created_at), created_at, id """, (item_id,), ).fetchall() reviewed_findings = rows_to_findings(conn, finding_rows) if reviewed_through_time: reviewed_findings = [ finding for finding in reviewed_findings if (finding_time := try_datetime(finding.get("event_at"))) and finding_time <= reviewed_through_time ] try: governance_memory = build_catalog_governance_memory( reviewed_findings, record or {} ) except ValueError as exc: return 409, { "error": "invalid_governance_memory", "message": str(exc), } timestamp = now_iso() if action == "archive": conn.execute( """ UPDATE catalog_items SET archived_at = ?, reappeared_at = NULL, updated_at = ? WHERE id = ? """, (timestamp, timestamp, item_id), ) add_timeline( conn, "catalog_item_archived", "catalog_item", item_id, "Catalog item archived", {"record_id": record_id}, actor, timestamp, ) else: latest_finding = reviewed_findings[-1] if reviewed_findings else None conn.execute( """ UPDATE catalog_items SET reappeared_at = NULL, updated_at = ? WHERE id = ? """, (timestamp, item_id), ) add_timeline( conn, "catalog_decision_recorded", "catalog_item", item_id, f"Catalog decision recorded: {action}", { "action": action, "record_id": record_id, "reviewed_through_finding_id": latest_finding.get("id") if latest_finding else None, "reviewed_through_finding_at": ( latest_finding.get("event_at") if latest_finding else reviewed_through_at ), "owner": item.get("owner"), "governance_memory": governance_memory, }, actor, timestamp, ) return 200, {"item": enrich_catalog_item(conn, get_catalog_item(conn, item_id))} def decide_catalog_item( item_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: """Record and apply a human disposition as one product action.""" try: reject_unknown_fields( payload, frozenset( {"action", "conclusion_type", "rationale", "source_url", "actor"} ), "catalog decision", ) except ValueError as exc: return 400, {"error": "invalid_catalog_decision", "message": str(exc)} action = str(payload.get("action") or "").strip() if action not in {"watch", "no_action"}: return 400, { "error": "invalid_catalog_decision", "allowed": ["watch", "no_action"], } try: rationale = optional_string(payload.get("rationale"), "rationale", 10_000) source_url = optional_string(payload.get("source_url"), "source_url", 2_000) except ValueError as exc: return 400, {"error": "invalid_catalog_decision", "message": str(exc)} if not rationale: return 400, { "error": "decision_rationale_required", "message": "A concise decision rationale is required.", } if source_url: parsed_url = urlparse(source_url) if parsed_url.scheme not in {"http", "https"} or not parsed_url.netloc: return 400, { "error": "invalid_catalog_decision", "message": "source_url must be an absolute HTTP or HTTPS URL.", } conclusion_type = str(payload.get("conclusion_type") or "").strip() if action == "watch": conclusion_type = "watch" elif conclusion_type not in GOVERNANCE_MEMORY_CONCLUSIONS - {"watch"}: return 400, { "error": "invalid_conclusion_type", "allowed": sorted(GOVERNANCE_MEMORY_CONCLUSIONS - {"watch"}), } body = rationale if source_url: body += f"\n\n[Related source]({source_url})" status, created = create_record( "catalog_item", item_id, { "record_type": ( "triage_record" if action == "watch" else "no_action_record" ), "title": rationale.splitlines()[0][:240], "structured_fields": { "conclusion_type": conclusion_type, "confidence": "high", "reopen_policy": "meaningful_change", "metric_guardrails": {}, }, "body_markdown": body, "visibility": "internal", "review_status": "ready", "created_by": payload.get("actor") or current_actor(), }, ) if status != 201: return status, created record_id = created["record"]["id"] status, decision = triage_catalog_item( item_id, { "action": action, "record_id": record_id, "actor": payload.get("actor") or current_actor(), }, ) if status != 200: return status, decision return 200, {"item": decision["item"], "record": created["record"]} def create_record( target_type: str, target_id: str, payload: dict[str, Any], ) -> tuple[int, dict[str, Any]]: record_type = payload.get("record_type") or "triage_record" if record_type not in RECORD_TYPES: return 400, {"error": "invalid_record_type", "allowed": sorted(RECORD_TYPES)} try: title = optional_string(payload.get("title"), "title", 240) or record_type.replace( "_", " " ).title() body_markdown = optional_string( payload.get("body_markdown") or payload.get("body"), "body_markdown", 500_000, ) or "" except ValueError as exc: return 400, {"error": "invalid_record", "message": str(exc)} structured_fields = payload.get("structured_fields") or {} if not isinstance(structured_fields, dict): return 400, {"error": "invalid_structured_fields"} visibility = payload.get("visibility") or "internal" review_status = payload.get("review_status") or "draft" if visibility not in RECORD_VISIBILITIES: return 400, {"error": "invalid_visibility"} if review_status not in RECORD_STATES: return 400, {"error": "invalid_record_state"} if visibility == "customer_visible" and review_status != "reviewed": return 409, { "error": "review_required", "message": "Customer-visible Records must be reviewed.", } content_error = record_content_error( record_type, structured_fields, body_markdown, visibility, review_status, ) if content_error: return 400, content_error timestamp = now_iso() record_id = new_id("rec") targets = [(target_type, target_id)] additional_targets = payload.get("additional_targets") or [] if not isinstance(additional_targets, list) or len(additional_targets) > 10: return 400, {"error": "invalid_additional_targets"} for target in additional_targets: if not isinstance(target, dict) or not isinstance(target.get("type"), str) or not isinstance(target.get("id"), str): return 400, {"error": "invalid_additional_targets"} pair = (target["type"], target["id"]) if pair not in targets: targets.append(pair) with get_conn() as conn: if any(not target_exists(conn, kind, identifier) for kind, identifier in targets): return 404, {"error": "record_target_not_found"} conn.execute( """ INSERT INTO records (id, record_type, title, structured_fields_json, body_markdown, visibility, review_status, created_by, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( record_id, record_type, title, json_dumps(structured_fields), body_markdown, visibility, review_status, payload.get("created_by") or current_actor(), timestamp, timestamp, ), ) for kind, identifier in targets: add_relation(conn, "record", record_id, "record_of", kind, identifier) add_timeline( conn, "record_created", kind, identifier, f"Record created: {title}", {"record_id": record_id, "record_type": record_type}, payload.get("created_by") or current_actor(), timestamp, ) created_record = get_record(conn, record_id) for kind, identifier in targets: if kind != "treatment": continue if created_record: record_recommendation_shared( conn, identifier, created_record, actor=payload.get("created_by") or current_actor(), occurred_at=timestamp, ) for item_id in linked_catalog_item_ids(conn, identifier): add_timeline( conn, "treatment_record_created", "catalog_item", item_id, f"Treatment Record created: {title}", { "record_id": record_id, "record_type": record_type, "treatment_id": identifier, }, payload.get("created_by") or current_actor(), timestamp, ) return 201, {"record": get_record(conn, record_id), "targets": record_targets(conn, record_id)} def record_detail(record_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: record = get_record(conn, record_id) if not record: return 404, {"error": "record_not_found"} return 200, {"record": record, "targets": record_targets(conn, record_id)} def update_record(record_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: allowed = { "title", "structured_fields", "body_markdown", "visibility", "review_status", } if not any(key in payload for key in allowed): return 400, {"error": "no_fields_to_update"} try: title = optional_string(payload.get("title"), "title", 240) if "title" in payload else None body = ( optional_string(payload.get("body_markdown"), "body_markdown", 500_000) if "body_markdown" in payload else None ) except ValueError as exc: return 400, {"error": "invalid_record", "message": str(exc)} with get_conn() as conn: before = get_record(conn, record_id) if not before: return 404, {"error": "record_not_found"} updates: dict[str, Any] = {} if "title" in payload: updates["title"] = title or before["title"] if "body_markdown" in payload: updates["body_markdown"] = body or "" if "structured_fields" in payload: if not isinstance(payload["structured_fields"], dict): return 400, {"error": "invalid_structured_fields"} updates["structured_fields_json"] = json_dumps(payload["structured_fields"]) if "visibility" in payload: if payload["visibility"] not in RECORD_VISIBILITIES: return 400, {"error": "invalid_visibility"} updates["visibility"] = payload["visibility"] if "review_status" in payload: if payload["review_status"] not in RECORD_STATES: return 400, {"error": "invalid_record_state"} updates["review_status"] = payload["review_status"] visibility = updates.get("visibility", before["visibility"]) state = updates.get("review_status", before["review_status"]) if visibility == "customer_visible" and state != "reviewed": return 409, { "error": "review_required", "message": "Customer-visible Records must be reviewed.", } structured_fields = ( payload["structured_fields"] if "structured_fields" in payload else before["structured_fields"] ) content_error = record_content_error( before["record_type"], structured_fields, updates.get("body_markdown", before["body_markdown"]), visibility, state, ) if content_error: return 400, content_error timestamp = now_iso() updates["updated_at"] = timestamp assignments = ", ".join(f"{key} = ?" for key in updates) conn.execute( f"UPDATE records SET {assignments} WHERE id = ?", [*updates.values(), record_id], ) after = get_record(conn, record_id) for target in record_targets(conn, record_id): add_timeline( conn, "record_updated", target["type"], target["id"], f"Record updated: {after['title']}", {"record_id": record_id, "before": before, "after": after}, payload.get("actor") or payload.get("created_by") or current_actor(), timestamp, ) if target["type"] == "treatment" and not is_shared_recommendation(before) and after: record_recommendation_shared( conn, target["id"], after, actor=payload.get("actor") or payload.get("created_by") or current_actor(), occurred_at=timestamp, ) return 200, {"record": after, "targets": record_targets(conn, record_id)} def create_treatment(payload: dict[str, Any], catalog_item_id: str | None = None) -> tuple[int, dict[str, Any]]: item_ids = ensure_list(payload.get("catalog_item_ids")) if catalog_item_id: item_ids.append(catalog_item_id) item_ids = list(dict.fromkeys(str(value) for value in item_ids if value)) if not item_ids: return 400, { "error": "catalog_item_required", "message": "A Treatment must be linked to at least one Catalog Item.", } if len(item_ids) > 50: return 400, {"error": "too_many_catalog_items"} timestamp = now_iso() actor = payload.get("created_by") or current_actor() with get_conn() as conn: linked_items = [get_catalog_item(conn, item_id) for item_id in item_ids] if any(item is None for item in linked_items): return 404, {"error": "catalog_item_not_found"} ineligible_items = [ item for item in linked_items if item and not catalog_governance_relevance(item)["review_eligible"] ] if ineligible_items: return 409, { "error": "catalog_item_not_review_eligible", "catalog_item_ids": [item["id"] for item in ineligible_items], "governance_relevance": [ catalog_governance_relevance(item) for item in ineligible_items ], } first_item = linked_items[0] or {} try: title = optional_string(payload.get("title"), "title", 240) or ( f"Treat {first_item['sql_digest'][:12]}" ) objective = require_string(payload, "objective", max_length=2000) success_criteria = require_string( payload, "success_criteria", max_length=4000 ) owner = optional_string(payload.get("owner"), "owner", 128) assignee = optional_string(payload.get("assignee"), "assignee", 128) except ValueError as exc: return 400, {"error": "invalid_treatment", "message": str(exc)} first_posture = catalog_current_posture(conn, first_item) severity = ( payload.get("severity") or first_posture.get("risk") or first_posture.get("last_known_risk") or "medium" ) if severity not in SEVERITIES: return 400, {"error": "invalid_severity"} requested_findings = ensure_list(payload.get("finding_ids")) if requested_findings: finding_ids = list(dict.fromkeys(str(value) for value in requested_findings if value)) placeholders = ",".join("?" for _ in finding_ids) rows = conn.execute( f"SELECT id, catalog_item_id FROM findings WHERE deleted_at IS NULL AND id IN ({placeholders})", finding_ids, ).fetchall() if len(rows) != len(finding_ids) or any(row["catalog_item_id"] not in item_ids for row in rows): return 400, {"error": "invalid_finding_selection"} else: placeholders = ",".join("?" for _ in item_ids) rows = conn.execute( f"SELECT id, catalog_item_id FROM findings WHERE deleted_at IS NULL AND catalog_item_id IN ({placeholders})", item_ids, ).fetchall() finding_ids = [row["id"] for row in rows] treatment_id = new_id("trt") conn.execute( """ INSERT INTO treatments (id, treatment_no, title, objective, success_criteria, state, stage, outcome, outcome_record_id, superseded_by_treatment_id, owner, assignee, priority, severity, labels_json, observation_started_at, observation_due_at, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( treatment_id, next_treatment_no(conn), title, objective, success_criteria, "active", "assessment", None, None, None, owner, assignee, payload.get("priority") or "normal", severity, json_dumps(ensure_list(payload.get("labels"))), None, None, timestamp, timestamp, None, ), ) for item_id in item_ids: add_relation(conn, "treatment", treatment_id, "treatment_for", "catalog_item", item_id) conn.execute( "UPDATE catalog_items SET reappeared_at = NULL WHERE id = ?", (item_id,), ) for finding_id in finding_ids: add_relation(conn, "finding", finding_id, "evidence_of", "treatment", treatment_id) for item_id in item_ids: add_timeline( conn, "treatment_created", "catalog_item", item_id, f"Treatment started: {title}", {"treatment_id": treatment_id, "linked_finding_count": len(finding_ids)}, actor, timestamp, ) add_timeline( conn, "treatment_created", "treatment", treatment_id, f"Treatment started: {title}", { "catalog_item_ids": item_ids, "finding_ids": finding_ids, "objective": objective, "success_criteria": success_criteria, }, actor, timestamp, ) treatment = get_treatment(conn, treatment_id) return 201, {"treatment": treatment, "linked_finding_count": len(finding_ids)} def treatment_filter_sql(params: dict[str, list[str]]) -> tuple[str, list[Any]]: where: list[str] = [] values: list[Any] = [] for key in ["state", "stage", "owner", "assignee", "priority", "severity", "outcome"]: selected = param_values(params, key) if selected: placeholders = ",".join("?" for _ in selected) where.append(f"t.{key} IN ({placeholders})") values.extend(selected) query = params.get("q", [""])[0].strip() if query: where.append("(t.treatment_no LIKE ? OR t.title LIKE ? OR t.objective LIKE ?)") values.extend([f"%{query}%", f"%{query}%", f"%{query}%"]) if params.get("observation_due", [""])[0]: expected = params["observation_due"][0].lower() in {"1", "true", "yes"} condition = ( "t.state = 'active' AND t.stage = 'observation' " "AND t.observation_due_at IS NOT NULL AND t.observation_due_at <= ?" ) where.append(("" if expected else "NOT (") + condition + ("" if expected else ")")) values.append(now_iso()) queue = params.get("queue", [""])[0].strip().lower() if queue == "follow_up": where.append( "(t.state = 'active' AND (t.stage = 'alignment' OR " "(t.stage = 'observation' AND t.observation_due_at IS NOT NULL " "AND t.observation_due_at <= ?)))" ) values.append(now_iso()) elif queue == "recent_outcomes": where.append("t.state IN ('completed', 'cancelled')") scope_conditions: list[str] = [] scope_values: list[Any] = [] for key in ["org_id", "cluster_id"]: selected = param_values(params, key) if selected: placeholders = ",".join("?" for _ in selected) scope_conditions.append(f"ci.{key} IN ({placeholders})") scope_values.extend(selected) if scope_conditions: where.append( "EXISTS (SELECT 1 FROM relations r JOIN catalog_items ci ON ci.id = r.to_id " "WHERE r.from_type = 'treatment' AND r.from_id = t.id " "AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' " f"AND {' AND '.join(scope_conditions)})" ) values.extend(scope_values) return (" WHERE " + " AND ".join(where)) if where else "", values def treatment_catalog_summaries( conn: sqlite3.Connection, treatment_id: str ) -> list[dict[str, Any]]: rows = conn.execute( """ SELECT ci.* FROM catalog_items ci JOIN relations r ON r.from_type = 'treatment' AND r.from_id = ? AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ci.id """, (treatment_id,), ).fetchall() items = [] for row in rows: item = row_to_catalog_item(row) posture = catalog_current_posture(conn, item) items.append( { "id": item["id"], "org_id": item["org_id"], "cluster_id": item["cluster_id"], "sql_digest": item["sql_digest"], "normalized_sql": item.get("normalized_sql"), "org_id": item["org_id"], "cluster_id": item["cluster_id"], "lifecycle": item["lifecycle"], "current_posture": posture, } ) items.sort( key=lambda item: ( -SEVERITY_RANK.get(item["current_posture"].get("risk") or "info", 0), item["sql_digest"], ) ) return items def treatment_stage_entered_at( conn: sqlite3.Connection, treatment: dict[str, Any] ) -> str | None: stage = treatment["stage"] sequence_sql = timeline_sequence_sql(conn) rows = conn.execute( f""" SELECT * FROM timeline_events WHERE target_type = 'treatment' AND target_id = ? ORDER BY created_at DESC, {sequence_sql} DESC """, (treatment["id"],), ).fetchall() for row in rows: event = row_to_timeline(row) event_type = event["event_type"] payload = event["payload"] if stage == "completed" and event_type in {"treatment_completed", "treatment_cancelled"}: return event["created_at"] if stage == "observation" and event_type == "observation_started": return event["created_at"] if event_type == "treatment_stage_changed" and payload.get("to") == stage: return event["created_at"] if event_type == "treatment_reopened" and payload.get("stage") == stage: return event["created_at"] if stage == "assessment" and event_type == "treatment_created": return event["created_at"] if stage == "observation": return treatment.get("observation_started_at") or treatment.get("created_at") if stage == "completed": return treatment.get("completed_at") or treatment.get("updated_at") return treatment.get("created_at") def enrich_treatment(conn: sqlite3.Connection, treatment: dict[str, Any]) -> dict[str, Any]: catalog_items = treatment_catalog_summaries(conn, treatment["id"]) treatment["catalog_items"] = catalog_items treatment["linked_sql_count"] = len(catalog_items) treatment["linked_finding_count"] = conn.execute( """ SELECT COUNT(*) FROM relations WHERE from_type = 'finding' AND relation_type = 'evidence_of' AND to_type = 'treatment' AND to_id = ? """, (treatment["id"],), ).fetchone()[0] treatment["org_ids"] = list(dict.fromkeys(item["org_id"] for item in catalog_items)) treatment["cluster_ids"] = list(dict.fromkeys(item["cluster_id"] for item in catalog_items)) latest_record = conn.execute( """ SELECT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.to_type = 'treatment' AND r.to_id = ? ORDER BY rec.updated_at DESC LIMIT 1 """, (treatment["id"],), ).fetchone() treatment["latest_record"] = row_to_record(latest_record) if latest_record else None treatment["record_count"] = conn.execute( """ SELECT COUNT(DISTINCT rec.id) FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' AND r.to_type = 'treatment' AND r.to_id = ? """, (treatment["id"],), ).fetchone()[0] treatment["is_observation_due"] = bool( treatment["state"] == "active" and treatment["stage"] == "observation" and treatment.get("observation_due_at") and treatment["observation_due_at"] <= now_iso() ) treatment["cycle_time_hours"] = duration_hours( treatment.get("created_at"), treatment.get("completed_at") if treatment["state"] != "active" else None, ) treatment["stage_entered_at"] = treatment_stage_entered_at(conn, treatment) treatment["stage_age_hours"] = duration_hours(treatment["stage_entered_at"]) return treatment def list_treatments(params: dict[str, list[str]]) -> dict[str, Any]: where_sql, values = treatment_filter_sql(params) limit = positive_int(params.get("limit", ["100"])[0], 100, 500) offset = positive_int(params.get("offset", ["0"])[0], 0, 1_000_000) base = " FROM treatments t" with get_conn() as conn: total = conn.execute("SELECT COUNT(*)" + base + where_sql, values).fetchone()[0] rows = conn.execute( "SELECT t.*" + base + where_sql + " ORDER BY CASE WHEN t.state = 'active' THEN 0 ELSE 1 END, " "CASE WHEN t.state = 'active' AND t.stage = 'observation' " "AND t.observation_due_at IS NOT NULL AND t.observation_due_at <= ? THEN 0 ELSE 1 END, " "t.updated_at DESC LIMIT ? OFFSET ?", [*values, now_iso(), limit, offset], ).fetchall() treatments = [enrich_treatment(conn, row_to_treatment(row)) for row in rows] return {"items": treatments, "total": total, "limit": limit, "offset": offset} def previous_calendar_month_start(value: datetime, timezone_offset: int) -> datetime: local_value = value + timedelta(minutes=timezone_offset) if local_value.month == 1: previous_local = datetime(local_value.year - 1, 12, 1, tzinfo=timezone.utc) else: previous_local = datetime(local_value.year, local_value.month - 1, 1, tzinfo=timezone.utc) return previous_local - timedelta(minutes=timezone_offset) def is_calendar_month_range(start: datetime, end: datetime, timezone_offset: int) -> bool: local_start = start + timedelta(minutes=timezone_offset) local_end = end + timedelta(minutes=timezone_offset) if any( ( local_start.day != 1, local_end.day != 1, local_start.hour != 0, local_start.minute != 0, local_start.second != 0, local_end.hour != 0, local_end.minute != 0, local_end.second != 0, ) ): return False expected_year = local_start.year + (1 if local_start.month == 12 else 0) expected_month = 1 if local_start.month == 12 else local_start.month + 1 return local_end.year == expected_year and local_end.month == expected_month def treatment_reporting_bounds( params: dict[str, list[str]], timezone_offset: int ) -> tuple[datetime, datetime, datetime, datetime, str]: now = datetime.now(timezone.utc) requested_end = try_datetime(params.get("to", [""])[0]) or now period_end = min(requested_end, now) period_start = try_datetime(params.get("from", [""])[0]) or period_end - timedelta(days=7) if period_start >= period_end: period_start = period_end - timedelta(days=7) custom_start = try_datetime(params.get("compare_from", [""])[0]) custom_end = try_datetime(params.get("compare_to", [""])[0]) if custom_start and custom_end: custom_end = min(custom_end, now) if custom_start < custom_end: return period_start, period_end, custom_start, custom_end, "custom" if is_calendar_month_range(period_start, requested_end, timezone_offset): comparison_start = previous_calendar_month_start(period_start, timezone_offset) if requested_end > now: comparison_end = min(period_start, comparison_start + (period_end - period_start)) else: comparison_end = period_start return period_start, period_end, comparison_start, comparison_end, "previous_calendar" duration = period_end - period_start return period_start, period_end, period_start - duration, period_start, "previous_equal" def empty_treatment_bucket(bucket: str) -> dict[str, Any]: return { "bucket": bucket, "new_treatments": 0, "reopened_treatments": 0, "recommendations_shared": 0, "completed_treatments": 0, "cancelled_treatments": 0, "closed_treatments": 0, "backlog": 0, } def treatment_event_state_change(event_type: str) -> int: if event_type in {"treatment_created", "treatment_reopened"}: return 1 if event_type in {"treatment_completed", "treatment_cancelled"}: return -1 return 0 def treatment_event_sort_key( value: tuple[datetime, int, dict[str, Any]] ) -> tuple[datetime, int]: timestamp, input_index, event = value sequence = event.get("event_sequence") return timestamp, sequence if isinstance(sequence, int) else input_index def treatment_period_aggregate( events: list[dict[str, Any]], *, period_start: datetime, period_end: datetime, timezone_offset: int, ) -> dict[str, Any]: bucket_cursor = day_bucket_start(period_start, timezone_offset) buckets: dict[str, dict[str, Any]] = {} while bucket_cursor < period_end: key = iso_datetime(bucket_cursor) buckets[key] = empty_treatment_bucket(key) bucket_cursor += timedelta(seconds=DAY_BUCKET_SECONDS) parsed_events = sorted( ( (timestamp, input_index, event) for input_index, event in enumerate(events) if (timestamp := try_datetime(event.get("created_at"))) is not None ), key=treatment_event_sort_key, ) active_ids: set[str] = set() for timestamp, _, event in parsed_events: if timestamp >= period_start: break delta = treatment_event_state_change(event["event_type"]) if delta > 0: active_ids.add(event["target_id"]) elif delta < 0: active_ids.discard(event["target_id"]) backlog_start = len(active_ids) created_at_by_treatment: dict[str, datetime] = {} for timestamp, _, event in parsed_events: if event["event_type"] == "treatment_created": created_at_by_treatment.setdefault(event["target_id"], timestamp) successful_ids: dict[str, dict[str, Any]] = {} completion_cycle_hours: list[float] = [] closed_outcome_counts: dict[str, int] = defaultdict(int) for timestamp, _, event in parsed_events: if timestamp < period_start or timestamp >= period_end: continue key = iso_datetime(day_bucket_start(timestamp, timezone_offset)) entry = buckets.setdefault(key, empty_treatment_bucket(key)) event_type = event["event_type"] if event_type == "treatment_created": entry["new_treatments"] += 1 elif event_type == "treatment_reopened": entry["reopened_treatments"] += 1 elif event_type == "recommendation_shared": entry["recommendations_shared"] += 1 elif event_type == "treatment_completed": entry["completed_treatments"] += 1 entry["closed_treatments"] += 1 outcome = event["payload"].get("outcome") or "unknown" closed_outcome_counts[outcome] += 1 created_at = created_at_by_treatment.get(event["target_id"]) if created_at and timestamp >= created_at: completion_cycle_hours.append((timestamp - created_at).total_seconds() / 3600) if outcome in {"fixed", "improved"}: successful_ids[event["target_id"]] = event elif event_type == "treatment_cancelled": entry["cancelled_treatments"] += 1 entry["closed_treatments"] += 1 closed_outcome_counts[event["payload"].get("outcome") or "cancelled"] += 1 active_ids.clear() event_index = 0 for key in sorted(buckets): bucket_start = try_datetime(key) or period_start cutoff = min(bucket_start + timedelta(seconds=DAY_BUCKET_SECONDS), period_end) while event_index < len(parsed_events) and parsed_events[event_index][0] < cutoff: _, _, event = parsed_events[event_index] delta = treatment_event_state_change(event["event_type"]) if delta > 0: active_ids.add(event["target_id"]) elif delta < 0: active_ids.discard(event["target_id"]) event_index += 1 buckets[key]["backlog"] = len(active_ids) time_series = [buckets[key] for key in sorted(buckets)] summary = { "new_treatments": sum(item["new_treatments"] for item in time_series), "reopened_treatments": sum(item["reopened_treatments"] for item in time_series), "recommendations_shared": sum(item["recommendations_shared"] for item in time_series), "completed_treatments": sum(item["completed_treatments"] for item in time_series), "cancelled_treatments": sum(item["cancelled_treatments"] for item in time_series), "closed_treatments": sum(item["closed_treatments"] for item in time_series), "successful_treatments": len(successful_ids), "backlog_start": backlog_start, "backlog_end": time_series[-1]["backlog"] if time_series else backlog_start, "net_backlog_change": (time_series[-1]["backlog"] if time_series else backlog_start) - backlog_start, "median_completion_time_hours": round(median(completion_cycle_hours), 1) if completion_cycle_hours else None, } return { "summary": summary, "time_series": time_series, "successful_events": successful_ids, "closed_outcome_counts": dict(closed_outcome_counts), } def treatment_stage_flow( events: list[dict[str, Any]], period_start: datetime, period_end: datetime ) -> dict[str, dict[str, Any]]: entries: dict[str, int] = defaultdict(int) exits: dict[str, int] = defaultdict(int) exit_durations: dict[str, list[float]] = defaultdict(list) current_stage: dict[str, str] = {} entered_at: dict[str, datetime] = {} parsed_events = sorted( ( (timestamp, input_index, event) for input_index, event in enumerate(events) if (timestamp := try_datetime(event.get("created_at"))) is not None and timestamp < period_end ), key=treatment_event_sort_key, ) def enter(treatment_id: str, stage: str, timestamp: datetime) -> None: current_stage[treatment_id] = stage entered_at[treatment_id] = timestamp if period_start <= timestamp < period_end: entries[stage] += 1 def leave(treatment_id: str, timestamp: datetime) -> None: stage = current_stage.get(treatment_id) if not stage or stage == "completed": return if period_start <= timestamp < period_end: exits[stage] += 1 started_at = entered_at.get(treatment_id) if started_at and timestamp >= started_at: exit_durations[stage].append((timestamp - started_at).total_seconds() / 3600) current_stage.pop(treatment_id, None) entered_at.pop(treatment_id, None) for timestamp, _, event in parsed_events: treatment_id = event["target_id"] event_type = event["event_type"] payload = event["payload"] if event_type == "treatment_created": enter(treatment_id, "assessment", timestamp) elif event_type == "treatment_reopened": enter(treatment_id, payload.get("stage") or "assessment", timestamp) elif event_type == "treatment_stage_changed": leave(treatment_id, timestamp) enter(treatment_id, payload.get("to") or "assessment", timestamp) elif event_type == "observation_started": leave(treatment_id, timestamp) enter(treatment_id, "observation", timestamp) elif event_type in {"treatment_completed", "treatment_cancelled"}: leave(treatment_id, timestamp) return { stage: { "entered_in_period_count": entries[stage], "exited_in_period_count": exits[stage], "median_exit_time_hours": round(median(exit_durations[stage]), 1) if exit_durations[stage] else None, } for stage in TREATMENT_STAGES[:-1] } def treatment_stage_health( treatments: list[dict[str, Any]], stage_flow: dict[str, dict[str, Any]] ) -> list[dict[str, Any]]: result = [] for stage in TREATMENT_STAGES[:-1]: stage_items = [ treatment for treatment in treatments if treatment["state"] == "active" and treatment["stage"] == stage ] ages = [ float(treatment["stage_age_hours"]) for treatment in stage_items if treatment.get("stage_age_hours") is not None ] result.append( { "stage": stage, "count": len(stage_items), "median_age_hours": round(median(ages), 1) if ages else None, "oldest_age_hours": round(max(ages), 1) if ages else None, "older_than_7d_count": sum(age >= 7 * 24 for age in ages), "observation_due_count": sum( 1 for treatment in stage_items if treatment["is_observation_due"] ), **stage_flow.get(stage, {}), } ) return result def treatment_active_age_distribution(treatments: list[dict[str, Any]]) -> list[dict[str, Any]]: buckets = [ ("under_1d", 0, 24), ("1_3d", 24, 3 * 24), ("3_7d", 3 * 24, 7 * 24), ("7_14d", 7 * 24, 14 * 24), ("over_14d", 14 * 24, None), ] counts = {key: 0 for key, _, _ in buckets} for treatment in treatments: if treatment["state"] != "active": continue age = treatment.get("cycle_time_hours") if not isinstance(age, (int, float)): continue for key, minimum, maximum in buckets: if age >= minimum and (maximum is None or age < maximum): counts[key] += 1 break return [{"key": key, "count": counts[key]} for key, _, _ in buckets] def treatment_started_cohort_distribution( events: list[dict[str, Any]], period_start: datetime, period_end: datetime ) -> list[dict[str, Any]]: cohort: dict[str, dict[str, str]] = {} parsed_events = sorted( ( (timestamp, input_index, event) for input_index, event in enumerate(events) if (timestamp := try_datetime(event.get("created_at"))) is not None and timestamp < period_end ), key=treatment_event_sort_key, ) for timestamp, _, event in parsed_events: treatment_id = event["target_id"] event_type = event["event_type"] payload = event["payload"] if event_type == "treatment_created" and period_start <= timestamp < period_end: cohort[treatment_id] = {"state": "active", "stage": "assessment"} continue if treatment_id not in cohort: continue if event_type == "treatment_stage_changed": cohort[treatment_id] = {"state": "active", "stage": payload.get("to") or "assessment"} elif event_type == "observation_started": cohort[treatment_id] = {"state": "active", "stage": "observation"} elif event_type == "treatment_reopened": cohort[treatment_id] = {"state": "active", "stage": payload.get("stage") or "assessment"} elif event_type == "treatment_completed": cohort[treatment_id] = {"state": "completed", "stage": "completed"} elif event_type == "treatment_cancelled": cohort[treatment_id] = {"state": "cancelled", "stage": "completed"} order = [*TREATMENT_STAGES[:-1], "completed", "cancelled"] counts = {key: 0 for key in order} for value in cohort.values(): key = value["stage"] if value["state"] == "active" else value["state"] counts[key] += 1 return [{"key": key, "count": counts[key]} for key in order] def treatment_outcome_distribution(counts: dict[str, int]) -> list[dict[str, Any]]: order = [ "fixed", "improved", "unchanged", "not_optimizable", "accepted_risk", "failed", "cancelled", "superseded", "unknown", ] return [{"key": key, "count": counts.get(key, 0)} for key in order] def treatment_stats(params: dict[str, list[str]]) -> dict[str, Any]: where_sql, values = treatment_filter_sql(params) timezone_offset = timezone_offset_minutes(params) period_start, period_end, comparison_start, comparison_end, comparison_mode = treatment_reporting_bounds( params, timezone_offset ) with get_conn() as conn: rows = conn.execute("SELECT t.* FROM treatments t" + where_sql, values).fetchall() treatments = [enrich_treatment(conn, row_to_treatment(row)) for row in rows] event_sequence_sql = timeline_sequence_sql(conn, "e") event_rows = conn.execute( f"SELECT e.*, {event_sequence_sql} AS event_sequence " "FROM timeline_events e JOIN treatments t ON t.id = e.target_id " "AND e.target_type = 'treatment'" + where_sql + f" ORDER BY e.created_at, {event_sequence_sql}", values, ).fetchall() events = [row_to_timeline(row) for row in event_rows] current = treatment_period_aggregate( events, period_start=period_start, period_end=period_end, timezone_offset=timezone_offset, ) comparison = treatment_period_aggregate( events, period_start=comparison_start, period_end=comparison_end, timezone_offset=timezone_offset, ) successful_items = [] treatment_by_id = {treatment["id"]: treatment for treatment in treatments} for treatment_id, event in sorted( current["successful_events"].items(), key=lambda item: item[1]["created_at"], reverse=True, ): treatment = treatment_by_id.get(treatment_id) if not treatment: continue successful_items.append( { "id": treatment["id"], "treatment_no": treatment["treatment_no"], "title": treatment["title"], "outcome": event["payload"].get("outcome"), "completed_at": event["created_at"], "catalog_items": treatment["catalog_items"], } ) current_snapshot = { "total_treatments": len(treatments), "active_treatments": sum(1 for treatment in treatments if treatment["state"] == "active"), "completed_treatments": sum(1 for treatment in treatments if treatment["state"] == "completed"), "cancelled_treatments": sum(1 for treatment in treatments if treatment["state"] == "cancelled"), "observation_due_treatments": sum(1 for treatment in treatments if treatment["is_observation_due"]), "unowned_active_treatments": sum( 1 for treatment in treatments if treatment["state"] == "active" and not treatment.get("owner") ), "active_older_than_7d": sum( 1 for treatment in treatments if treatment["state"] == "active" and treatment.get("stage_age_hours") is not None and treatment["stage_age_hours"] >= 7 * 24 ), } delta_keys = ( "new_treatments", "reopened_treatments", "recommendations_shared", "completed_treatments", "successful_treatments", "closed_treatments", "backlog_end", "net_backlog_change", ) deltas = { key: metric_delta(current["summary"][key], comparison["summary"][key]) for key in delta_keys } current_completion_time = current["summary"]["median_completion_time_hours"] comparison_completion_time = comparison["summary"]["median_completion_time_hours"] deltas["median_completion_time_hours"] = ( metric_delta(current_completion_time, comparison_completion_time) if current_completion_time is not None and comparison_completion_time is not None else None ) stage_flow = treatment_stage_flow(events, period_start, period_end) return { "timezone_offset_minutes": timezone_offset, "comparison_mode": comparison_mode, "period": {"from": iso_datetime(period_start), "to": iso_datetime(period_end)}, "comparison_period": { "from": iso_datetime(comparison_start), "to": iso_datetime(comparison_end), }, "summary": current["summary"], "comparison": comparison["summary"], "deltas": deltas, "time_series": current["time_series"], "current_snapshot": current_snapshot, "stage_health": treatment_stage_health(treatments, stage_flow), "distributions": { "active_age": treatment_active_age_distribution(treatments), "started_cohort": treatment_started_cohort_distribution(events, period_start, period_end), "closed_outcomes": treatment_outcome_distribution(current["closed_outcome_counts"]), }, "successful_treatments": successful_items, } def treatment_detail( treatment_id: str, locale: str = "en" ) -> tuple[int, dict[str, Any]]: with get_conn() as conn: treatment = get_treatment(conn, treatment_id) if not treatment: return 404, {"error": "treatment_not_found"} catalog_items = [ enrich_catalog_item(conn, row_to_catalog_item(row)) for row in conn.execute( """ SELECT ci.* FROM catalog_items ci JOIN relations r ON r.from_type = 'treatment' AND r.from_id = ? AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' AND r.to_id = ci.id """, (treatment_id,), ).fetchall() ] finding_rows = conn.execute( """ SELECT f.* FROM findings f JOIN relations r ON r.from_type = 'finding' AND r.from_id = f.id AND r.relation_type = 'evidence_of' AND r.to_type = 'treatment' AND r.to_id = ? ORDER BY COALESCE(f.reported_at, f.created_at) DESC, f.created_at DESC """, (treatment_id,), ).fetchall() findings = rows_to_findings(conn, finding_rows, compact=True) records = [ row_to_record(row) for row in conn.execute( """ SELECT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.to_type = 'treatment' AND r.to_id = ? ORDER BY rec.updated_at DESC """, (treatment_id,), ).fetchall() ] sequence_sql = timeline_sequence_sql(conn) timeline = [ row_to_timeline(row, locale) for row in conn.execute( f""" SELECT * FROM timeline_events WHERE target_type = 'treatment' AND target_id = ? ORDER BY created_at DESC, {sequence_sql} DESC """, (treatment_id,), ).fetchall() ] return 200, { "treatment": enrich_treatment(conn, treatment), "catalog_items": catalog_items, "findings": findings, "records": records, "timeline": timeline, } def update_treatment(treatment_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: if any( key in payload for key in [ "state", "stage", "outcome", "outcome_record_id", "superseded_by_treatment_id", "completed_at", ] ): return 409, { "error": "domain_action_required", "message": "Treatment workflow fields are changed through transition, complete, or reopen actions.", } allowed = [ "title", "objective", "success_criteria", "owner", "assignee", "priority", "severity", ] updates = {key: payload[key] for key in allowed if key in payload} if "severity" in updates and updates["severity"] not in SEVERITIES: return 400, {"error": "invalid_severity"} if "labels" in payload: updates["labels_json"] = json_dumps(ensure_list(payload["labels"])) for field, maximum in (("title", 240), ("objective", 2000), ("success_criteria", 4000)): if field in updates: try: updates[field] = require_string(payload, field, max_length=maximum) except ValueError as exc: return 400, {"error": "invalid_treatment", "message": str(exc)} if not updates: return 400, {"error": "no_fields_to_update"} with get_conn() as conn: before = get_treatment(conn, treatment_id) if not before: return 404, {"error": "treatment_not_found"} updates["updated_at"] = now_iso() assignments = ", ".join(f"{key} = ?" for key in updates) conn.execute(f"UPDATE treatments SET {assignments} WHERE id = ?", [*updates.values(), treatment_id]) after = get_treatment(conn, treatment_id) add_timeline( conn, "treatment_updated", "treatment", treatment_id, "Treatment updated", {"before": before, "after": after}, payload.get("actor") or current_actor(), ) return 200, {"treatment": enrich_treatment(conn, after)} def treatment_has_ready_record( conn: sqlite3.Connection, treatment_id: str, record_type: str, ) -> bool: rows = conn.execute( """ SELECT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' AND r.to_type = 'treatment' AND r.to_id = ? WHERE rec.record_type = ? AND rec.review_status IN ('ready', 'reviewed') """, (treatment_id, record_type), ).fetchall() return any( not record_content_error( record["record_type"], record["structured_fields"], record["body_markdown"], record["visibility"], record["review_status"], ) for record in (row_to_record(row) for row in rows) ) def transition_treatment(treatment_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: target_stage = payload.get("stage") if target_stage not in TREATMENT_STAGES: return 400, {"error": "invalid_treatment_stage", "allowed": list(TREATMENT_STAGES)} if target_stage == "observation": return 409, { "error": "start_observation_required", "message": "Use the start observation action to enter observation.", } if target_stage == "completed": return 409, { "error": "complete_treatment_required", "message": "Use the complete action to enter the completed stage.", } actor = payload.get("actor") or current_actor() with get_conn() as conn: treatment = get_treatment(conn, treatment_id) if not treatment: return 404, {"error": "treatment_not_found"} if treatment["state"] != "active": return 409, { "error": "treatment_not_active", "message": "Reopen the Treatment before moving it.", } if target_stage == treatment["stage"]: return 200, {"treatment": enrich_treatment(conn, treatment)} if target_stage not in TREATMENT_STAGE_TRANSITIONS.get(treatment["stage"], set()): return 409, { "error": "invalid_treatment_transition", "from": treatment["stage"], "to": target_stage, } if ( treatment["stage"] == "assessment" and target_stage == "planning" and not treatment_has_ready_record( conn, treatment_id, "analysis_record" ) ): return 409, { "error": "analysis_record_required", "message": "Create a ready or reviewed Analysis Record before moving to planning.", } timestamp = now_iso() conn.execute( "UPDATE treatments SET stage = ?, updated_at = ? WHERE id = ?", (target_stage, timestamp, treatment_id), ) add_timeline( conn, "treatment_stage_changed", "treatment", treatment_id, f"Treatment moved to {target_stage}", {"from": treatment["stage"], "to": target_stage}, actor, timestamp, ) for item_id in linked_catalog_item_ids(conn, treatment_id): add_timeline( conn, "treatment_milestone", "catalog_item", item_id, f"Treatment moved to {target_stage}", {"treatment_id": treatment_id, "stage": target_stage}, actor, timestamp, ) return 200, {"treatment": enrich_treatment(conn, get_treatment(conn, treatment_id))} def start_observation(treatment_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: record_id = payload.get("record_id") if not isinstance(record_id, str): return 400, { "error": "observation_record_required", "message": "Create an Observation Record before starting observation.", } try: due_at = parse_iso(payload.get("observation_due_at"), "observation_due_at", required=True) except ValueError as exc: return 400, {"error": "invalid_observation", "message": str(exc)} actor = payload.get("actor") or current_actor() with get_conn() as conn: treatment = get_treatment(conn, treatment_id) if not treatment: return 404, {"error": "treatment_not_found"} if treatment["state"] != "active": return 409, {"error": "treatment_not_active"} if treatment["stage"] != "execution": return 409, { "error": "execution_stage_required", "message": "Move the Treatment to execution before starting observation.", } record = get_record(conn, record_id) if ( not record or record["record_type"] != "observation_record" or not record_is_linked(conn, record_id, "treatment", treatment_id) ): return 409, {"error": "invalid_observation_record"} started_at = now_iso() if due_at and due_at <= started_at: return 400, { "error": "invalid_observation_due_at", "message": "Observation due time must be in the future.", } conn.execute( """ UPDATE treatments SET stage = 'observation', observation_started_at = ?, observation_due_at = ?, updated_at = ? WHERE id = ? """, (started_at, due_at, started_at, treatment_id), ) add_timeline( conn, "observation_started", "treatment", treatment_id, "Observation started", {"record_id": record_id, "due_at": due_at}, actor, started_at, ) for item_id in linked_catalog_item_ids(conn, treatment_id): add_timeline( conn, "observation_started", "catalog_item", item_id, "Treatment observation started", {"treatment_id": treatment_id, "record_id": record_id, "due_at": due_at}, actor, started_at, ) return 200, {"treatment": enrich_treatment(conn, get_treatment(conn, treatment_id)), "record": record} def complete_treatment(treatment_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: outcome = payload.get("outcome") if outcome not in TREATMENT_OUTCOMES: return 400, { "error": "invalid_outcome", "allowed": sorted(TREATMENT_OUTCOMES), } actor = payload.get("actor") or current_actor() with get_conn() as conn: treatment = get_treatment(conn, treatment_id) if not treatment: return 404, {"error": "treatment_not_found"} if treatment["state"] != "active": return 409, {"error": "treatment_not_active"} records = [ row_to_record(row) for row in conn.execute( """ SELECT rec.* FROM records rec JOIN relations r ON r.from_type = 'record' AND r.from_id = rec.id AND r.relation_type = 'record_of' AND r.to_type = 'treatment' AND r.to_id = ? """, (treatment_id,), ).fetchall() ] requested_record_id = payload.get("outcome_record_id") def select_record(candidates: list[dict[str, Any]]) -> dict[str, Any] | None: if requested_record_id: return next( (record for record in candidates if record["id"] == requested_record_id), None, ) return candidates[0] if candidates else None selected_record: dict[str, Any] | None = None if outcome in {"fixed", "improved", "unchanged"}: selected_record = select_record( [ record for record in records if record["record_type"] == "observation_record" and record["review_status"] == "reviewed" and record["structured_fields"].get("conclusion_type") == outcome ] ) if not selected_record: return 409, { "error": "reviewed_observation_required", "message": ( f"{outcome} requires a reviewed Observation Record with " f"conclusion_type={outcome}." ), } elif outcome == "failed": selected_record = select_record( [ record for record in records if ( record["record_type"] == "observation_record" and record["review_status"] == "reviewed" and record["structured_fields"].get("conclusion_type") in {"failed", "regressed"} ) or ( record["record_type"] == "outcome_record" and record["review_status"] in {"ready", "reviewed"} ) ] ) if not selected_record: return 409, { "error": "outcome_record_required", "message": "Failed requires reviewed observation evidence or a ready Outcome Record.", } elif outcome in {"not_optimizable", "accepted_risk", "cancelled"}: selected_record = select_record( [ record for record in records if record["record_type"] == "outcome_record" and record["review_status"] in {"ready", "reviewed"} ] ) if not selected_record: return 409, { "error": "outcome_record_required", "message": f"{outcome} requires a ready or reviewed Outcome Record.", } superseded_by = payload.get("superseded_by_treatment_id") if outcome == "superseded": target = get_treatment(conn, str(superseded_by)) if superseded_by else None if not target or target["id"] == treatment_id: return 400, {"error": "superseding_treatment_required"} if not set(linked_catalog_item_ids(conn, treatment_id)).intersection( linked_catalog_item_ids(conn, target["id"]) ): return 409, { "error": "superseding_treatment_scope_mismatch", "message": "The superseding Treatment must share a Catalog Item.", } add_relation( conn, "treatment", treatment_id, "superseded_by", "treatment", target["id"], ) timestamp = now_iso() state = "cancelled" if outcome == "cancelled" else "completed" conn.execute( """ UPDATE treatments SET state = ?, stage = 'completed', outcome = ?, outcome_record_id = ?, superseded_by_treatment_id = ?, completed_at = ?, updated_at = ? WHERE id = ? """, ( state, outcome, selected_record["id"] if selected_record else None, superseded_by, timestamp, timestamp, treatment_id, ), ) event_type = "treatment_cancelled" if state == "cancelled" else "treatment_completed" add_timeline( conn, event_type, "treatment", treatment_id, f"Treatment {state} with outcome {outcome}", { "outcome": outcome, "outcome_record_id": selected_record["id"] if selected_record else None, "superseded_by_treatment_id": superseded_by, }, actor, timestamp, ) for item_id in linked_catalog_item_ids(conn, treatment_id): add_timeline( conn, event_type, "catalog_item", item_id, f"Treatment {state} with outcome {outcome}", {"treatment_id": treatment_id, "outcome": outcome}, actor, timestamp, ) return 200, {"treatment": enrich_treatment(conn, get_treatment(conn, treatment_id))} def reopen_treatment(treatment_id: str, payload: dict[str, Any]) -> tuple[int, dict[str, Any]]: stage = payload.get("stage") or "assessment" if stage not in TREATMENT_STAGES or stage in {"observation", "completed"}: return 400, {"error": "invalid_treatment_stage"} actor = payload.get("actor") or current_actor() with get_conn() as conn: treatment = get_treatment(conn, treatment_id) if not treatment: return 404, {"error": "treatment_not_found"} if treatment["state"] == "active": return 409, {"error": "treatment_already_active"} timestamp = now_iso() conn.execute( """ UPDATE treatments SET state = 'active', stage = ?, outcome = NULL, outcome_record_id = NULL, superseded_by_treatment_id = NULL, completed_at = NULL, observation_started_at = NULL, observation_due_at = NULL, updated_at = ? WHERE id = ? """, (stage, timestamp, treatment_id), ) conn.execute( """ DELETE FROM relations WHERE from_type = 'treatment' AND from_id = ? AND relation_type = 'superseded_by' AND to_type = 'treatment' """, (treatment_id,), ) add_timeline( conn, "treatment_reopened", "treatment", treatment_id, "Treatment reopened", {"from_outcome": treatment.get("outcome"), "stage": stage}, actor, timestamp, ) for item_id in linked_catalog_item_ids(conn, treatment_id): add_timeline( conn, "treatment_reopened", "catalog_item", item_id, "Related Treatment reopened", {"treatment_id": treatment_id, "stage": stage}, actor, timestamp, ) return 200, {"treatment": enrich_treatment(conn, get_treatment(conn, treatment_id))} def empty_catalog_review_bucket(bucket: str) -> dict[str, Any]: return { "bucket": bucket, "review_inflow": 0, "review_handled": 0, "backlog": 0, "critical_backlog": 0, } def apply_catalog_review_event( states: dict[str, dict[str, Any]], event: dict[str, Any], review_policies: dict[str, dict[str, Any]] | None = None, ) -> tuple[int, int]: item_id = event["target_id"] state = states.setdefault( item_id, { "pending": False, "risk": None, "active_treatments": set(), "archived": False, "findings": [], }, ) event_type = event["event_type"] payload = event.get("payload") or {} entered = 0 handled = 0 def enter_review(risk: str | None = None) -> None: nonlocal entered if state["archived"] or state["active_treatments"]: return if not state["pending"]: state["pending"] = True entered = 1 if risk in SEVERITY_RANK: state["risk"] = max_severity([state["risk"], risk]) def resolve_review(*, clear_findings: bool = True) -> None: nonlocal handled if state["pending"]: state["pending"] = False state["risk"] = None handled = 1 if clear_findings: state["findings"] = [] def current_anomaly_risk() -> str | None: return max_severity( [ entry["severity"] for entry in state["findings"] if finding_signal_class(entry) == FINDING_SIGNAL_ANOMALY ] ) if payload.get("review_eligible") is False: state["pending"] = False state["risk"] = None state["findings"] = [] return entered, handled if event_type == "catalog_item_created": state["archived"] = False elif event_type == "catalog_item_reactivated": state["archived"] = False elif event_type == "finding_ingested": severity = str(payload.get("severity") or "") state["findings"].append( { "event_at": event.get("created_at"), "severity": severity, "signal_class": payload.get("signal_class"), } ) policy = (review_policies or {}).get( item_id, { **DEFAULT_SQL_REVIEW_POLICY, "source": "system_default", }, ) admission = catalog_review_admission(state["findings"], policy) if admission["required"]: enter_review(current_anomaly_risk()) elif event_type in {"catalog_decision_recorded", "catalog_item_archived"}: resolve_review() if event_type == "catalog_item_archived": state["archived"] = True elif event_type in {"treatment_created", "treatment_reopened"}: treatment_id = str(payload.get("treatment_id") or "") if treatment_id: state["active_treatments"].add(treatment_id) resolve_review() elif event_type in {"treatment_completed", "treatment_cancelled"}: treatment_id = str(payload.get("treatment_id") or "") if treatment_id: state["active_treatments"].discard(treatment_id) state["findings"] = [] return entered, handled def enrich_catalog_event_governance_projection( conn: sqlite3.Connection, events: list[dict[str, Any]] ) -> None: chunk_size = 5000 if connection_dialect(conn) == "mysql" else 500 item_ids = list( dict.fromkeys( str(event.get("target_id") or "") for event in events if event.get("target_type") == "catalog_item" and event.get("target_id") ) ) review_eligibility: dict[str, bool] = {} for start in range(0, len(item_ids), chunk_size): chunk = item_ids[start : start + chunk_size] placeholders = ",".join("?" for _ in chunk) rows = conn.execute( f"SELECT id, normalized_sql FROM catalog_items " f"WHERE id IN ({placeholders})", chunk, ).fetchall() for row in rows: review_eligibility[row["id"]] = bool( catalog_governance_relevance(dict(row))["review_eligible"] ) finding_ids = list( dict.fromkeys( str(event.get("payload", {}).get("finding_id") or "") for event in events if event.get("event_type") == "finding_ingested" and event.get("payload", {}).get("finding_id") ) ) projections: dict[str, dict[str, Any]] = {} for start in range(0, len(finding_ids), chunk_size): chunk = finding_ids[start : start + chunk_size] placeholders = ",".join("?" for _ in chunk) rows = conn.execute( f"SELECT id, source, detector_code, dimensions_json FROM findings " f"WHERE id IN ({placeholders})", chunk, ).fetchall() for row in rows: finding = dict(row) projections[row["id"]] = { "signal_class": finding_signal_class(finding), } for event in events: item_id = str(event.get("target_id") or "") payload = event.get("payload") or {} if item_id in review_eligibility: payload["review_eligible"] = review_eligibility[item_id] if event.get("event_type") != "finding_ingested": continue finding_id = str(payload.get("finding_id") or "") if finding_id in projections: payload.update(projections[finding_id]) def catalog_review_period_aggregate( events: list[dict[str, Any]], *, period_start: datetime, period_end: datetime, timezone_offset: int, review_policies: dict[str, dict[str, Any]] | None = None, ) -> dict[str, Any]: bucket_cursor = day_bucket_start(period_start, timezone_offset) buckets: dict[str, dict[str, Any]] = {} while bucket_cursor < period_end: key = iso_datetime(bucket_cursor) buckets[key] = empty_catalog_review_bucket(key) bucket_cursor += timedelta(seconds=DAY_BUCKET_SECONDS) parsed_events = sorted( ( (timestamp, input_index, event) for input_index, event in enumerate(events) if (timestamp := try_datetime(event.get("created_at"))) is not None and timestamp < period_end ), key=treatment_event_sort_key, ) states: dict[str, dict[str, Any]] = {} event_index = 0 while event_index < len(parsed_events) and parsed_events[event_index][0] < period_start: apply_catalog_review_event( states, parsed_events[event_index][2], review_policies ) event_index += 1 def backlog_counts() -> tuple[int, int]: pending = [state for state in states.values() if state["pending"]] return len(pending), sum(1 for state in pending if state["risk"] == "critical") backlog_start, critical_backlog_start = backlog_counts() for key in sorted(buckets): bucket_start = try_datetime(key) or period_start cutoff = min(bucket_start + timedelta(seconds=DAY_BUCKET_SECONDS), period_end) entry = buckets[key] while event_index < len(parsed_events) and parsed_events[event_index][0] < cutoff: timestamp, _, event = parsed_events[event_index] entered, handled = apply_catalog_review_event( states, event, review_policies ) if timestamp >= period_start: entry["review_inflow"] += entered entry["review_handled"] += handled event_index += 1 entry["backlog"], entry["critical_backlog"] = backlog_counts() time_series = [buckets[key] for key in sorted(buckets)] backlog_end = time_series[-1]["backlog"] if time_series else backlog_start critical_backlog_end = ( time_series[-1]["critical_backlog"] if time_series else critical_backlog_start ) return { "summary": { "review_inflow": sum(item["review_inflow"] for item in time_series), "review_handled": sum(item["review_handled"] for item in time_series), "backlog_start": backlog_start, "backlog_end": backlog_end, "net_backlog_change": backlog_end - backlog_start, "critical_backlog_start": critical_backlog_start, "critical_backlog_end": critical_backlog_end, "critical_backlog_change": critical_backlog_end - critical_backlog_start, }, "time_series": time_series, } def workbench_outcome_scope( conn: sqlite3.Connection, params: dict[str, list[str]], period_start: datetime, period_end: datetime, ) -> dict[str, int]: where_sql, values = treatment_filter_sql(params) rows = conn.execute( """ SELECT DISTINCT ci.org_id, ci.cluster_id FROM timeline_events e JOIN treatments t ON t.id = e.target_id AND e.target_type = 'treatment' JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' JOIN catalog_items ci ON ci.id = r.to_id """ + (where_sql or " WHERE 1 = 1") + " AND e.event_type IN ('recommendation_shared', 'treatment_completed', 'treatment_cancelled')" + " AND e.created_at >= ? AND e.created_at < ?", [*values, iso_datetime(period_start), iso_datetime(period_end)], ).fetchall() return { "affected_orgs": len({row["org_id"] for row in rows}), "affected_clusters": len({row["cluster_id"] for row in rows}), } def workbench_assessment( review_summary: dict[str, Any], treatment_summary: dict[str, Any], *, stalled_treatments: int, observation_due: int, comparison_quality: dict[str, Any], ) -> dict[str, Any]: if not comparison_quality["comparable"]: return { "state": "baseline", "reasons": [ { "code": "baseline_building", "value": comparison_quality.get("current_completed_runs", 0), } ], } critical_change = review_summary["critical_backlog_change"] backlog_change = review_summary["net_backlog_change"] review_gap = review_summary["review_inflow"] - review_summary["review_handled"] successful = treatment_summary["successful_treatments"] reasons: list[dict[str, Any]] = [] if critical_change: reasons.append({"code": "critical_backlog_change", "value": critical_change}) if review_gap: reasons.append({"code": "review_balance", "value": review_gap}) if successful: reasons.append({"code": "verified_success", "value": successful}) if stalled_treatments: reasons.append({"code": "stalled_treatments", "value": stalled_treatments}) if observation_due: reasons.append({"code": "observation_due", "value": observation_due}) if not reasons: reasons.append({"code": "no_material_change", "value": 0}) if critical_change > 0 or (backlog_change > 0 and review_gap > 0): state = "expanding" elif critical_change < 0 and backlog_change <= 0: state = "improving" elif stalled_treatments or observation_due or review_summary["critical_backlog_end"]: state = "attention" else: state = "stable" return {"state": state, "reasons": reasons[:3]} def catalog_queue_cohort(item: dict[str, Any]) -> str: return str( (item["current_posture"].get("review_priority") or {}).get("tier") or "none" ) def workbench_catalog_queue(items: list[dict[str, Any]]) -> dict[str, Any]: decision_items = [ item for item in items if catalog_projection_review_eligible(item) and item["current_posture"]["state"] == "needs_review" and not item["current_posture"]["active_treatment_count"] ] decision_items.sort(key=catalog_operational_sort_key) recommended_items = select_recommended_review_batch(decision_items) priority_counts = { tier: sum( 1 for item in decision_items if catalog_queue_cohort(item) == tier ) for tier in REVIEW_PRIORITY_TIERS } return { "total": len(recommended_items), "batch_limit": RECOMMENDED_REVIEW_BATCH_SIZE, "priority_counts": priority_counts, "items": [ { "id": item["id"], "org_id": item["org_id"], "cluster_id": item["cluster_id"], "sql_digest": item["sql_digest"], "normalized_sql": item.get("normalized_sql"), "owner": item.get("owner"), "latest_finding_at": item.get("latest_finding_at"), "finding_count": item.get("finding_count", 0), "finding_run_count": item.get("finding_run_count", 0), "symptom_codes": item.get("symptom_codes", []), "cohort": catalog_queue_cohort(item), "current_posture": item["current_posture"], } for item in recommended_items[:8] ], } def workbench_scope_params(params: dict[str, list[str]]) -> dict[str, list[str]]: return { key: list(params[key]) for key in ("org_id", "cluster_id") if params.get(key) } def update_cluster_sql_health_owners( cluster_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: reject_unknown_fields( payload, frozenset({"owner_ids"}), "cluster SQL health owners" ) cluster_id = cluster_id.strip() if not cluster_id or len(cluster_id) > 128: raise ValueError("cluster_id must be between 1 and 128 characters") raw_owner_ids = payload.get("owner_ids") if not isinstance(raw_owner_ids, list): raise ValueError("owner_ids must be an array") if len(raw_owner_ids) > 20: raise ValueError("owner_ids must contain at most 20 owners") owner_ids: list[str] = [] for index, value in enumerate(raw_owner_ids): if not isinstance(value, str): raise ValueError(f"owner_ids[{index}] must be a string") owner_id = value.strip() if not owner_id: raise ValueError(f"owner_ids[{index}] must not be empty") if len(owner_id) > 128: raise ValueError(f"owner_ids[{index}] must be at most 128 characters") if owner_id not in owner_ids: owner_ids.append(owner_id) timestamp = now_iso() with get_conn() as conn: existing = { row["owner_id"]: row["assigned_at"] for row in conn.execute( "SELECT owner_id, assigned_at FROM cluster_sql_health_owners " "WHERE cluster_id = ?", (cluster_id,), ).fetchall() } conn.execute( "DELETE FROM cluster_sql_health_owners WHERE cluster_id = ?", (cluster_id,), ) conn.executemany( """ INSERT INTO cluster_sql_health_owners (cluster_id, owner_id, assigned_by, assigned_at, updated_at) VALUES (?, ?, ?, ?, ?) """, [ ( cluster_id, owner_id, current_user_id(), existing.get(owner_id, timestamp), timestamp, ) for owner_id in owner_ids ], ) return 200, { "cluster_id": cluster_id, "owners": owner_ids, "updated_at": timestamp, } def upsert_cluster_sql_review_policy( conn: sqlite3.Connection, cluster_id: str, policy: dict[str, Any], timestamp: str, ) -> None: conn.execute( dialect_sql( conn, """ INSERT INTO cluster_sql_review_policies (cluster_id, critical_finding_triggers_review, finding_count_threshold, finding_window_days, updated_by, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(cluster_id) DO UPDATE SET critical_finding_triggers_review = excluded.critical_finding_triggers_review, finding_count_threshold = excluded.finding_count_threshold, finding_window_days = excluded.finding_window_days, updated_by = excluded.updated_by, updated_at = excluded.updated_at """, """ INSERT INTO cluster_sql_review_policies (cluster_id, critical_finding_triggers_review, finding_count_threshold, finding_window_days, updated_by, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON DUPLICATE KEY UPDATE critical_finding_triggers_review = VALUES(critical_finding_triggers_review), finding_count_threshold = VALUES(finding_count_threshold), finding_window_days = VALUES(finding_window_days), updated_by = VALUES(updated_by), updated_at = VALUES(updated_at) """, ), ( cluster_id, int(policy["critical_finding_triggers_review"]), policy["finding_count_threshold"], policy["finding_window_days"], current_user_id(), timestamp, timestamp, ), ) def cluster_review_impact( conn: sqlite3.Connection, cluster_id: str ) -> dict[str, int]: rows = conn.execute( "SELECT * FROM catalog_items WHERE cluster_id = ?", (cluster_id,), ).fetchall() items = [enrich_catalog_item(conn, row_to_catalog_item(row)) for row in rows] decision_items = [ item for item in items if catalog_projection_review_eligible(item) and item["current_posture"]["state"] == "needs_review" ] recommended = select_recommended_review_batch(decision_items) return { "catalog_item_count": len(items), "decision_required_count": len(decision_items), "recommended_review_count": len(recommended), "p0_count": sum( 1 for item in decision_items if item["current_posture"]["review_priority"]["tier"] == "p0" ), "p1_count": sum( 1 for item in decision_items if item["current_posture"]["review_priority"]["tier"] == "p1" ), "registered_count": sum( 1 for item in items if item["current_posture"]["state"] == "registered" ), } def cluster_configuration_payload( conn: sqlite3.Connection, cluster_id: str ) -> dict[str, Any]: candidates = cluster_directory_candidates(conn) cluster = candidates.get(cluster_id) or { "cluster_id": cluster_id, "cluster_name": cluster_id, "org_id": None, "org_name": None, "lifecycle": "unknown", } memberships: list[dict[str, Any]] = [] scope_rows = conn.execute( "SELECT * FROM cluster_scopes WHERE owner_id = ? OR visibility = 'public' " "ORDER BY is_recommended DESC, name, id", (current_user_id(),), ).fetchall() for row in scope_rows: members = cluster_scope_members(conn, row) if any(member["cluster_id"] == cluster_id for member in members): memberships.append( { "id": row["id"], "name": row["name"], "visibility": row["visibility"], "membership_mode": row["membership_mode"], "is_recommended": bool(row["is_recommended"]), "can_edit": row["owner_id"] == current_user_id() and not bool(row["is_recommended"]), "member_count": len(members), } ) owners = [ row["owner_id"] for row in conn.execute( "SELECT owner_id FROM cluster_sql_health_owners " "WHERE cluster_id = ? ORDER BY owner_id", (cluster_id,), ).fetchall() ] return { "cluster": cluster, "sql_review_policy": cluster_sql_review_policy(conn, cluster_id), "sql_health_owners": owners, "memberships": memberships, "review_impact": cluster_review_impact(conn, cluster_id), } def get_cluster_configuration(cluster_id: str) -> tuple[int, dict[str, Any]]: cluster_id = cluster_id.strip() if not cluster_id or len(cluster_id) > 128: return 400, {"error": "invalid_cluster_id"} with get_conn() as conn: return 200, cluster_configuration_payload(conn, cluster_id) def update_cluster_configuration( cluster_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: reject_unknown_fields( payload, frozenset({"sql_review_policy"}), "cluster configuration" ) cluster_id = cluster_id.strip() if not cluster_id or len(cluster_id) > 128: raise ValueError("cluster_id must be between 1 and 128 characters") policy = parse_sql_review_policy(payload.get("sql_review_policy")) timestamp = now_iso() with get_conn() as conn: upsert_cluster_sql_review_policy(conn, cluster_id, policy, timestamp) return 200, cluster_configuration_payload(conn, cluster_id) def reset_cluster_configuration(cluster_id: str) -> tuple[int, dict[str, Any]]: cluster_id = cluster_id.strip() if not cluster_id or len(cluster_id) > 128: return 400, {"error": "invalid_cluster_id"} with get_conn() as conn: conn.execute( "DELETE FROM cluster_sql_review_policies WHERE cluster_id = ?", (cluster_id,), ) return 200, cluster_configuration_payload(conn, cluster_id) def cluster_scope_configurations(scope_id: str) -> tuple[int, dict[str, Any]]: with get_conn() as conn: row = visible_cluster_scope_row(conn, scope_id) if not row: return 404, {"error": "cluster_scope_not_found"} scope = row_to_cluster_scope(conn, row) members = [ { **member, "sql_review_policy": cluster_sql_review_policy( conn, member["cluster_id"] ), } for member in scope["members"] ] return 200, { "cluster_scope": {**scope, "members": members}, "system_default": { **DEFAULT_SQL_REVIEW_POLICY, "source": "system_default", }, } def apply_cluster_scope_configurations( scope_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: reject_unknown_fields( payload, frozenset({"cluster_ids", "sql_review_policy"}), "cluster scope configuration application", ) raw_cluster_ids = payload.get("cluster_ids") if not isinstance(raw_cluster_ids, list) or not raw_cluster_ids: raise ValueError("cluster_ids must be a non-empty array") if len(raw_cluster_ids) > 1000: raise ValueError("cluster_ids must contain at most 1000 clusters") cluster_ids: list[str] = [] for index, value in enumerate(raw_cluster_ids): if not isinstance(value, str) or not value.strip(): raise ValueError(f"cluster_ids[{index}] must be a non-empty string") cluster_id = value.strip() if len(cluster_id) > 128: raise ValueError(f"cluster_ids[{index}] must be at most 128 characters") if cluster_id not in cluster_ids: cluster_ids.append(cluster_id) policy = parse_sql_review_policy(payload.get("sql_review_policy")) with get_conn() as conn: row = visible_cluster_scope_row(conn, scope_id) if not row: return 404, {"error": "cluster_scope_not_found"} current_members = { member["cluster_id"] for member in cluster_scope_members(conn, row) } invalid_ids = [cluster_id for cluster_id in cluster_ids if cluster_id not in current_members] if invalid_ids: return 409, { "error": "clusters_not_in_scope", "cluster_ids": invalid_ids, } timestamp = now_iso() for cluster_id in cluster_ids: upsert_cluster_sql_review_policy(conn, cluster_id, policy, timestamp) return 200, { "scope_id": scope_id, "applied_count": len(cluster_ids), "cluster_ids": cluster_ids, "sql_review_policy": {**policy, "source": "cluster"}, "updated_at": timestamp, } def clinic_health_check_cluster_context( cluster_id: str, ) -> tuple[int, dict[str, Any]]: cluster_id = cluster_id.strip() if not cluster_id or len(cluster_id) > 128: return 400, {"error": "invalid_cluster_id"} if not CLINIC_API_KEY: return 503, {"error": "clinic_api_not_configured"} def cached_context() -> dict[str, Any] | None: with get_conn() as conn: candidate = cluster_directory_candidates(conn).get(cluster_id) metadata_row = conn.execute( "SELECT * FROM cluster_metadata WHERE cluster_id = ?", (cluster_id,) ).fetchone() if not candidate: return None metadata = ( row_to_cluster_metadata(metadata_row) if metadata_row else {"metadata": {}} ) canonical_org_id = optional_metadata_value(candidate.get("tenant_id")) if not canonical_org_id or canonical_org_id == "unknown": return None candidate_org_id = optional_metadata_value(candidate.get("org_id")) portal_org_id = ( candidate_org_id if candidate_org_id and candidate_org_id != canonical_org_id else None ) metadata_values = ensure_dict(metadata.get("metadata")) return { **candidate, "org_id": canonical_org_id, "dbaas_org_id": canonical_org_id, "tenant_id": canonical_org_id, "portal_org_id": portal_org_id, "project_id": metadata_values.get("project_id"), "provider": candidate.get("provider") or metadata_values.get("cloud_provider"), "region": candidate.get("region") or metadata_values.get("region"), } if context := cached_context(): return 200, context metadata = fetch_clinic_cluster_metadata(cluster_id) if not metadata: return 502, {"error": "clinic_api_unavailable"} upsert_cluster_metadata(metadata) if context := cached_context(): return 200, context return 502, {"error": "clinic_metadata_invalid"} def cache_health_check_portal_org_identity( context: dict[str, Any], reports: list[dict[str, Any]] ) -> dict[str, Any]: portal_org_ids = { str(report.get("portalOrgId") or "").strip() for report in reports if isinstance(report, dict) and str(report.get("portalOrgId") or "").strip() } canonical_org_id = optional_metadata_value(context.get("dbaas_org_id")) if not canonical_org_id: return context if len(portal_org_ids) > 1: return context resolved_identity: dict[str, Any] | None = None if portal_org_ids: portal_org_id = next(iter(portal_org_ids)) else: cached_portal_org_id = optional_metadata_value(context.get("portal_org_id")) if cached_portal_org_id: return context resolved_identity = clinic_portal_cluster_identity( context["cluster_id"], canonical_org_id ) if not resolved_identity: return context portal_org_id = resolved_identity["clinic_org_id"] with get_conn() as conn: existing_row = conn.execute( "SELECT * FROM cluster_metadata WHERE cluster_id = ?", (context["cluster_id"],), ).fetchone() existing = row_to_cluster_metadata(existing_row) if existing_row else None existing_metadata = existing.get("metadata", {}) if existing else {} resolved_metadata = ( ensure_dict(resolved_identity.get("metadata")) if resolved_identity else {} ) resolved_metadata = { key: value for key, value in resolved_metadata.items() if value is not None } stored = upsert_cluster_metadata_with_conn( conn, { "cluster_id": context["cluster_id"], "clinic_org_id": portal_org_id, "tenant_id": canonical_org_id, "org_name": (resolved_identity or {}).get("org_name") or context.get("org_name") or (existing.get("org_name") if existing else None), "cluster_name": (resolved_identity or {}).get("cluster_name") or context.get("cluster_name") or (existing.get("cluster_name") if existing else context["cluster_id"]), "deploy_type": (resolved_identity or {}).get("deploy_type") or context.get("deploy_type") or (existing.get("deploy_type") if existing else None), "metadata": {**existing_metadata, **resolved_metadata}, "fetched_at": now_iso(), }, ) return { **context, "portal_org_id": portal_org_id, "org_name": stored.get("org_name") or context.get("org_name"), "cluster_name": stored.get("cluster_name") or context.get("cluster_name"), "deploy_type": stored.get("deploy_type") or context.get("deploy_type"), } def health_check_report_list( cluster_id: str, params: dict[str, list[str]] ) -> tuple[int, dict[str, Any]]: allowed = {"page", "page_size", "status", "created_from", "created_to"} unexpected = sorted(set(params) - allowed) if unexpected: return 400, { "error": "invalid_health_check_report_query", "message": f"unsupported query parameters: {', '.join(unexpected)}", } try: page = strict_positive_query_int(params, "page", 1, 1_000_000) page_size = strict_positive_query_int(params, "page_size", 20, 100) statuses = param_values(params, "status") invalid_statuses = [ status for status in statuses if status not in HEALTH_CHECK_REPORT_STATUSES ] if invalid_statuses: raise ValueError( f"status contains unsupported values: {', '.join(invalid_statuses)}" ) created_from = parse_iso( params.get("created_from", [None])[0], "created_from" ) created_to = parse_iso(params.get("created_to", [None])[0], "created_to") if created_from and created_to and created_from > created_to: raise ValueError("created_from must not be after created_to") except ValueError as exc: return 400, { "error": "invalid_health_check_report_query", "message": str(exc), } context_status, context = clinic_health_check_cluster_context(cluster_id) if context_status != 200: return context_status, context query: list[tuple[str, str]] = [ ("page", str(page)), ("pageSize", str(page_size)), ] query.extend(("status", status) for status in statuses) if created_from: query.append(("createdFrom", created_from)) if created_to: query.append(("createdTo", created_to)) status, payload = clinic_data_proxy_get( "orgs/" f"{quote(context['dbaas_org_id'], safe='')}/clusters/" f"{quote(cluster_id, safe='')}/health-check/reports", query, ) if status == HTTPStatus.NOT_FOUND: return 404, {"error": "clinic_health_check_reports_not_found"} if status != 200 or not isinstance(payload, dict): return 502, {"error": "clinic_health_check_reports_unavailable"} raw_items = payload.get("items") if not isinstance(raw_items, list): return 502, {"error": "clinic_health_check_report_response_invalid"} typed_items = [item for item in raw_items if isinstance(item, dict)] context = cache_health_check_portal_org_identity(context, typed_items) reports = [ normalize_health_check_report_summary(item, context.get("portal_org_id")) for item in typed_items ] syncs = health_check_report_sync_projections( cluster_id, [report["report_id"] for report in reports] ) for report in reports: report["sync"] = syncs.get(report["report_id"], unsynced_report_state()) return 200, { "items": reports, "page": positive_int(payload.get("page"), page, 1_000_000), "page_size": positive_int(payload.get("pageSize"), page_size, 100), "total": positive_int(payload.get("total"), len(reports), 10_000_000), "cluster": context, } def health_check_report_detail( cluster_id: str, report_id: str, params: dict[str, list[str]], ) -> tuple[int, dict[str, Any]]: unexpected = sorted(set(params) - {"item_name"}) if unexpected: return 400, { "error": "invalid_health_check_report_query", "message": f"unsupported query parameters: {', '.join(unexpected)}", } try: report_id = validate_health_check_resource_id(report_id, "report_id") item_names = [ validate_health_check_resource_id(value, "item_name") for value in param_values(params, "item_name") ] if len(item_names) > 64: raise ValueError("item_name may be repeated at most 64 times") except ValueError as exc: return 400, { "error": "invalid_health_check_report_query", "message": str(exc), } context_status, context = clinic_health_check_cluster_context(cluster_id) if context_status != 200: return context_status, context status, report = clinic_health_check_report_get( context["dbaas_org_id"], cluster_id, report_id, item_names ) if status == HTTPStatus.NOT_FOUND: return 404, {"error": "clinic_health_check_report_not_found"} if status != 200 or report is None: return 502, {"error": "clinic_health_check_report_unavailable"} context = cache_health_check_portal_org_identity(context, [report]) return 200, normalize_health_check_report_detail( report, context.get("portal_org_id") ) def parse_health_check_report_sync_request( payload: dict[str, Any], ) -> list[dict[str, Any]]: reject_unknown_fields( payload, frozenset({"reports"}), "health check report sync" ) raw_reports = payload.get("reports") if not isinstance(raw_reports, list) or not raw_reports: raise ValueError("reports must be a non-empty array") if len(raw_reports) > 20: raise ValueError("reports must contain at most 20 entries") requested: list[dict[str, Any]] = [] seen: set[str] = set() for index, value in enumerate(raw_reports): if not isinstance(value, dict): raise ValueError(f"reports[{index}] must be an object") reject_unknown_fields( value, frozenset({"report_id", "item_names"}), f"reports[{index}]", ) report_id = validate_health_check_resource_id( value.get("report_id"), f"reports[{index}].report_id" ) raw_item_names = value.get("item_names") if raw_item_names is None: item_names: list[str] = [] else: if not isinstance(raw_item_names, list): raise ValueError(f"reports[{index}].item_names must be an array") item_names = [] for item_index, item_name in enumerate(raw_item_names): name = validate_health_check_resource_id( item_name, f"reports[{index}].item_names[{item_index}]", ) if name not in SUPPORTED_SQL_CHECK_SET: raise ValueError( f"reports[{index}].item_names contains unsupported SQL check {name}" ) if name not in item_names: item_names.append(name) if report_id not in seen: requested.append({"report_id": report_id, "item_names": item_names}) seen.add(report_id) return requested def sync_health_check_reports( cluster_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: try: requested = parse_health_check_report_sync_request(payload) except ValueError as exc: return 400, {"error": "invalid_health_check_report_sync", "message": str(exc)} context_status, context = clinic_health_check_cluster_context(cluster_id) if context_status != 200: return context_status, context results = [ sync_one_health_check_report(context, entry["report_id"], entry["item_names"]) for entry in requested ] summary = { "reports": len(results), "succeeded": sum(result["status"] == "succeeded" for result in results), "partial": sum(result["status"] == "partial" for result in results), "failed": sum(result["status"] == "failed" for result in results), "findings_created": sum(int(result.get("created_count") or 0) for result in results), "findings_existing": sum(int(result.get("duplicate_count") or 0) for result in results), "findings_rejected": sum(int(result.get("rejected_count") or 0) for result in results), "catalog_items_created": sum( int(result.get("catalog_created_count") or 0) for result in results ), } response_status = 207 if summary["partial"] or summary["failed"] else 200 return response_status, { "cluster_id": cluster_id, "org_id": context["dbaas_org_id"], "summary": summary, "items": results, } def queue_health_check_report_imports( cluster_id: str, payload: dict[str, Any] ) -> tuple[int, dict[str, Any]]: try: requested = parse_health_check_report_sync_request(payload) except ValueError as exc: return 400, {"error": "invalid_health_check_report_sync", "message": str(exc)} context_status, context = clinic_health_check_cluster_context(cluster_id) if context_status != 200: return context_status, context org_id = str(context["dbaas_org_id"]) requested_by = current_user_id() queue_started_at = datetime.now(timezone.utc) queued = 0 in_progress = 0 items: list[dict[str, Any]] = [] with get_conn() as conn: for index, entry in enumerate(requested): queued_at = ( queue_started_at + timedelta(microseconds=index) ).isoformat(timespec="microseconds").replace("+00:00", "Z") existing = conn.execute( """ SELECT state FROM health_check_report_syncs WHERE org_id = ? AND cluster_id = ? AND report_id = ? """, (org_id, cluster_id, entry["report_id"]), ).fetchone() if existing and existing["state"] in {"queued", "syncing"}: in_progress += 1 items.append( { "report_id": entry["report_id"], "state": existing["state"], "selected_item_names": entry["item_names"], } ) continue conn.execute( dialect_sql( conn, """ INSERT INTO health_check_report_syncs (id, org_id, cluster_id, report_id, state, selected_items_json, requested_by, started_at, updated_at) VALUES (?, ?, ?, ?, 'queued', ?, ?, ?, ?) ON CONFLICT(org_id, cluster_id, report_id) DO UPDATE SET report_status = NULL, state = 'queued', selected_items_json = excluded.selected_items_json, finding_run_id = NULL, finding_count = 0, created_count = 0, duplicate_count = 0, rejected_count = 0, catalog_created_count = 0, requested_by = excluded.requested_by, report_created_at = NULL, report_updated_at = NULL, error_message = NULL, started_at = excluded.started_at, completed_at = NULL, updated_at = excluded.updated_at """, """ INSERT INTO health_check_report_syncs (id, org_id, cluster_id, report_id, state, selected_items_json, requested_by, started_at, updated_at) VALUES (?, ?, ?, ?, 'queued', ?, ?, ?, ?) ON DUPLICATE KEY UPDATE report_status = NULL, state = 'queued', selected_items_json = VALUES(selected_items_json), finding_run_id = NULL, finding_count = 0, created_count = 0, duplicate_count = 0, rejected_count = 0, catalog_created_count = 0, requested_by = VALUES(requested_by), report_created_at = NULL, report_updated_at = NULL, error_message = NULL, started_at = VALUES(started_at), completed_at = NULL, updated_at = VALUES(updated_at) """, ), ( new_id("hcs"), org_id, cluster_id, entry["report_id"], json_dumps(entry["item_names"]), requested_by, queued_at, queued_at, ), ) queued += 1 items.append( { "report_id": entry["report_id"], "state": "queued", "selected_item_names": entry["item_names"], } ) _HEALTH_CHECK_IMPORT_WAKE.set() return HTTPStatus.ACCEPTED, { "cluster_id": cluster_id, "org_id": org_id, "summary": { "reports": len(requested), "queued": queued, "in_progress": in_progress, }, "items": items, } def recover_interrupted_health_check_report_imports() -> int: timestamp = now_iso() with get_conn() as conn: cursor = conn.execute( """ UPDATE health_check_report_syncs SET state = 'queued', error_message = NULL, completed_at = NULL, updated_at = ? WHERE state = 'syncing' """, (timestamp,), ) return max(0, int(cursor.rowcount or 0)) def claim_next_health_check_report_import() -> dict[str, Any] | None: with get_conn() as conn: candidates = conn.execute( """ SELECT id, org_id, cluster_id, report_id, selected_items_json, requested_by, updated_at FROM health_check_report_syncs WHERE state = 'queued' ORDER BY updated_at, report_id LIMIT 8 """ ).fetchall() for candidate in candidates: timestamp = now_iso() cursor = conn.execute( """ UPDATE health_check_report_syncs SET state = 'syncing', started_at = ?, completed_at = NULL, error_message = NULL, updated_at = ? WHERE id = ? AND state = 'queued' """, (timestamp, timestamp, candidate["id"]), ) if int(cursor.rowcount or 0) != 1: continue return { **dict(candidate), "state": "syncing", "started_at": timestamp, "selected_item_names": json_loads( candidate["selected_items_json"], [] ), } return None def fail_claimed_health_check_report_import( claimed: dict[str, Any], message: str ) -> None: timestamp = now_iso() with get_conn() as conn: conn.execute( """ UPDATE health_check_report_syncs SET state = 'failed', error_message = ?, completed_at = ?, updated_at = ? WHERE id = ? """, (message[:2000], timestamp, timestamp, claimed["id"]), ) def process_next_health_check_report_import() -> bool: claimed = claim_next_health_check_report_import() if not claimed: return False started = time.monotonic() result_state = "failed" request_user_token = REQUEST_USER.set({"id": claimed["requested_by"]}) try: status, body = sync_health_check_reports( claimed["cluster_id"], { "reports": [ { "report_id": claimed["report_id"], "item_names": claimed["selected_item_names"], } ] }, ) if status not in {HTTPStatus.OK, HTTPStatus.MULTI_STATUS}: fail_claimed_health_check_report_import( claimed, str( body.get("message") or body.get("error") or "Health Check report import could not be completed" ), ) elif body.get("items"): result_state = str(body["items"][0].get("status") or "failed") except Exception as exc: # Keep one malformed report from stopping the queue. fail_claimed_health_check_report_import(claimed, str(exc)) print( json.dumps( { "timestamp": now_iso(), "level": "error", "event": "health_check_report_import_failed", "cluster_id": claimed["cluster_id"], "report_id": claimed["report_id"], "error_type": type(exc).__name__, }, ensure_ascii=True, ), file=sys.stderr, flush=True, ) finally: REQUEST_USER.reset(request_user_token) print( json.dumps( { "timestamp": now_iso(), "level": "info", "event": "health_check_report_import_completed", "cluster_id": claimed["cluster_id"], "report_id": claimed["report_id"], "state": result_state, "duration_ms": round((time.monotonic() - started) * 1000), }, ensure_ascii=True, ), file=sys.stderr, flush=True, ) return True def health_check_report_import_worker_loop() -> None: while not _HEALTH_CHECK_IMPORT_STOP.is_set(): if process_next_health_check_report_import(): continue _HEALTH_CHECK_IMPORT_WAKE.wait(timeout=5.0) _HEALTH_CHECK_IMPORT_WAKE.clear() def start_health_check_report_import_worker() -> None: global _HEALTH_CHECK_IMPORT_WORKER with _HEALTH_CHECK_IMPORT_WORKER_LOCK: if ( _HEALTH_CHECK_IMPORT_WORKER is not None and _HEALTH_CHECK_IMPORT_WORKER.is_alive() ): return _HEALTH_CHECK_IMPORT_STOP.clear() recovered = recover_interrupted_health_check_report_imports() _HEALTH_CHECK_IMPORT_WORKER = threading.Thread( target=health_check_report_import_worker_loop, name="health-check-report-import-worker", daemon=True, ) _HEALTH_CHECK_IMPORT_WORKER.start() if recovered: _HEALTH_CHECK_IMPORT_WAKE.set() def stop_health_check_report_import_worker() -> None: _HEALTH_CHECK_IMPORT_STOP.set() _HEALTH_CHECK_IMPORT_WAKE.set() worker = _HEALTH_CHECK_IMPORT_WORKER if worker is not None and worker.is_alive(): worker.join(timeout=5.0) def sync_one_health_check_report( context: dict[str, Any], report_id: str, item_names: list[str] ) -> dict[str, Any]: started_at = now_iso() start_health_check_report_sync( context["dbaas_org_id"], context["cluster_id"], report_id, item_names, started_at, ) try: status, report = clinic_health_check_report_get( context["dbaas_org_id"], context["cluster_id"], report_id, item_names ) if status == HTTPStatus.NOT_FOUND: raise ValueError("Clinic Health Check report was not found in this cluster") if status != 200 or report is None: raise RuntimeError("Clinic Health Check report detail is unavailable") context = cache_health_check_portal_org_identity(context, [report]) report_status = str(report.get("status") or "").lower() if report_status in {"pending", "running"}: raise ValueError("Clinic Health Check report is not complete yet") if report_status == "failed": raise ValueError("Clinic Health Check report failed and cannot be synchronized") available_items = importable_check_names(report.get("items")) if not available_items: raise ValueError("Clinic Health Check report has no supported SQL check items") imported = build_report_import(report, context, CLINIC_PORTAL_BASE) report_created_at = imported["report"]["created_at"] run_status, run_body = create_finding_run( imported["run"], received_at=report_created_at ) if run_status not in {200, 201} or not run_body.get("run"): raise RuntimeError( str(run_body.get("message") or "Finding run could not be created") ) finding_run_id = run_body["run"]["id"] created_count = 0 duplicate_count = 0 rejected_count = 0 catalog_created_count = 0 rejection_messages: list[str] = [] for finding in imported["findings"]: finding_status, finding_body = create_finding( finding, received_at=report_created_at, compact_response=True, ) if finding_status == 201: created_count += 1 if finding_body["finding"].get("is_new_digest"): catalog_created_count += 1 elif finding_status == 200 and finding_body.get("finding"): duplicate_count += 1 else: rejected_count += 1 rejection_messages.append( str( finding_body.get("message") or finding_body.get("error") or "Finding was rejected" ) ) sync_state = ( "partial" if rejected_count or imported["failed_item_names"] or imported["run"]["status"] == "partial" else "succeeded" ) error_message = "; ".join(dict.fromkeys(rejection_messages)) or None result = { "report_id": report_id, "status": sync_state, "report_status": report_status, "finding_run_id": finding_run_id, "finding_count": len(imported["findings"]), "created_count": created_count, "duplicate_count": duplicate_count, "rejected_count": rejected_count, "catalog_created_count": catalog_created_count, "selected_item_names": imported["supported_item_names"], "failed_item_names": imported["failed_item_names"], "source_url": imported["report"].get("source_url"), "report_created_at": report_created_at, "report_updated_at": imported["report"].get("updated_at"), "completed_at": now_iso(), "error_message": error_message, } finish_health_check_report_sync(context, result) return result except (RuntimeError, ValueError, KeyError) as exc: result = { "report_id": report_id, "status": "failed", "report_status": None, "finding_run_id": None, "finding_count": 0, "created_count": 0, "duplicate_count": 0, "rejected_count": 0, "catalog_created_count": 0, "selected_item_names": item_names, "failed_item_names": [], "source_url": None, "report_created_at": None, "report_updated_at": None, "completed_at": now_iso(), "error_message": str(exc), } finish_health_check_report_sync(context, result) return result def clinic_health_check_report_get( org_id: str, cluster_id: str, report_id: str, item_names: list[str], ) -> tuple[int, dict[str, Any] | None]: status, payload = clinic_data_proxy_get( "orgs/" f"{quote(org_id, safe='')}/clusters/{quote(cluster_id, safe='')}" f"/health-check/reports/{quote(report_id, safe='')}", [("itemName", name) for name in item_names], ) return status, payload if isinstance(payload, dict) else None def normalize_health_check_report_summary( report: dict[str, Any], portal_org_id: str | None = None ) -> dict[str, Any]: check_items = [ { "name": str(item.get("name") or ""), "description": item.get("description"), "check_type": item.get("checkType"), "status": item.get("status"), "error_message": item.get("errorMessage"), } for item in report.get("checkItems", []) if isinstance(item, dict) ] return { "report_id": str(report.get("reportId") or ""), "strategy_id": report.get("strategyId"), "org_id": report.get("orgId"), "portal_org_id": report.get("portalOrgId") or portal_org_id, "cluster_id": report.get("clusterId"), "status": report.get("status"), "error_message": report.get("errorMessage"), "created_at": report.get("createdAt"), "updated_at": report.get("updatedAt"), "time_range_a_start": report.get("timeRangeAStart"), "time_range_a_end": report.get("timeRangeAEnd"), "time_range_b_start": report.get("timeRangeBStart"), "time_range_b_end": report.get("timeRangeBEnd"), "check_items": check_items, "importable_item_names": importable_check_names(report.get("checkItems")), "source_url": build_report_source_url( CLINIC_PORTAL_BASE, report, portal_org_id ), } def normalize_health_check_report_detail( report: dict[str, Any], portal_org_id: str | None = None ) -> dict[str, Any]: return { **normalize_health_check_report_summary( {**report, "checkItems": report.get("items", [])}, portal_org_id, ), "items": [ { "name": item.get("name"), "description": item.get("description"), "check_type": item.get("checkType"), "params": item.get("params"), "status": item.get("status"), "error_message": item.get("errorMessage"), "content": item.get("content"), } for item in report.get("items", []) if isinstance(item, dict) ], } def start_health_check_report_sync( org_id: str, cluster_id: str, report_id: str, item_names: list[str], timestamp: str, ) -> None: with get_conn() as conn: conn.execute( dialect_sql( conn, """ INSERT INTO health_check_report_syncs (id, org_id, cluster_id, report_id, state, selected_items_json, requested_by, started_at, updated_at) VALUES (?, ?, ?, ?, 'syncing', ?, ?, ?, ?) ON CONFLICT(org_id, cluster_id, report_id) DO UPDATE SET report_status = NULL, state = 'syncing', selected_items_json = excluded.selected_items_json, finding_run_id = NULL, finding_count = 0, created_count = 0, duplicate_count = 0, rejected_count = 0, catalog_created_count = 0, requested_by = excluded.requested_by, report_created_at = NULL, report_updated_at = NULL, error_message = NULL, started_at = excluded.started_at, completed_at = NULL, updated_at = excluded.updated_at """, """ INSERT INTO health_check_report_syncs (id, org_id, cluster_id, report_id, state, selected_items_json, requested_by, started_at, updated_at) VALUES (?, ?, ?, ?, 'syncing', ?, ?, ?, ?) ON DUPLICATE KEY UPDATE report_status = NULL, state = 'syncing', selected_items_json = VALUES(selected_items_json), finding_run_id = NULL, finding_count = 0, created_count = 0, duplicate_count = 0, rejected_count = 0, catalog_created_count = 0, requested_by = VALUES(requested_by), report_created_at = NULL, report_updated_at = NULL, error_message = NULL, started_at = VALUES(started_at), completed_at = NULL, updated_at = VALUES(updated_at) """, ), ( new_id("hcs"), org_id, cluster_id, report_id, json_dumps(item_names), current_user_id(), timestamp, timestamp, ), ) def finish_health_check_report_sync( context: dict[str, Any], result: dict[str, Any] ) -> None: completed_at = result["completed_at"] with get_conn() as conn: conn.execute( """ UPDATE health_check_report_syncs SET report_status = ?, state = ?, selected_items_json = ?, finding_run_id = ?, finding_count = ?, created_count = ?, duplicate_count = ?, rejected_count = ?, catalog_created_count = ?, report_created_at = ?, report_updated_at = ?, error_message = ?, completed_at = ?, updated_at = ? WHERE org_id = ? AND cluster_id = ? AND report_id = ? """, ( result.get("report_status"), result["status"], json_dumps(result.get("selected_item_names") or []), result.get("finding_run_id"), result.get("finding_count") or 0, result.get("created_count") or 0, result.get("duplicate_count") or 0, result.get("rejected_count") or 0, result.get("catalog_created_count") or 0, result.get("report_created_at"), result.get("report_updated_at"), result.get("error_message"), completed_at, completed_at, context["dbaas_org_id"], context["cluster_id"], result["report_id"], ), ) def health_check_report_sync_projections( cluster_id: str, report_ids: list[str] ) -> dict[str, dict[str, Any]]: if not report_ids: return {} placeholders = ",".join("?" for _ in report_ids) with get_conn() as conn: sync_rows = conn.execute( f"SELECT * FROM health_check_report_syncs " f"WHERE cluster_id = ? AND report_id IN ({placeholders})", (cluster_id, *report_ids), ).fetchall() run_rows = conn.execute( f""" SELECT fr.id, fr.source_run_id, fr.status, fr.ingested_at, COUNT(f.id) AS finding_count, COALESCE(SUM(CASE WHEN f.is_new_digest = 1 THEN 1 ELSE 0 END), 0) AS catalog_created_count FROM finding_runs fr LEFT JOIN findings f ON f.finding_run_id = fr.id AND f.deleted_at IS NULL WHERE fr.source = 'clinic_health_check' AND fr.cluster_id = ? AND fr.source_run_id IN ({placeholders}) GROUP BY fr.id, fr.source_run_id, fr.status, fr.ingested_at """, (cluster_id, *report_ids), ).fetchall() projections = { row["report_id"]: { "state": row["state"], "finding_run_id": row["finding_run_id"], "finding_count": row["finding_count"], "created_count": row["created_count"], "duplicate_count": row["duplicate_count"], "rejected_count": row["rejected_count"], "catalog_created_count": row["catalog_created_count"], "selected_item_names": json_loads(row["selected_items_json"], []), "last_synced_at": row["completed_at"], "error_message": row["error_message"], "source": "sync_audit", } for row in sync_rows } for row in run_rows: projections.setdefault( row["source_run_id"], { "state": ( "succeeded" if row["status"] == "success" else "partial" ), "finding_run_id": row["id"], "finding_count": row["finding_count"], "created_count": row["finding_count"], "duplicate_count": 0, "rejected_count": 0, "catalog_created_count": row["catalog_created_count"], "selected_item_names": [], "last_synced_at": row["ingested_at"], "error_message": None, "source": "finding_run", }, ) return projections def unsynced_report_state() -> dict[str, Any]: return { "state": "not_synced", "finding_run_id": None, "finding_count": 0, "created_count": 0, "duplicate_count": 0, "rejected_count": 0, "catalog_created_count": 0, "selected_item_names": [], "last_synced_at": None, "error_message": None, "source": "none", } def strict_positive_query_int( params: dict[str, list[str]], key: str, default: int, maximum: int ) -> int: values = params.get(key) if not values: return default if len(values) != 1: raise ValueError(f"{key} must be specified once") try: value = int(values[0]) except (TypeError, ValueError) as exc: raise ValueError(f"{key} must be an integer") from exc if value < 1 or value > maximum: raise ValueError(f"{key} must be between 1 and {maximum}") return value def validate_health_check_resource_id(value: Any, field: str) -> str: if not isinstance(value, str) or not value.strip(): raise ValueError(f"{field} is required") result = value.strip() if len(result) > 256: raise ValueError(f"{field} must be at most 256 characters") if any(ord(character) < 32 for character in result): raise ValueError(f"{field} contains invalid characters") return result def cluster_health_bucket(value: str | None, timezone_offset: int) -> str | None: timestamp = try_datetime(value) if timestamp is None: return None return iso_datetime(day_bucket_start(timestamp, timezone_offset)) def cluster_health_period( observation_values: list[str | None], intake_values: list[str | None], timezone_offset: int, fallback_anchor: datetime | None = None, ) -> tuple[datetime, datetime]: observations = [ timestamp for value in observation_values if (timestamp := try_datetime(value)) is not None ] intakes = [ timestamp for value in intake_values if (timestamp := try_datetime(value)) is not None ] observation_anchor = max(observations, default=None) intake_anchor = max(intakes, default=None) if observation_anchor is not None: period_end = day_bucket_start( observation_anchor, timezone_offset ) + timedelta(days=1) # A normal daily report can arrive on the next local day. Do not let # that intake timestamp add an empty observation day to the window. if intake_anchor is not None: intake_bucket = day_bucket_start(intake_anchor, timezone_offset) if intake_bucket > period_end: period_end = intake_bucket + timedelta(days=1) else: anchor = intake_anchor or fallback_anchor or datetime.now(timezone.utc) period_end = day_bucket_start(anchor, timezone_offset) + timedelta(days=1) return period_end - timedelta(days=14), period_end def numeric_metric(value: Any) -> float | None: if isinstance(value, bool) or not isinstance(value, (int, float)): return None return float(value) def average_covered(values: list[float | int | None]) -> float | None: present = [float(value) for value in values if isinstance(value, (int, float))] return sum(present) / len(present) if present else None def relative_change(current: float | None, previous: float | None) -> float | None: if current is None or previous is None: return None if previous == 0: return 0.0 if current == 0 else 1.0 return (current - previous) / previous def cluster_health_direction( series: list[dict[str, Any]], ) -> dict[str, Any]: previous = series[:7] current = series[7:] previous_coverage = sum(1 for point in previous if point["covered"]) current_coverage = sum(1 for point in current if point["covered"]) comparison = { "previous_coverage_days": previous_coverage, "current_coverage_days": current_coverage, } if previous_coverage < 2 or current_coverage < 2: return { "state": "insufficient_data", "reasons": ["insufficient_comparable_coverage"], "comparison": comparison, } def covered_average( points: list[dict[str, Any]], key: str, coverage_key: str ) -> float | None: return average_covered( [point[key] if point[coverage_key] else None for point in points] ) previous_risk = covered_average(previous, "risk_weight", "intake_covered") current_risk = covered_average(current, "risk_weight", "intake_covered") previous_slow = covered_average(previous, "slow_log_count", "covered") current_slow = covered_average(current, "slow_log_count", "covered") previous_findings = covered_average( previous, "finding_count", "intake_covered" ) current_findings = covered_average(current, "finding_count", "intake_covered") risk_change = relative_change(current_risk, previous_risk) slow_change = relative_change(current_slow, previous_slow) finding_change = relative_change(current_findings, previous_findings) comparison.update( { "previous_risk_per_day": round(previous_risk or 0, 2), "current_risk_per_day": round(current_risk or 0, 2), "risk_change_percent": round(risk_change * 100, 1) if risk_change is not None else None, "previous_slow_log_per_day": round(previous_slow or 0, 2), "current_slow_log_per_day": round(current_slow or 0, 2), "slow_log_change_percent": round(slow_change * 100, 1) if slow_change is not None else None, "previous_findings_per_day": round(previous_findings or 0, 2), "current_findings_per_day": round(current_findings or 0, 2), "finding_change_percent": round(finding_change * 100, 1) if finding_change is not None else None, } ) reasons: list[str] = [] if risk_change is not None and risk_change >= 0.25 and (current_risk or 0) > 0: reasons.append("severe_findings_up") elif risk_change is not None and risk_change <= -0.2: reasons.append("severe_findings_down") if slow_change is not None and slow_change >= 0.35 and (current_slow or 0) > 0: reasons.append("slow_log_up") elif slow_change is not None and slow_change <= -0.25: reasons.append("slow_log_down") if finding_change is not None and finding_change >= 0.3 and (current_findings or 0) > 0: reasons.append("finding_inflow_up") elif finding_change is not None and finding_change <= -0.25: reasons.append("finding_inflow_down") worsening = any(reason.endswith("_up") for reason in reasons) improving = any(reason.endswith("_down") for reason in reasons) if worsening and not improving: state = "worsening" elif improving and not worsening: state = "improving" else: state = "stable" if not reasons: reasons.append("no_material_change") elif worsening and improving: reasons.insert(0, "mixed_signals") return {"state": state, "reasons": reasons[:3], "comparison": comparison} def cluster_health_risk( items: list[dict[str, Any]], coverage_days: int, active_treatment_count: int ) -> dict[str, Any]: active_items = [ item for item in items if item["current_posture"]["state"] != "archived" ] decision_items = [ item for item in active_items if catalog_projection_review_eligible(item) and item["current_posture"]["state"] == "needs_review" and not item["current_posture"]["active_treatment_count"] ] priority_items = { tier: [ item for item in decision_items if item["current_posture"]["review_priority"]["tier"] == tier ] for tier in REVIEW_PRIORITY_TIERS } critical_items = [ item for item in active_items if catalog_projection_review_eligible(item) and item["current_posture"].get("risk") == "critical" ] high_items = [ item for item in active_items if catalog_projection_review_eligible(item) and item["current_posture"].get("risk") == "high" ] untreated_critical = [ item for item in critical_items if not item["current_posture"]["active_treatment_count"] ] reasons: list[str] = [] if priority_items["p0"]: level = "urgent" reasons.append("immediate_review_present") elif priority_items["p1"]: level = "high" reasons.append("priority_review_present") elif active_treatment_count: level = "attention" reasons.append("active_treatment_present") elif coverage_days >= 4: level = "clear" reasons.append("no_material_unhandled_risk") else: level = "insufficient_data" reasons.append("insufficient_recent_coverage") return { "level": level, "reasons": reasons, "critical_sql_count": len(critical_items), "high_sql_count": len(high_items), "untreated_critical_count": len(untreated_critical), "p0_count": len(priority_items["p0"]), "p1_count": len(priority_items["p1"]), "priority_count": len(priority_items["p0"]) + len(priority_items["p1"]), "todo_count": len(priority_items["p0"]) + len(priority_items["p1"]), "active_treatment_count": active_treatment_count, "excluded_non_tunable_count": sum( 1 for item in active_items if not catalog_projection_review_eligible(item) ), } def workbench_cluster_selection( conn: sqlite3.Connection, params: dict[str, list[str]] ) -> tuple[dict[str, dict[str, Any]], list[str]]: requested_clusters = param_values(params, "cluster_id") requested_orgs = set(param_values(params, "org_id")) if requested_clusters: cluster_ids = list(dict.fromkeys(requested_clusters)) placeholders = ",".join("?" for _ in cluster_ids) metadata_rows = conn.execute( f""" SELECT cluster_id, cluster_name, COALESCE(clinic_org_id, tenant_id) AS org_id, org_name, COALESCE(tenant_id, clinic_org_id) AS tenant_id, metadata_json, fetched_at FROM cluster_metadata WHERE cluster_id IN ({placeholders}) """, cluster_ids, ).fetchall() metadata_ids = {row["cluster_id"] for row in metadata_rows} missing_ids = [cluster_id for cluster_id in cluster_ids if cluster_id not in metadata_ids] scope_rows = [] if missing_ids: missing_placeholders = ",".join("?" for _ in missing_ids) scope_rows = conn.execute( f""" SELECT cluster_id, cluster_name, org_id, org_name, NULL AS tenant_id, NULL AS metadata_json, NULL AS fetched_at FROM cluster_scope_members WHERE cluster_id IN ({missing_placeholders}) ORDER BY created_at, id """, missing_ids, ).fetchall() directory: dict[str, dict[str, Any]] = { cluster_id: { "cluster_id": cluster_id, "cluster_name": cluster_id, "org_id": None, "org_name": None, "tenant_id": None, "provider": None, "region": None, "customer_region": None, "lifecycle": "unknown", "last_seen_at": None, "metadata_updated_at": None, } for cluster_id in cluster_ids } # Saved scope rows provide a readable fallback; canonical metadata wins. for row in [*scope_rows, *metadata_rows]: candidate = directory[row["cluster_id"]] metadata = ensure_dict(json_loads(row["metadata_json"], {})) candidate.update( { "cluster_name": row["cluster_name"] or candidate["cluster_name"], "org_id": row["org_id"] or candidate.get("org_id"), "org_name": row["org_name"] or candidate.get("org_name"), "tenant_id": row["tenant_id"] or candidate.get("tenant_id"), "provider": metadata.get("cloud_provider") or metadata.get("provider") or candidate.get("provider"), "region": metadata.get("region") or candidate.get("region"), "customer_region": metadata.get("customer_region") or candidate.get("customer_region"), "lifecycle": str( metadata.get("lifecycle") or metadata.get("status") or candidate.get("lifecycle") or "unknown" ).lower(), "metadata_updated_at": row["fetched_at"] or candidate.get("metadata_updated_at"), } ) return directory, cluster_ids directory = cluster_directory_candidates(conn) if requested_orgs: cluster_ids = [ cluster_id for cluster_id, candidate in directory.items() if requested_orgs.intersection( str(value) for value in (candidate.get("org_id"), candidate.get("tenant_id")) if value ) ] else: cluster_ids = list(directory) return directory, list(dict.fromkeys(cluster_ids)) def workbench_attention( params: dict[str, list[str]], timezone_offset: int ) -> dict[str, Any]: scope_params = workbench_scope_params(params) with get_conn() as conn: directory, cluster_ids = workbench_cluster_selection(conn, scope_params) catalog_where, catalog_values = catalog_filter_sql(scope_params) catalog_rows = conn.execute( "SELECT ci.* FROM catalog_items ci" + catalog_where, catalog_values, ).fetchall() catalog_items, _ = project_catalog_items(conn, catalog_rows) active_items = [ item for item in catalog_items if item["current_posture"]["state"] != "archived" ] catalog_by_cluster: dict[str, list[dict[str, Any]]] = defaultdict(list) for item in active_items: catalog_by_cluster[item["cluster_id"]].append(item) owners: dict[str, list[str]] = defaultdict(list) runs_by_cluster: dict[str, list[sqlite3.Row]] = defaultdict(list) observation_anchors: dict[str, list[str | None]] = defaultdict(list) intake_anchors: dict[str, list[str | None]] = defaultdict(list) active_treatments_by_cluster: dict[str, set[str]] = defaultdict(set) if cluster_ids: placeholders = ",".join("?" for _ in cluster_ids) for row in conn.execute( f"SELECT * FROM cluster_sql_health_owners " f"WHERE cluster_id IN ({placeholders}) ORDER BY owner_id", cluster_ids, ).fetchall(): owners[row["cluster_id"]].append(row["owner_id"]) run_rows = conn.execute( f"SELECT cluster_id, time_window_end, ingested_at, status " f"FROM finding_runs WHERE cluster_id IN ({placeholders})", cluster_ids, ).fetchall() for row in run_rows: runs_by_cluster[row["cluster_id"]].append(row) observation_anchors[row["cluster_id"]].append(row["time_window_end"]) intake_anchors[row["cluster_id"]].append(row["ingested_at"]) finding_anchor_rows = conn.execute( f"SELECT cluster_id, " f"MAX(COALESCE(time_window_end, observed_at, created_at)) AS observation_at, " f"MAX(created_at) AS intake_at FROM findings " f"WHERE deleted_at IS NULL AND cluster_id IN ({placeholders}) " f"GROUP BY cluster_id", cluster_ids, ).fetchall() for row in finding_anchor_rows: observation_anchors[row["cluster_id"]].append(row["observation_at"]) intake_anchors[row["cluster_id"]].append(row["intake_at"]) active_treatment_rows = conn.execute( f""" SELECT ci.cluster_id, ci.id AS catalog_item_id, t.id AS treatment_id FROM treatments t JOIN relations r ON r.from_type = 'treatment' AND r.from_id = t.id AND r.relation_type = 'treatment_for' AND r.to_type = 'catalog_item' JOIN catalog_items ci ON ci.id = r.to_id WHERE t.state = 'active' AND ci.cluster_id IN ({placeholders}) """, cluster_ids, ).fetchall() eligible_catalog_ids = { item["id"] for item in active_items if catalog_projection_review_eligible(item) } for row in active_treatment_rows: if row["catalog_item_id"] in eligible_catalog_ids: active_treatments_by_cluster[row["cluster_id"]].add( row["treatment_id"] ) fallback_anchor = datetime.now(timezone.utc) periods_by_cluster = { cluster_id: cluster_health_period( observation_anchors.get(cluster_id, []), intake_anchors.get(cluster_id, []), timezone_offset, fallback_anchor, ) for cluster_id in cluster_ids } result_items: list[dict[str, Any]] = [] for cluster_id in cluster_ids: period_start, period_end = periods_by_cluster[cluster_id] covered_buckets = { bucket for row in runs_by_cluster.get(cluster_id, []) if row["status"] in {"success", "partial"} and (bucket := cluster_health_bucket(row["time_window_end"], timezone_offset)) and iso_datetime(period_start) <= bucket < iso_datetime(period_end) } coverage_days = len(covered_buckets) active_treatment_count = len(active_treatments_by_cluster[cluster_id]) identity = directory.get( cluster_id, { "cluster_id": cluster_id, "cluster_name": cluster_id, "org_id": None, "org_name": None, "provider": None, "region": None, "lifecycle": "unknown", }, ) result_items.append( { **identity, "owners": owners.get(cluster_id, []), "health": cluster_health_risk( catalog_by_cluster.get(cluster_id, []), coverage_days, active_treatment_count, ), "period": { "from": iso_datetime(period_start), "to": iso_datetime(period_end), }, "coverage_days": coverage_days, "last_report_at": max( ( row["ingested_at"] for row in runs_by_cluster.get(cluster_id, []) if row["ingested_at"] ), default=None, ), } ) health_order = { "urgent": 0, "high": 1, "attention": 2, "insufficient_data": 3, "clear": 4, } result_items.sort( key=lambda item: ( health_order.get(item["health"]["level"], 9), -item["health"]["priority_count"], str(item.get("cluster_name") or item["cluster_id"]), ) ) period_starts = [value[0] for value in periods_by_cluster.values()] period_ends = [value[1] for value in periods_by_cluster.values()] cluster_health = { "period": { "from": iso_datetime(min(period_starts, default=fallback_anchor)), "to": iso_datetime(max(period_ends, default=fallback_anchor)), }, "data_as_of": max( ( item.get("last_report_at") for item in result_items if item.get("last_report_at") ), default=None, ), "summary": { "total_clusters": len(result_items), "needs_attention": sum( 1 for item in result_items if item["health"]["level"] in {"urgent", "high", "attention"} ), }, "items": result_items, } return { "cluster_health": cluster_health, "catalog_queue": workbench_catalog_queue(active_items), } def workbench_cluster_health_trends( params: dict[str, list[str]], timezone_offset: int ) -> dict[str, Any]: scope_params = workbench_scope_params(params) with get_conn() as conn: _, cluster_ids = workbench_cluster_selection(conn, scope_params) placeholders = ",".join("?" for _ in cluster_ids) observation_anchors: dict[str, list[str | None]] = defaultdict(list) intake_anchors: dict[str, list[str | None]] = defaultdict(list) if cluster_ids: run_anchor_rows = conn.execute( f"SELECT cluster_id, MAX(time_window_end) AS observation_at, " f"MAX(ingested_at) AS intake_at FROM finding_runs " f"WHERE cluster_id IN ({placeholders}) GROUP BY cluster_id", cluster_ids, ).fetchall() finding_anchor_rows = conn.execute( f"SELECT cluster_id, " f"MAX(COALESCE(time_window_end, observed_at, created_at)) " f"AS observation_at, MAX(created_at) AS intake_at " f"FROM findings WHERE deleted_at IS NULL " f"AND cluster_id IN ({placeholders}) GROUP BY cluster_id", cluster_ids, ).fetchall() for row in (*run_anchor_rows, *finding_anchor_rows): observation_anchors[row["cluster_id"]].append(row["observation_at"]) intake_anchors[row["cluster_id"]].append(row["intake_at"]) fallback_anchor = datetime.now(timezone.utc) periods_by_cluster = { cluster_id: cluster_health_period( observation_anchors.get(cluster_id, []), intake_anchors.get(cluster_id, []), timezone_offset, fallback_anchor, ) for cluster_id in cluster_ids } if periods_by_cluster: period_start = min(period[0] for period in periods_by_cluster.values()) period_end = max(period[1] for period in periods_by_cluster.values()) else: period_start, period_end = cluster_health_period( [], [], timezone_offset, fallback_anchor ) findings_by_cluster: dict[str, list[sqlite3.Row]] = defaultdict(list) runs_by_cluster: dict[str, list[sqlite3.Row]] = defaultdict(list) catalog_by_cluster: dict[str, list[dict[str, Any]]] = defaultdict(list) if cluster_ids: finding_rows = conn.execute( f"SELECT f.id, f.source, f.detector_code, f.severity, " "f.cluster_id, f.created_at, f.observed_at, f.time_window_end, " "f.finding_run_id, f.source_run_id, f.metrics_json, " "f.dimensions_json, f.normalized_sql, " "f.catalog_item_id, f.sql_digest, " "ci.normalized_sql AS catalog_normalized_sql " f"FROM findings f JOIN catalog_items ci ON ci.id = f.catalog_item_id " f"WHERE f.deleted_at IS NULL " f"AND f.cluster_id IN ({placeholders}) " "AND ((f.created_at >= ? AND f.created_at < ?) " "OR (COALESCE(f.observed_at, f.time_window_end) >= ? " "AND COALESCE(f.observed_at, f.time_window_end) < ?))", [ *cluster_ids, iso_datetime(period_start), iso_datetime(period_end), iso_datetime(period_start), iso_datetime(period_end), ], ).fetchall() for row in finding_rows: findings_by_cluster[row["cluster_id"]].append(row) run_rows = conn.execute( f"SELECT id, source_run_id, cluster_id, time_window_end, " "ingested_at, status FROM finding_runs " f"WHERE cluster_id IN ({placeholders}) " "AND ((ingested_at >= ? AND ingested_at < ?) " "OR (time_window_end >= ? AND time_window_end < ?)) " "ORDER BY ingested_at", [ *cluster_ids, iso_datetime(period_start), iso_datetime(period_end), iso_datetime(period_start), iso_datetime(period_end), ], ).fetchall() for row in run_rows: runs_by_cluster[row["cluster_id"]].append(row) catalog_where, catalog_values = catalog_filter_sql(scope_params) catalog_rows = conn.execute( "SELECT ci.id, ci.cluster_id, ci.created_at, ci.normalized_sql " "FROM catalog_items ci" + catalog_where, catalog_values, ).fetchall() for row in catalog_rows: item = dict(row) if catalog_projection_review_eligible(item): catalog_by_cluster[item["cluster_id"]].append(item) result_items: list[dict[str, Any]] = [] for cluster_id in cluster_ids: item_period_start, item_period_end = periods_by_cluster[cluster_id] buckets = [ iso_datetime(item_period_start + timedelta(days=index)) for index in range(14) ] covered_buckets = { cluster_health_bucket(row["time_window_end"], timezone_offset) for row in runs_by_cluster.get(cluster_id, []) if row["status"] in {"success", "partial"} } intake_covered_buckets = { cluster_health_bucket(row["ingested_at"], timezone_offset) for row in runs_by_cluster.get(cluster_id, []) if row["status"] in {"success", "partial"} } run_observation_buckets: dict[str, str | None] = {} for row in runs_by_cluster.get(cluster_id, []): bucket = cluster_health_bucket(row["time_window_end"], timezone_offset) run_observation_buckets[row["id"]] = bucket run_observation_buckets[row["source_run_id"]] = bucket daily_findings: dict[str, int] = defaultdict(int) daily_risk: dict[str, int] = defaultdict(int) slow_by_digest: dict[tuple[str, str, str], float] = {} for row in findings_by_cluster.get(cluster_id, []): finding = dict(row) if not finding.get("normalized_sql"): finding["normalized_sql"] = finding.get( "catalog_normalized_sql" ) review_eligible = finding_review_eligible(finding) intake_bucket = cluster_health_bucket(row["created_at"], timezone_offset) if intake_bucket and review_eligible: daily_findings[intake_bucket] += 1 if ( finding_signal_class(finding) == FINDING_SIGNAL_ANOMALY ): daily_risk[intake_bucket] += SEVERITY_RANK.get( row["severity"], 0 ) intake_covered_buckets.add(intake_bucket) metrics = ensure_dict(json_loads(row["metrics_json"], {})) slow_count = numeric_metric( metrics.get("slowlog_slow_count", metrics.get("slow_count")) ) run_key = row["finding_run_id"] or row["source_run_id"] or row["id"] observation_bucket = run_observation_buckets.get(str(run_key)) if observation_bucket is None: observation_bucket = cluster_health_bucket( row["observed_at"] or row["time_window_end"], timezone_offset, ) if review_eligible and slow_count is not None and observation_bucket: metric_key = ( observation_bucket, str(run_key), row["sql_digest"], ) slow_by_digest[metric_key] = max( slow_count, slow_by_digest.get(metric_key, 0.0) ) daily_slow: dict[str, float] = defaultdict(float) for (bucket, _, _), value in slow_by_digest.items(): daily_slow[bucket] += value daily_new_digests: dict[str, int] = defaultdict(int) for item in catalog_by_cluster.get(cluster_id, []): if not catalog_projection_review_eligible(item): continue bucket = cluster_health_bucket(item["created_at"], timezone_offset) if bucket in buckets: daily_new_digests[bucket] += 1 series = [] for bucket in buckets: covered = bucket in covered_buckets intake_covered = bucket in intake_covered_buckets series.append( { "bucket": bucket, "covered": covered, "intake_covered": intake_covered, "slow_log_count": round(daily_slow.get(bucket, 0), 2) if covered else None, "finding_count": ( daily_findings.get(bucket, 0) if intake_covered else None ), "new_digest_count": daily_new_digests.get(bucket, 0), "risk_weight": ( daily_risk.get(bucket, 0) if intake_covered else None ), } ) coverage_days = sum(1 for point in series if point["covered"]) direction = cluster_health_direction(series) result_items.append( { "cluster_id": cluster_id, "direction": direction, "series": series, "period": { "from": iso_datetime(item_period_start), "to": iso_datetime(item_period_end), }, "coverage_days": coverage_days, "last_report_at": max( (row["ingested_at"] for row in runs_by_cluster.get(cluster_id, [])), default=None, ), } ) direction_order = {"worsening": 0, "stable": 1, "insufficient_data": 2, "improving": 3} result_items.sort( key=lambda item: ( direction_order.get(item["direction"]["state"], 9), item["cluster_id"], ) ) return { "period": {"from": iso_datetime(period_start), "to": iso_datetime(period_end)}, "data_as_of": max( (item.get("last_report_at") for item in result_items if item.get("last_report_at")), default=None, ), "summary": { "total_clusters": len(result_items), "worsening": sum( 1 for item in result_items if item["direction"]["state"] == "worsening" ), "improving": sum( 1 for item in result_items if item["direction"]["state"] == "improving" ), "insufficient_data": sum( 1 for item in result_items if item["direction"]["state"] == "insufficient_data" ), }, "items": result_items, } def workbench_cluster_health( params: dict[str, list[str]], timezone_offset: int ) -> dict[str, Any]: attention = workbench_attention(params, timezone_offset)["cluster_health"] trends = workbench_cluster_health_trends(params, timezone_offset) trends_by_cluster = {item["cluster_id"]: item for item in trends["items"]} items = [] for item in attention["items"]: trend = trends_by_cluster.get(item["cluster_id"]) items.append( { **item, "direction": ( trend["direction"] if trend else { "state": "insufficient_data", "reasons": ["insufficient_comparable_coverage"], "comparison": {}, } ), "series": trend["series"] if trend else [], } ) health_order = { "urgent": 0, "high": 1, "attention": 2, "insufficient_data": 3, "clear": 4, } direction_order = { "worsening": 0, "stable": 1, "insufficient_data": 2, "improving": 3, } items.sort( key=lambda item: ( health_order.get(item["health"]["level"], 9), direction_order.get(item["direction"]["state"], 9), -item["health"]["priority_count"], str(item.get("cluster_name") or item["cluster_id"]), ) ) return { "period": trends["period"], "data_as_of": trends.get("data_as_of") or attention.get("data_as_of"), "summary": { **attention["summary"], "worsening": trends["summary"]["worsening"], "improving": trends["summary"]["improving"], "insufficient_data": sum( 1 for item in items if item["health"]["level"] == "insufficient_data" or item["direction"]["state"] == "insufficient_data" ), }, "items": items, } def workbench_treatment_queue(params: dict[str, list[str]]) -> dict[str, Any]: queue_params = merge_query_params(workbench_scope_params(params), state="active") queue_params["limit"] = ["100"] payload = list_treatments(queue_params) items = list(payload["items"]) items.sort( key=lambda item: ( 0 if item.get("is_observation_due") else 1, -(float(item.get("stage_age_hours") or 0)), item["updated_at"], ) ) return { "total": payload["total"], "items": [ { "id": item["id"], "treatment_no": item["treatment_no"], "title": item["title"], "stage": item["stage"], "severity": item.get("severity"), "owner": item.get("owner"), "assignee": item.get("assignee"), "stage_age_hours": item.get("stage_age_hours"), "is_observation_due": item.get("is_observation_due", False), "catalog_items": item.get("catalog_items", []), "updated_at": item["updated_at"], } for item in items[:8] ], } def workbench_period_outcomes(params: dict[str, list[str]]) -> dict[str, Any]: timezone_offset = timezone_offset_minutes(params) ( period_start, period_end, comparison_start, comparison_end, comparison_mode, ) = treatment_reporting_bounds(params, timezone_offset) treatment = treatment_stats(params) with get_conn() as conn: outcome_scope = workbench_outcome_scope( conn, params, period_start, period_end ) current_coverage = finding_run_coverage( conn, params, iso_datetime(period_start), iso_datetime(period_end), "created", ) comparison_coverage = finding_run_coverage( conn, params, iso_datetime(comparison_start), iso_datetime(comparison_end), "created", ) comparison_quality = inspection_comparison_quality( current_coverage, comparison_coverage ) treatment_summary = treatment["summary"] completed = treatment_summary["completed_treatments"] outcomes = { "recommendations_shared": treatment_summary["recommendations_shared"], "closed_treatments": treatment_summary["closed_treatments"], "successful_treatments": treatment_summary["successful_treatments"], "success_rate": ( round(treatment_summary["successful_treatments"] / completed, 3) if completed else None ), "median_completion_time_hours": treatment_summary[ "median_completion_time_hours" ], **outcome_scope, "deltas": { key: ( treatment["deltas"][key] if comparison_quality["comparable"] else None ) for key in ( "recommendations_shared", "closed_treatments", "successful_treatments", ) }, } return { "timezone_offset_minutes": timezone_offset, "comparison_mode": comparison_mode, "period": { "from": iso_datetime(period_start), "to": iso_datetime(period_end), }, "comparison_period": { "from": iso_datetime(comparison_start), "to": iso_datetime(comparison_end), }, "comparison_quality": comparison_quality, "outcomes": outcomes, "treatment_flow": {"time_series": treatment["time_series"]}, } def workbench(params: dict[str, list[str]]) -> dict[str, Any]: timezone_offset = timezone_offset_minutes(params) period_start, period_end, comparison_start, comparison_end, comparison_mode = treatment_reporting_bounds( params, timezone_offset ) treatment = treatment_stats(params) treatment_queue = workbench_treatment_queue(params) with get_conn() as conn: catalog_where, catalog_values = catalog_filter_sql(params) catalog_rows = conn.execute( "SELECT ci.* FROM catalog_items ci" + catalog_where, catalog_values, ).fetchall() event_sequence_sql = timeline_sequence_sql(conn, "e") event_rows = conn.execute( f"SELECT e.*, {event_sequence_sql} AS event_sequence " "FROM timeline_events e " "JOIN catalog_items ci ON ci.id = e.target_id AND e.target_type = 'catalog_item'" + catalog_where + f" ORDER BY e.created_at, {event_sequence_sql}", catalog_values, ).fetchall() catalog_events = [row_to_timeline(row) for row in event_rows] enrich_catalog_event_governance_projection(conn, catalog_events) catalog_items, catalog_review_policies = project_catalog_items( conn, catalog_rows, catalog_events ) outcome_scope = workbench_outcome_scope(conn, params, period_start, period_end) current_coverage = finding_run_coverage( conn, params, iso_datetime(period_start), iso_datetime(period_end), "created", ) comparison_coverage = finding_run_coverage( conn, params, iso_datetime(comparison_start), iso_datetime(comparison_end), "created", ) review_current = catalog_review_period_aggregate( catalog_events, period_start=period_start, period_end=period_end, timezone_offset=timezone_offset, review_policies=catalog_review_policies, ) review_comparison = catalog_review_period_aggregate( catalog_events, period_start=comparison_start, period_end=comparison_end, timezone_offset=timezone_offset, review_policies=catalog_review_policies, ) review_delta_keys = ( "review_inflow", "review_handled", "backlog_end", "net_backlog_change", "critical_backlog_end", "critical_backlog_change", ) comparison_quality = inspection_comparison_quality( current_coverage, comparison_coverage ) review_deltas = { key: ( metric_delta( review_current["summary"][key], review_comparison["summary"][key] ) if comparison_quality["comparable"] else None ) for key in review_delta_keys } active_items = [ item for item in catalog_items if item["current_posture"]["state"] != "archived" ] catalog_queue = workbench_catalog_queue(active_items) critical_without_treatment = sum( 1 for item in active_items if item["current_posture"].get("risk") == "critical" and not item["current_posture"]["active_treatment_count"] ) critical_history = sum( 1 for item in active_items if item["current_posture"].get("risk") != "critical" and item["current_posture"].get("unreviewed_peak_risk") == "critical" and not item["current_posture"]["active_treatment_count"] ) stalled_treatments = treatment["current_snapshot"]["active_older_than_7d"] observation_due = treatment["current_snapshot"]["observation_due_treatments"] follow_up = sum( entry["count"] for entry in treatment["stage_health"] if entry["stage"] == "alignment" ) + observation_due bottlenecks = [ { "code": "critical_without_treatment", "count": critical_without_treatment, "tone": "danger", "target": "catalog", "filters": {"risk": "critical", "has_active_treatment": "false"}, }, { "code": "critical_history", "count": critical_history, "tone": "attention", "target": "catalog", "filters": {"queue": "critical_history"}, }, { "code": "stalled_treatments", "count": stalled_treatments, "tone": "attention", "target": "treatments_insights", "filters": {}, }, { "code": "observation_due", "count": observation_due, "tone": "attention", "target": "treatments", "filters": {"observation_due": "true"}, }, { "code": "follow_up", "count": follow_up, "tone": "attention", "target": "treatments", "filters": {"queue": "follow_up"}, }, ] bottlenecks = [item for item in bottlenecks if item["count"] > 0] bottlenecks.sort( key=lambda item: ( 0 if item["tone"] == "danger" else 1, -item["count"], item["code"], ) ) treatment_summary = treatment["summary"] completed = treatment_summary["completed_treatments"] outcomes = { "recommendations_shared": treatment_summary["recommendations_shared"], "closed_treatments": treatment_summary["closed_treatments"], "successful_treatments": treatment_summary["successful_treatments"], "success_rate": ( round(treatment_summary["successful_treatments"] / completed * 100, 1) if completed else None ), "median_completion_time_hours": treatment_summary["median_completion_time_hours"], **outcome_scope, "deltas": { key: ( treatment["deltas"][key] if comparison_quality["comparable"] else None ) for key in ( "recommendations_shared", "closed_treatments", "successful_treatments", ) }, } return { "timezone_offset_minutes": timezone_offset, "comparison_mode": comparison_mode, "period": {"from": iso_datetime(period_start), "to": iso_datetime(period_end)}, "comparison_period": { "from": iso_datetime(comparison_start), "to": iso_datetime(comparison_end), }, "comparison_quality": comparison_quality, "assessment": workbench_assessment( review_current["summary"], treatment_summary, stalled_treatments=stalled_treatments, observation_due=observation_due, comparison_quality=comparison_quality, ), "review_flow": { "summary": review_current["summary"], "comparison": review_comparison["summary"], "deltas": review_deltas, "time_series": review_current["time_series"], }, "treatment_flow": { "summary": treatment_summary, "comparison": treatment["comparison"], "deltas": { key: value if comparison_quality["comparable"] else None for key, value in treatment["deltas"].items() }, "current_snapshot": treatment["current_snapshot"], "time_series": treatment["time_series"], "stage_health": treatment["stage_health"], }, "outcomes": outcomes, "treatment_queue": treatment_queue, "bottlenecks": bottlenecks[:4], "catalog_queue": catalog_queue, } class AppHandler(BaseHTTPRequestHandler): server_version = "SQLCatalog/0.1" def handle_one_request(self) -> None: self._request_started_at = time.monotonic() super().handle_one_request() def log_message(self, fmt: str, *args: Any) -> None: sys.stderr.write( json.dumps( { "timestamp": now_iso(), "level": "info", "event": "http_request", "remote_addr": self.client_address[0], "duration_ms": round( (time.monotonic() - self._request_started_at) * 1000 ), "message": fmt % args, }, ensure_ascii=True, ) + "\n" ) sys.stderr.flush() def _locale(self) -> str: return negotiate_locale(self.headers.get("Accept-Language")) def _historical_replay_at(self) -> str | None: return historical_replay_at(self.headers.get(HISTORICAL_REPLAY_HEADER)) def _authenticate_api_request(self, path: str) -> Token[dict[str, Any] | None] | None: if path in { "/api/v1/healthz", "/api/v1/healthz/live", "/api/v1/healthz/ready", } or not path.startswith("/api/v1/"): return None principal = get_authenticator().authenticate(self.headers.get("Authorization")) return REQUEST_USER.set(ensure_authenticated_user(principal)) @staticmethod def _finish_authenticated_request(token: Token[dict[str, Any] | None] | None) -> None: if token is not None: REQUEST_USER.reset(token) def _send_auth_error(self, exc: AuthError) -> None: self._send_json(exc.status, {"error": exc.code, "message": exc.message}) def _send_json(self, status: int, payload: dict[str, Any]) -> None: locale = self._locale() if status >= 400 and isinstance(payload.get("error"), str): payload = localize_error(payload, locale) body = json_dumps(payload).encode("utf-8") self.send_response(status) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(body))) origin = (self.headers.get("Origin") or "").rstrip("/") if origin and origin in CORS_ALLOWED_ORIGINS: self.send_header("Access-Control-Allow-Origin", origin) self.send_header( "Access-Control-Allow-Headers", "authorization, content-type, accept-language, x-sql-catalog-replay-at", ) self.send_header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS") self.send_header("Cache-Control", "no-store") self.send_header("Content-Language", locale) self.send_header( "Vary", "Accept-Language, Origin" if origin else "Accept-Language" ) self.send_header("X-Content-Type-Options", "nosniff") self.send_header("Referrer-Policy", "strict-origin-when-cross-origin") self.end_headers() self.wfile.write(body) def _read_json(self) -> dict[str, Any]: length = int(self.headers.get("Content-Length") or 0) if length > MAX_REQUEST_BYTES: raise ValueError(f"Request body exceeds {MAX_REQUEST_BYTES} bytes") if length == 0: return {} raw = self.rfile.read(length).decode("utf-8") try: data = json.loads(raw) except json.JSONDecodeError as exc: raise ValueError(f"Invalid JSON: {exc}") from exc if not isinstance(data, dict): raise ValueError("JSON body must be an object") return data def do_OPTIONS(self) -> None: origin = (self.headers.get("Origin") or "").rstrip("/") if origin and origin not in CORS_ALLOWED_ORIGINS: self._send_json(HTTPStatus.FORBIDDEN, {"error": "forbidden"}) return self._send_json(200, {"ok": True}) def do_HEAD(self) -> None: path = urlparse(self.path).path if path.startswith("/api/"): self.send_response(HTTPStatus.METHOD_NOT_ALLOWED) self.send_header("Allow", "GET") self.send_header("Content-Length", "0") self.end_headers() return self._serve_static(path, include_body=False) def do_GET(self) -> None: parsed = urlparse(self.path) path = parsed.path params = parse_qs(parsed.query) request_user_token: Token[dict[str, Any] | None] | None = None try: request_user_token = self._authenticate_api_request(path) if path == "/api/v1/healthz/live": self._send_json(HTTPStatus.OK, {"ok": True, "status": "live"}) elif path in {"/api/v1/healthz", "/api/v1/healthz/ready"}: status, payload = readiness_status() self._send_json(status, payload) elif path == "/api/v1/auth/me": self._send_json(200, {"user": current_user()}) elif path == "/api/v1/users": self._send_json(200, list_users()) elif path == "/api/v1/workbench/attention": self._send_json( 200, workbench_attention(params, timezone_offset_minutes(params)), ) elif path == "/api/v1/workbench/cluster-health/trends": self._send_json( 200, workbench_cluster_health_trends( params, timezone_offset_minutes(params) ), ) elif path == "/api/v1/workbench/treatment-queue": self._send_json(200, workbench_treatment_queue(params)) elif path == "/api/v1/workbench/outcomes": self._send_json(200, workbench_period_outcomes(params)) elif path == "/api/v1/workbench": self._send_json(200, workbench(params)) elif path == "/api/v1/workbench/cluster-health": self._send_json( 200, workbench_cluster_health( params, timezone_offset_minutes(params) ), ) elif path == "/api/v1/findings": self._send_json(200, list_findings(params)) elif path == "/api/v1/findings/stats": self._send_json(200, finding_stats(params)) elif path == "/api/v1/symptom-definitions": self._send_json(200, list_symptom_definitions(params, self._locale())) elif path == "/api/v1/finding-runs": self._send_json(200, list_finding_runs(params)) elif path == "/api/v1/cluster-metadata": self._send_json(200, cluster_metadata(params)) elif path == "/api/v1/cluster-scopes": self._send_json(200, cluster_scope_library()) elif path == "/api/v1/scopes": self._send_json(200, scope_library()) elif path == "/api/v1/clinic/scopes/search": status, payload = clinic_scope_search(params) self._send_json(status, payload) elif path == "/api/v1/clinic/scopes/resolve": status, payload = clinic_scope_resolve(params) self._send_json(status, payload) elif match := re.fullmatch( r"/api/v1/clinic/organizations/([^/]+)/clusters", path ): status, payload = clinic_organization_clusters(match.group(1), params) self._send_json(status, payload) elif match := re.fullmatch(r"/api/v1/cluster-groups/([^/]+)", path): status, payload = cluster_group_detail(match.group(1)) self._send_json(status, payload) elif match := re.fullmatch( r"/api/v1/cluster-scopes/([^/]+)/cluster-configurations", path ): status, payload = cluster_scope_configurations(match.group(1)) self._send_json(status, payload) elif match := re.fullmatch(r"/api/v1/cluster-scopes/([^/]+)", path): status, payload = cluster_scope_detail(match.group(1)) self._send_json(status, payload) elif match := re.fullmatch( r"/api/v1/clusters/([^/]+)/configuration", path ): status, payload = get_cluster_configuration(match.group(1)) self._send_json(status, payload) elif match := re.fullmatch( r"/api/v1/clusters/([^/]+)/health-check/reports/([^/]+)", path ): status, payload = health_check_report_detail( match.group(1), match.group(2), params ) self._send_json(status, payload) elif match := re.fullmatch( r"/api/v1/clusters/([^/]+)/health-check/reports", path ): status, payload = health_check_report_list(match.group(1), params) self._send_json(status, payload) elif match := re.fullmatch(r"/api/v1/findings/([^/]+)", path): self._get_finding(match.group(1)) elif path == "/api/v1/catalog-items": self._send_json(200, list_catalog_items(params)) elif path == "/api/v1/catalog-items/stats": self._send_json(200, catalog_stats(params)) elif match := re.fullmatch(r"/api/v1/catalog-items/([^/]+)", path): status, payload = catalog_item_detail(match.group(1), self._locale()) self._send_json(status, payload) elif path == "/api/v1/treatments": self._send_json(200, list_treatments(params)) elif path == "/api/v1/treatments/stats": self._send_json(200, treatment_stats(params)) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)", path): status, payload = treatment_detail(match.group(1), self._locale()) self._send_json(status, payload) elif match := re.fullmatch(r"/api/v1/records/([^/]+)", path): status, payload = record_detail(match.group(1)) self._send_json(status, payload) else: self._serve_static(path) except AuthError as exc: self._send_auth_error(exc) except Exception as exc: # noqa: BLE001 - return useful demo errors. self._send_json(500, {"error": "internal_error", "message": str(exc)}) finally: self._finish_authenticated_request(request_user_token) def do_POST(self) -> None: parsed = urlparse(self.path) path = parsed.path request_user_token: Token[dict[str, Any] | None] | None = None try: request_user_token = self._authenticate_api_request(path) payload = bind_request_actor(self._read_json()) if path == "/api/v1/findings": status, body = create_finding( payload, received_at=self._historical_replay_at(), ) self._send_json(status, body) elif path == "/api/v1/catalog-items": status, body = create_catalog_item(payload) self._send_json(status, body) elif path == "/api/v1/finding-batches": status, body = create_finding_batch( payload, received_at=self._historical_replay_at(), ) self._send_json(status, body) elif path == "/api/v1/finding-deletions/preview": status, body = finding_deletion_preview(payload) self._send_json(status, body) elif path == "/api/v1/finding-deletions": status, body = delete_findings(payload) self._send_json(status, body) elif path == "/api/v1/finding-restorations": status, body = restore_findings(payload) self._send_json(status, body) elif path == "/api/v1/finding-runs": status, body = create_finding_run( payload, received_at=self._historical_replay_at(), ) self._send_json(status, body) elif path == "/api/v1/cluster-scopes/preview": status, body = cluster_scope_preview(payload) self._send_json(status, body) elif path == "/api/v1/cluster-scopes": status, body = create_cluster_scope(payload) self._send_json(status, body) elif match := re.fullmatch( r"/api/v1/clusters/([^/]+)/health-check/report-syncs", path ): status, body = queue_health_check_report_imports( match.group(1), payload ) self._send_json(status, body) elif match := re.fullmatch( r"/api/v1/cluster-scopes/([^/]+)/cluster-configurations/apply", path, ): status, body = apply_cluster_scope_configurations( match.group(1), payload ) self._send_json(status, body) elif path == "/api/v1/me/preferences/default-cluster-scope": status, body = set_default_cluster_scope(payload) self._send_json(status, body) elif path == "/api/v1/followed-scopes": status, body = create_followed_scope(payload) self._send_json(status, body) elif path == "/api/v1/cluster-groups": status, body = create_cluster_group(payload) self._send_json(status, body) elif path == "/api/v1/treatments": status, body = create_treatment(payload) self._send_json(status, body) elif path == "/api/v1/records": target_type = payload.pop("target_type", None) target_id = payload.pop("target_id", None) if not isinstance(target_type, str) or not isinstance(target_id, str): self._send_json(400, {"error": "record_target_required"}) else: status, body = create_record(target_type, target_id, payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/catalog-items/([^/]+)/treatments", path): status, body = create_treatment(payload, catalog_item_id=match.group(1)) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/catalog-items/([^/]+)/records", path): status, body = create_record("catalog_item", match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)/records", path): status, body = create_record("treatment", match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)/complete", path): status, body = complete_treatment(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/catalog-items/([^/]+)/triage", path): status, body = triage_catalog_item(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/catalog-items/([^/]+)/decision", path): status, body = decide_catalog_item(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)/transition", path): status, body = transition_treatment(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)/observations/start", path): status, body = start_observation(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)/reopen", path): status, body = reopen_treatment(match.group(1), payload) self._send_json(status, body) else: self._send_json(404, {"error": "not_found"}) except AuthError as exc: self._send_auth_error(exc) except PermissionError as exc: self._send_json(403, {"error": "historical_replay_forbidden", "message": str(exc)}) except ValueError as exc: self._send_json(400, {"error": "bad_request", "message": str(exc)}) except Exception as exc: # noqa: BLE001 - return useful demo errors. self._send_json(500, {"error": "internal_error", "message": str(exc)}) finally: self._finish_authenticated_request(request_user_token) def do_PATCH(self) -> None: parsed = urlparse(self.path) path = parsed.path request_user_token: Token[dict[str, Any] | None] | None = None try: request_user_token = self._authenticate_api_request(path) payload = bind_request_actor(self._read_json()) if match := re.fullmatch( r"/api/v1/clusters/([^/]+)/sql-health-owners", path ): status, body = update_cluster_sql_health_owners( match.group(1), payload ) self._send_json(status, body) elif match := re.fullmatch( r"/api/v1/clusters/([^/]+)/configuration", path ): status, body = update_cluster_configuration(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/catalog-items/([^/]+)", path): status, body = update_catalog_item(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/treatments/([^/]+)", path): status, body = update_treatment(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/records/([^/]+)", path): status, body = update_record(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/cluster-groups/([^/]+)", path): status, body = update_cluster_group(match.group(1), payload) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/cluster-scopes/([^/]+)", path): status, body = update_cluster_scope(match.group(1), payload) self._send_json(status, body) else: self._send_json(404, {"error": "not_found"}) except AuthError as exc: self._send_auth_error(exc) except ValueError as exc: self._send_json(400, {"error": "bad_request", "message": str(exc)}) except Exception as exc: # noqa: BLE001 - return useful demo errors. self._send_json(500, {"error": "internal_error", "message": str(exc)}) finally: self._finish_authenticated_request(request_user_token) def do_DELETE(self) -> None: parsed = urlparse(self.path) path = parsed.path request_user_token: Token[dict[str, Any] | None] | None = None try: request_user_token = self._authenticate_api_request(path) if match := re.fullmatch(r"/api/v1/followed-scopes/([^/]+)", path): status, body = delete_followed_scope(match.group(1)) self._send_json(status, body) elif match := re.fullmatch( r"/api/v1/clusters/([^/]+)/configuration", path ): status, body = reset_cluster_configuration(match.group(1)) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/cluster-groups/([^/]+)", path): status, body = delete_cluster_group(match.group(1)) self._send_json(status, body) elif match := re.fullmatch(r"/api/v1/cluster-scopes/([^/]+)", path): status, body = delete_cluster_scope(match.group(1)) self._send_json(status, body) else: self._send_json(404, {"error": "not_found"}) except AuthError as exc: self._send_auth_error(exc) except Exception as exc: # noqa: BLE001 - return useful demo errors. self._send_json(500, {"error": "internal_error", "message": str(exc)}) finally: self._finish_authenticated_request(request_user_token) def _get_finding(self, finding_id: str) -> None: status, payload = finding_detail(finding_id, self._locale()) self._send_json(status, payload) def _serve_static(self, path: str, *, include_body: bool = True) -> None: if path.startswith("/api/"): self._send_json(404, {"error": "not_found"}) return if path == "/": file_path = WEB_DIR / "index.html" else: relative = path.removeprefix("/") if relative.startswith("static/"): relative = relative.removeprefix("static/") file_path = WEB_DIR / relative try: file_path.resolve().relative_to(WEB_DIR.resolve()) except ValueError: self._send_json(403, {"error": "forbidden"}) return if not file_path.exists() or not file_path.is_file(): # Client-side routes need the SPA shell when the built app is served directly. if Path(path).suffix or not (WEB_DIR / "index.html").is_file(): self._send_json(404, {"error": "not_found"}) return file_path = WEB_DIR / "index.html" content_type = mimetypes.guess_type(str(file_path))[0] or "application/octet-stream" body = file_path.read_bytes() self.send_response(HTTPStatus.OK) self.send_header("Content-Type", content_type) self.send_header("Content-Length", str(len(body))) self.send_header("X-Content-Type-Options", "nosniff") self.send_header("X-Frame-Options", "DENY") self.send_header("Referrer-Policy", "strict-origin-when-cross-origin") if file_path.name == "index.html": self.send_header("Cache-Control", "no-cache") elif path.startswith("/assets/"): self.send_header("Cache-Control", "public, max-age=31536000, immutable") else: self.send_header("Cache-Control", "public, max-age=3600") self.end_headers() if include_body: self.wfile.write(body) def main(argv: list[str] | None = None) -> None: parser = argparse.ArgumentParser(description="Run or migrate SQL Catalog") parser.add_argument( "--migrate-only", action="store_true", help="apply database migrations and exit without starting the HTTP server", ) args = parser.parse_args(argv) init_db() if args.migrate_only: print(f"SQL Catalog database schema is ready at version {SCHEMA_VERSION}", flush=True) return if use_configured_database_url(): warm_mysql_pool( str(DATABASE_URL), DATABASE_PASSWORD_ENV, target_size=min(4, int(os.environ.get("SQL_CATALOG_DB_POOL_SIZE", "8"))), ) start_health_check_report_import_worker() httpd = ThreadingHTTPServer((HOST, PORT), AppHandler) httpd.daemon_threads = True def shutdown(signum: int, _frame: Any) -> None: print(f"Received signal {signum}; shutting down SQL Catalog", flush=True) _HEALTH_CHECK_IMPORT_STOP.set() _HEALTH_CHECK_IMPORT_WAKE.set() threading.Thread(target=httpd.shutdown, daemon=True).start() signal.signal(signal.SIGTERM, shutdown) signal.signal(signal.SIGINT, shutdown) print(f"SQL Catalog listening on http://{HOST}:{PORT}", flush=True) print( "Database: " + database_description( str(DATABASE_URL) if use_configured_database_url() else None, DB_PATH, ), flush=True, ) try: httpd.serve_forever(poll_interval=0.5) finally: httpd.server_close() stop_health_check_report_import_worker() if __name__ == "__main__": main()