{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "durable-workflow.v2.repair-actionability-objects",
  "title": "Durable Workflow repair and actionability objects",
  "description": "Normative JSON Schema for task-repair policy snapshots, repair candidate snapshots, actionability hints, queue visibility rows, and structured failure/action affordance objects emitted by workflow, server, and Waterline operator surfaces.",
  "type": "object",
  "x-durable-workflow-catalog-entry": "repair_actionability_objects",
  "x-durable-workflow-catalog-schema": "durable-workflow.v2.platform-protocol-specs.catalog",
  "x-durable-workflow-catalog-version": 13,
  "x-durable-workflow-owner-symbol": "Workflow\\V2\\Support\\TaskRepairCandidates, Workflow\\V2\\Support\\TaskRepairPolicy, and Workflow\\V2\\Support\\OperatorQueueVisibility",
  "x-durable-workflow-evolution-rule": "additive_minor_breaking_major",
  "x-durable-workflow-object-families": [
    {
      "name": "task_repair_policy",
      "owner_repo": "durable-workflow/workflow",
      "schema_authority": "Workflow\\V2\\Support\\TaskRepairPolicy::snapshot",
      "version_authority": "durable-workflow.v2.repair-actionability-objects"
    },
    {
      "name": "task_repair_candidates",
      "owner_repo": "durable-workflow/workflow",
      "schema_authority": "Workflow\\V2\\Support\\TaskRepairCandidates::snapshot",
      "version_authority": "durable-workflow.v2.repair-actionability-objects"
    },
    {
      "name": "operator_queue_visibility",
      "owner_repo": "durable-workflow/workflow",
      "schema_authority": "Workflow\\V2\\Support\\OperatorQueueVisibility",
      "version_authority": "durable-workflow.v2.repair-actionability-objects"
    },
    {
      "name": "actionability",
      "owner_repo": "durable-workflow/waterline",
      "schema_authority": "Waterline\\Support\\ActionabilityContract",
      "version_authority": "Waterline\\Support\\ActionabilityContract::VERSION"
    }
  ],
  "additionalProperties": true,
  "properties": {
    "policy": {
      "$ref": "#/$defs/taskRepairPolicy"
    },
    "candidates": {
      "$ref": "#/$defs/taskRepairCandidates"
    },
    "actionability": {
      "$ref": "#/$defs/actionability"
    },
    "queue_visibility": {
      "$ref": "#/$defs/queueVisibility"
    },
    "failure": {
      "$ref": "#/$defs/structuredFailure"
    }
  },
  "$defs": {
    "taskRepairPolicy": {
      "type": "object",
      "required": [
        "redispatch_after_seconds",
        "loop_throttle_seconds",
        "scan_limit",
        "scan_strategy",
        "failure_backoff_max_seconds",
        "failure_backoff_strategy"
      ],
      "additionalProperties": true,
      "properties": {
        "redispatch_after_seconds": { "type": "integer", "minimum": 1 },
        "loop_throttle_seconds": { "type": "integer", "minimum": 1 },
        "scan_limit": { "type": "integer", "minimum": 1 },
        "scan_strategy": { "type": "string", "const": "scope_fair_round_robin" },
        "failure_backoff_max_seconds": { "type": "integer", "minimum": 1 },
        "failure_backoff_strategy": { "type": "string", "const": "exponential_by_repair_count" }
      }
    },
    "taskRepairCandidates": {
      "type": "object",
      "required": [
        "existing_task_candidates",
        "missing_task_candidates",
        "total_candidates",
        "scan_limit",
        "scan_strategy",
        "scopes"
      ],
      "additionalProperties": true,
      "properties": {
        "existing_task_candidates": { "type": "integer", "minimum": 0 },
        "missing_task_candidates": { "type": "integer", "minimum": 0 },
        "total_candidates": { "type": "integer", "minimum": 0 },
        "scan_limit": { "type": "integer", "minimum": 1 },
        "scan_strategy": { "type": "string" },
        "selected_total_candidates": { "type": "integer", "minimum": 0 },
        "scan_pressure": { "type": "boolean" },
        "oldest_task_candidate_created_at": { "type": ["string", "null"], "format": "date-time" },
        "oldest_missing_run_started_at": { "type": ["string", "null"], "format": "date-time" },
        "scopes": {
          "type": "array",
          "items": { "$ref": "#/$defs/taskRepairScope" }
        }
      }
    },
    "taskRepairScope": {
      "type": "object",
      "required": ["scope_key", "existing_task_candidates", "missing_task_candidates", "total_candidates"],
      "additionalProperties": true,
      "properties": {
        "scope_key": { "type": "string" },
        "connection": { "type": ["string", "null"] },
        "queue": { "type": ["string", "null"] },
        "compatibility": { "type": ["string", "null"] },
        "existing_task_candidates": { "type": "integer", "minimum": 0 },
        "missing_task_candidates": { "type": "integer", "minimum": 0 },
        "total_candidates": { "type": "integer", "minimum": 0 },
        "scan_limited_by_global_policy": { "type": "boolean" }
      }
    },
    "actionability": {
      "type": "object",
      "required": ["schema", "version"],
      "additionalProperties": true,
      "properties": {
        "schema": { "type": "string" },
        "version": { "type": "integer", "minimum": 1 },
        "repair_state": {
          "type": "string",
          "enum": ["repairable", "blocked", "not_needed", "unknown"]
        },
        "state": {
          "type": "string",
          "enum": ["actionable", "diagnostic_only"]
        },
        "repairable": { "type": "boolean" },
        "repair_source": { "type": "boolean" },
        "diagnostic_only": { "type": "boolean" },
        "blocked_reason": { "type": ["string", "null"] },
        "actions": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "required": ["allowed", "derived_from"],
            "additionalProperties": true,
            "properties": {
              "allowed": { "type": "boolean" },
              "reason": { "type": ["string", "null"] },
              "derived_from": { "type": "string" }
            }
          }
        },
        "badges": { "type": "object", "additionalProperties": true }
      }
    },
    "queueVisibility": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "namespace": { "type": ["string", "null"] },
        "queues": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "task_queue": { "type": "string" },
              "stats": { "type": "object", "additionalProperties": true },
              "current_leases": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
              "repair": { "$ref": "#/$defs/taskRepairCandidates" }
            }
          }
        }
      }
    },
    "structuredFailure": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "failure_id": { "type": ["string", "null"] },
        "failure_category": { "type": ["string", "null"] },
        "non_retryable": { "type": ["boolean", "null"] },
        "exception_type": { "type": ["string", "null"] },
        "exception_class": { "type": ["string", "null"] },
        "message": { "type": ["string", "null"] },
        "code": { "type": ["string", "integer", "null"] }
      }
    }
  }
}