{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://clearhead.dev/schemas/v0.7.0/transaction_request.schema.json",
  "title": "ClearHead Transaction Request",
  "description": "A batch of semantic action operations that must validate together and commit together through one PendingBatch. Operations are applied in array order against trusted workspace state loaded under the workspace lock; any invalid operation rejects the whole batch before a write. This is NOT a JSON Patch or a desired-state document: each operation names an intent (update / complete / cancel / reopen) whose in-place field and date changes core owns. Complete, cancel, and reopen affect only the named action: no cascade, no parent-link detachment, and no file move. Single-item work should use the ordinary verbs; a transaction exists only for edits that must be atomic together. Dry-run is an invocation flag (`clearhead transact --dry-run`), not part of this document.",
  "type": "object",
  "required": ["operations"],
  "additionalProperties": false,
  "properties": {
    "operations": {
      "type": "array",
      "minItems": 1,
      "description": "Ordered operations. Applied in sequence; the batch is all-or-nothing.",
      "items": {
        "oneOf": [
          { "$ref": "#/$defs/updateAction" },
          { "$ref": "#/$defs/completeAction" },
          { "$ref": "#/$defs/cancelAction" },
          { "$ref": "#/$defs/reopenAction" }
        ]
      }
    }
  },
  "$defs": {
    "canonicalId": {
      "type": "string",
      "description": "Canonical action identity as a urn:uuid IRI, the exact spelling the query contract exports and the CLI resolver accepts.",
      "pattern": "^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "updateAction": {
      "type": "object",
      "description": "Edit an open action's attributes in place (single file). Core refuses a closed target altogether, even when no state edit is requested. No cascade, no move. State may be set to a NON-terminal value here; terminal transitions (completed / cancelled) are rejected by core in favor of complete-action / cancel-action, which stamp state and completed_at together. Use reopen-action to reopen a closed action and clear its completed_at.",
      "required": ["op", "target", "set"],
      "additionalProperties": false,
      "properties": {
        "op": { "const": "update-action" },
        "target": { "$ref": "#/$defs/canonicalId" },
        "set": {
          "type": "object",
          "description": "Fields to change; mirrors core's ActionUpdate applier surface. At least one field. Dependency-graph edits (predecessors, is_sequential) are intentionally out of the v1 operation set.",
          "minProperties": 1,
          "additionalProperties": false,
          "properties": {
            "name": { "type": "string", "minLength": 1 },
            "description": { "type": "string" },
            "priority": { "type": "integer", "minimum": 1, "maximum": 9 },
            "context": {
              "type": "array",
              "description": "Context tags as bare names (no leading '+'). Replaces the existing set.",
              "items": { "type": "string", "minLength": 1 }
            },
            "alias": { "type": "string", "minLength": 1 },
            "state": {
              "type": "string",
              "description": "Action state, serialized as core ActionState does (snake_case; BlockedOrAwaiting => 'blocked'). Terminal values 'completed'/'cancelled' are accepted structurally but rejected by core's terminal-state guard — use complete-action / cancel-action instead. To reopen a closed action, use reopen-action rather than a field update.",
              "enum": ["not_started", "in_progress", "blocked", "completed", "cancelled"]
            },
            "scheduled_at": {
              "type": "string",
              "description": "The do-date, written as '@' takes it: an ISO 8601 date or date-time (the planned start), or a start/end interval (a planned block), e.g. 2026-04-01T09:00/2026-04-01T09:30. Duration is the block's length (Decision 51)."
            }
          }
        }
      }
    },
    "completeAction": {
      "type": "object",
      "description": "Close only the named action in place: set state to completed and stamp completed_at. No cascade, no parent-link detachment, and no file move. Descendants and the action's parent link are unchanged; closed lines remain ordinary records in the active file. Archival is a separate whole-root-tree operation.",
      "required": ["op", "target"],
      "additionalProperties": false,
      "properties": {
        "op": { "const": "complete-action" },
        "target": { "$ref": "#/$defs/canonicalId" }
      }
    },
    "cancelAction": {
      "type": "object",
      "description": "Cancel only the named action in place: set state to cancelled and stamp completed_at. No cascade, no parent-link detachment, and no file move. Descendants and the action's parent link are unchanged; archival is a separate whole-root-tree operation.",
      "required": ["op", "target"],
      "additionalProperties": false,
      "properties": {
        "op": { "const": "cancel-action" },
        "target": { "$ref": "#/$defs/canonicalId" }
      }
    },
    "reopenAction": {
      "type": "object",
      "description": "Reopen only the named closed action in place: set state to not_started and clear completed_at. Allowed only in the active file; refused if archived (unarchive its root tree first). No cascade, no parent-link detachment, and no file move. Descendants and the action's parent link are unchanged.",
      "required": ["op", "target"],
      "additionalProperties": false,
      "properties": {
        "op": { "const": "reopen-action" },
        "target": { "$ref": "#/$defs/canonicalId" }
      }
    }
  }
}
