# Catalog Governance Decisions

## Purpose

A repeated Finding is evidence, not automatically a new human TODO. A reviewer can record a
`watch` or `no_action` disposition with an explicit reopening policy. SQL Catalog snapshots the
evidence known at that decision and evaluates later anomaly Findings against it.

The decision remains auditable as a Record plus a `catalog_decision_recorded` Timeline event. It
does not overwrite or delete any Finding.

## Governance Relevance

Catalog responses expose `current_posture.governance_relevance`:

```json
{
  "review_eligible": false,
  "statement_type": "analyze",
  "reason": "non_tunable_statement"
}
```

Diagnostic, administrative, transaction-control, DDL, and maintenance statements such as
`ANALYZE`, `SHOW`, `EXPLAIN`, `ALTER`, and `COMMIT` remain in the Catalog with their original
Findings, metrics, and Timeline. They do not contribute to review admission, review priority,
Workbench TODOs, or cluster SQL health. Unknown statement types remain eligible so that an
unrecognized application query is not silently hidden.

Starting review or creating a new Treatment for an excluded Catalog Item returns HTTP `409` with
`error=catalog_item_not_review_eligible`. Existing Treatments remain readable and completable.

## 1. Create a Decision Record

Create a `triage_record` for `watch`, or a `no_action_record` for `no_action`:

```http
POST /api/v1/records
Content-Type: application/json
```

```json
{
  "target_type": "catalog_item",
  "target_id": "cat_...",
  "record_type": "no_action_record",
  "title": "Known stable workload",
  "review_status": "ready",
  "visibility": "internal",
  "structured_fields": {
    "conclusion_type": "known_stable",
    "confidence": "high",
    "reopen_policy": "meaningful_change",
    "review_after": "2026-09-01T00:00:00Z",
    "metric_guardrails": {
      "sql_tikv_high_cpu_total_topsql_cpu_seconds": {
        "increase_percent": 30
      }
    }
  },
  "body_markdown": "## Decision\n\nKnown business workload.\n\n## Rationale\n\nCPU time is stable.",
  "created_by": "reviewer@example.com"
}
```

| Field | Required | Meaning |
| --- | ---: | --- |
| `conclusion_type` | Yes | `watch`, `no_action`, `expected_workload`, `known_stable`, `not_optimizable`, `accepted_risk`, `false_positive`, or `obsolete`. |
| `confidence` | Yes | Human confidence in the conclusion. |
| `reopen_policy` | Yes | `meaningful_change` (default UI choice), `any_anomaly`, or `manual_review`. |
| `review_after` | No | ISO-8601 time at which the conclusion must be reviewed again. |
| `metric_guardrails` | No | Metric-keyed `increase_percent` and/or `above` rules. At most 32 metric keys. |

The Record must be `ready` or `reviewed` and contain substantive Markdown before it can be applied.

## 2. Apply the Disposition

```http
POST /api/v1/catalog-items/{catalog_item_id}/triage
Content-Type: application/json
```

```json
{
  "action": "no_action",
  "record_id": "rec_...",
  "actor": "reviewer@example.com"
}
```

Use `action=watch` with a related `triage_record`. The server captures the latest reviewed Finding,
known Symptoms, peak Severity, and baseline values for configured metric guardrails.

For migration of a historical review only, `reviewed_through_at` may specify the ISO-8601 evidence
cutoff. Findings after that cutoff are immediately evaluated as later evidence rather than silently
treated as reviewed.

## 3. Reopening Behavior

| Policy | Reopens when |
| --- | --- |
| `any_anomaly` | Any later anomaly Finding arrives. Legacy decisions use this conservative behavior. |
| `meaningful_change` | A new Symptom appears, Severity rises, a metric guardrail is breached, or `review_after` is due. |
| `manual_review` | `review_after` is due or a user explicitly starts another review. |

Ranking observations never reopen a decision. A covered Finding remains visible in Finding history
and metric trends, while `current_posture.unreviewed_anomaly_count` stays zero.

## 4. Read Projection

Catalog detail and list responses expose `current_posture.governance_memory` with:

- `status`: `active`, `change_detected`, or `review_due`;
- conclusion, reopening policy, Record, and review time;
- later evidence and covered Finding counts;
- trigger Finding, new Symptom codes, trigger reasons, and metric baseline/current values.

`change_detected` with current Critical risk is P0. Non-Critical meaningful change and review due are
P1. Active governance memory suppresses P0/P1/P2 queue admission but never suppresses source data.