{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/latitude-so/main/json-schema/latitude-so-signal-detail-schema.json",
  "title": "SignalDetail",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/latitude-so-openapi.json#/components/schemas/SignalDetail",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 24,
      "maxLength": 24,
      "description": "Stable signal identifier."
    },
    "organizationId": {
      "type": "string",
      "minLength": 24,
      "maxLength": 24,
      "description": "Organization that owns this signal."
    },
    "projectId": {
      "type": "string",
      "minLength": 24,
      "maxLength": 24,
      "description": "Project this signal belongs to."
    },
    "slug": {
      "type": "string",
      "description": "URL-safe slug derived from `name`. Unique within the project."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name."
    },
    "description": {
      "type": "string",
      "description": "Description of the signal."
    },
    "source": {
      "type": "string",
      "enum": [
        "annotation",
        "flagger",
        "custom"
      ],
      "description": "Where the signal originated from."
    },
    "scoreEvidence": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SignalScoreEvidence"
      },
      "description": "Agent Score dimension and evidence-role pairs informed by this signal. An empty list means the signal is diagnostic only."
    },
    "states": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "new",
          "escalating",
          "ongoing",
          "resolved",
          "regressed",
          "ignored"
        ]
      },
      "description": "Active lifecycle states. A signal may carry multiple states at once (e.g. `escalating` + `new`)."
    },
    "resolvedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO-8601 timestamp at which the signal was resolved, or `null`."
    },
    "ignoredAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO-8601 timestamp at which the signal was ignored, or `null`."
    },
    "regressedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO-8601 timestamp at which a new occurrence reopened the resolved signal, or `null`."
    },
    "mutedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO-8601 timestamp at which notifications were muted, or `null`. Muting only silences notifications; incidents still open."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO-8601 timestamp of creation."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO-8601 timestamp of the last update."
    },
    "trend": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SignalTrendBucket"
      },
      "description": "Daily occurrence counts over the past 14 days."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags seen on the signal's occurrences."
    },
    "firstSeenAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO-8601 timestamp of the earliest occurrence over the signal's lifetime, or `null` if none yet."
    },
    "lastSeenAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO-8601 timestamp of the latest occurrence over the signal's lifetime, or `null` if none yet."
    },
    "occurrences": {
      "type": "integer",
      "minimum": 0,
      "description": "Lifetime occurrence count."
    },
    "affectedSessionsPercent": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Lifetime fraction of project sessions affected by this signal, in `[0, 1]`."
    },
    "evaluations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Evaluation"
      },
      "description": "Active evaluations monitoring the signal. Archived and deleted evaluations are excluded."
    },
    "monitoringState": {
      "$ref": "#/$defs/SignalMonitoringState"
    },
    "feedback": {
      "$ref": "#/$defs/SignalFeedback"
    }
  },
  "required": [
    "id",
    "organizationId",
    "projectId",
    "slug",
    "name",
    "description",
    "source",
    "scoreEvidence",
    "states",
    "resolvedAt",
    "ignoredAt",
    "regressedAt",
    "mutedAt",
    "createdAt",
    "updatedAt",
    "trend",
    "tags",
    "firstSeenAt",
    "lastSeenAt",
    "occurrences",
    "affectedSessionsPercent",
    "evaluations",
    "monitoringState",
    "feedback"
  ],
  "$defs": {
    "Evaluation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 24,
          "maxLength": 24,
          "description": "Stable evaluation identifier."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name."
        },
        "description": {
          "type": "string",
          "description": "Generated description of the evaluation."
        },
        "alignedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 timestamp at which the evaluation was last realigned, or `null` if never aligned."
        },
        "archivedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 timestamp at which the evaluation was archived, or `null`."
        },
        "deletedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 timestamp at which the evaluation was deleted, or `null`."
        },
        "createdAt": {
          "type": "string",
          "description": "ISO-8601 timestamp of creation."
        },
        "updatedAt": {
          "type": "string",
          "description": "ISO-8601 timestamp of the last update."
        },
        "sampling": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Sampling rate as a percentage in `[0, 100]`. `0` means the evaluation is paused."
        },
        "alignment": {
          "$ref": "#/$defs/EvaluationAlignmentMetrics"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "alignedAt",
        "archivedAt",
        "deletedAt",
        "createdAt",
        "updatedAt",
        "sampling",
        "alignment"
      ]
    },
    "EvaluationAlignmentMetrics": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "alignmentMetric": {
          "type": "number",
          "description": "Headline score that judges how well the evaluation tracks human annotations."
        },
        "accuracy": {
          "type": "number",
          "description": "Accuracy: `(TP + TN) / total`."
        },
        "precision": {
          "type": "number",
          "description": "Precision: `TP / (TP + FP)`."
        },
        "recall": {
          "type": "number",
          "description": "Recall / sensitivity: `TP / (TP + FN)`."
        },
        "specificity": {
          "type": "number",
          "description": "Specificity: `TN / (TN + FP)`."
        },
        "trueness": {
          "type": "number",
          "description": "Mean of precision and negative predictive value."
        },
        "f1": {
          "type": "number",
          "description": "F1 score: harmonic mean of precision and recall."
        },
        "balancedAccuracy": {
          "type": "number",
          "description": "Balanced accuracy: mean of recall and specificity."
        },
        "matthewsCorrelationCoefficient": {
          "type": "number",
          "description": "Matthews correlation coefficient, in `[-1, 1]`."
        }
      },
      "required": [
        "alignmentMetric",
        "accuracy",
        "precision",
        "recall",
        "specificity",
        "trueness",
        "f1",
        "balancedAccuracy",
        "matthewsCorrelationCoefficient"
      ],
      "description": "Alignment metrics computed from the evaluation's confusion matrix, or `null` for an unaligned (e.g. raw / deterministic) evaluation."
    },
    "SignalFeedback": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "value": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Normalized score for the signal's usefulness, in `[0, 1]`."
        },
        "passed": {
          "type": "boolean",
          "description": "`true` when the signal is a real problem; `false` when it is a false positive."
        },
        "feedback": {
          "type": "string",
          "description": "Reason given for the verdict. Empty when none was provided."
        }
      },
      "required": [
        "value",
        "passed",
        "feedback"
      ],
      "description": "The verdict submitted for this signal, or `null` when none has been submitted yet."
    },
    "SignalMonitoringState": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "automatic"
              ]
            }
          },
          "required": [
            "kind"
          ],
          "description": "The signal is automatically monitored by the system and does not need an evaluation."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "idle"
              ]
            }
          },
          "required": [
            "kind"
          ],
          "description": "The signal is not currently being monitored."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "generating"
              ]
            }
          },
          "required": [
            "kind"
          ],
          "description": "An evaluation is being generated for this signal. The signal has no active evaluation yet."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "realigning"
              ]
            },
            "evaluationId": {
              "type": "string",
              "minLength": 24,
              "maxLength": 24,
              "description": "Id of the evaluation currently being realigned."
            }
          },
          "required": [
            "kind",
            "evaluationId"
          ],
          "description": "An active evaluation is being realigned."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "failed"
              ]
            },
            "phase": {
              "type": "string",
              "enum": [
                "generate",
                "realign"
              ],
              "description": "Which workflow failed: `generate` (creating the evaluation) or `realign` (updating it)."
            },
            "evaluationId": {
              "type": "string",
              "minLength": 24,
              "maxLength": 24,
              "description": "Id of the evaluation whose realignment failed. Absent when the failure was during `generate`."
            },
            "reason": {
              "type": [
                "string",
                "null"
              ],
              "description": "Resolved failure message, or `null` once Temporal has dropped the failed run."
            }
          },
          "required": [
            "kind",
            "phase",
            "reason"
          ],
          "description": "The most recent generation or realignment workflow for this signal ended in failure."
        }
      ],
      "description": "Whether the signal is currently being monitored: `automatic`, `idle`, `generating`, `realigning`, or `failed`."
    },
    "SignalScoreEvidence": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "scoreDimension": {
              "type": "string",
              "enum": [
                "outcome"
              ],
              "description": "Agent Score dimension this evidence informs."
            },
            "role": {
              "type": "string",
              "enum": [
                "taskOutcome"
              ],
              "description": "How this evidence informs the dimension."
            }
          },
          "required": [
            "scoreDimension",
            "role"
          ]
        },
        {
          "type": "object",
          "properties": {
            "scoreDimension": {
              "type": "string",
              "enum": [
                "reliability"
              ],
              "description": "Agent Score dimension this evidence informs."
            },
            "role": {
              "type": "string",
              "enum": [
                "completionOutcome",
                "operationalIncident"
              ],
              "description": "How this evidence informs the dimension."
            }
          },
          "required": [
            "scoreDimension",
            "role"
          ]
        },
        {
          "type": "object",
          "properties": {
            "scoreDimension": {
              "type": "string",
              "enum": [
                "cost"
              ],
              "description": "Agent Score dimension this evidence informs."
            },
            "role": {
              "type": "string",
              "enum": [
                "spendEfficiency"
              ],
              "description": "How this evidence informs the dimension."
            }
          },
          "required": [
            "scoreDimension",
            "role"
          ]
        },
        {
          "type": "object",
          "properties": {
            "scoreDimension": {
              "type": "string",
              "enum": [
                "speed"
              ],
              "description": "Agent Score dimension this evidence informs."
            },
            "role": {
              "type": "string",
              "enum": [
                "criticalPathEfficiency"
              ],
              "description": "How this evidence informs the dimension."
            }
          },
          "required": [
            "scoreDimension",
            "role"
          ]
        },
        {
          "type": "object",
          "properties": {
            "scoreDimension": {
              "type": "string",
              "enum": [
                "safety"
              ],
              "description": "Agent Score dimension this evidence informs."
            },
            "role": {
              "type": "string",
              "enum": [
                "confirmedHarm",
                "exposure"
              ],
              "description": "How this evidence informs the dimension."
            }
          },
          "required": [
            "scoreDimension",
            "role"
          ]
        }
      ]
    },
    "SignalTrendBucket": {
      "type": "object",
      "properties": {
        "bucket": {
          "type": "string",
          "description": "UTC day bucket (`YYYY-MM-DD`)."
        },
        "count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of occurrences within the bucket."
        }
      },
      "required": [
        "bucket",
        "count"
      ]
    }
  }
}