{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://clearhead.dev/schemas/v0.7.0/transaction_result.schema.json",
  "title": "ClearHead Transaction Result",
  "description": "The single receipt a transaction emits: a committed batch, a dry-run preview, or a typed rejection that wrote nothing. Discriminated on `kind`. Per-operation outcomes reuse the same VerbOutcome shapes the single mutation verbs already emit, and a rejection reuses the VerbError taxonomy, so the read side, the single verbs, and the batch surface all speak one spelling. Compare-and-swap / conflict outcomes are intentionally not modeled in v1 (no stale-update token exists yet).",
  "oneOf": [
    { "$ref": "#/$defs/committed" },
    { "$ref": "#/$defs/dryRun" },
    { "$ref": "#/$defs/rejected" }
  ],
  "$defs": {
    "canonicalId": {
      "type": "string",
      "pattern": "^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "verbOutcome": {
      "type": "object",
      "description": "One applied (or, in a dry-run, would-be-applied) operation outcome. Mirrors clearhead-cli VerbOutcome in full, independent of which kinds `transact` itself can currently request — the taxonomy lives in core so every producer speaks one spelling. `completed`/`cancelled` carry `open_children`, the ids left open beneath the named action (empty when none), and no `children` count. Only `deleted` carries `children`, the number of descendants also deleted. `reopened` affects one action and carries neither field, as do `added`/`updated`.",
      "required": ["kind", "id"],
      "additionalProperties": false,
      "properties": {
        "kind": { "enum": ["completed", "cancelled", "reopened", "updated", "added", "deleted"] },
        "id": { "$ref": "#/$defs/canonicalId" },
        "children": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of descendant actions also deleted. Present only for deleted."
        },
        "open_children": {
          "type": "array",
          "items": { "$ref": "#/$defs/canonicalId" },
          "description": "Ids of actions left open beneath the named action. Required for completed/cancelled, empty when none; absent for all other outcomes."
        }
      },
      "allOf": [
        {
          "if": { "properties": { "kind": { "const": "deleted" } } },
          "then": { "required": ["children"] }
        },
        {
          "if": { "properties": { "kind": { "enum": ["completed", "cancelled", "reopened", "updated", "added"] } } },
          "then": { "not": { "required": ["children"] } }
        },
        {
          "if": { "properties": { "kind": { "enum": ["completed", "cancelled"] } } },
          "then": { "required": ["open_children"] },
          "else": { "not": { "required": ["open_children"] } }
        }
      ]
    },
    "operationOutcomes": {
      "type": "array",
      "minItems": 1,
      "description": "One outcome per request operation, in request order.",
      "items": { "$ref": "#/$defs/verbOutcome" }
    },
    "files": {
      "type": "array",
      "description": "Absolute paths of the .actions files written (committed) or that would be written (dry-run). Derived sidecars are not listed.",
      "items": { "type": "string", "minLength": 1 }
    },
    "committed": {
      "type": "object",
      "description": "The batch validated and committed through one PendingBatch.",
      "required": ["kind", "operations", "files"],
      "additionalProperties": false,
      "properties": {
        "kind": { "const": "committed" },
        "operations": { "$ref": "#/$defs/operationOutcomes" },
        "files": { "$ref": "#/$defs/files" }
      }
    },
    "dryRun": {
      "type": "object",
      "description": "The batch validated but was not staged; nothing was written. Reports what would happen.",
      "required": ["kind", "operations", "files"],
      "additionalProperties": false,
      "properties": {
        "kind": { "const": "dry-run" },
        "operations": { "$ref": "#/$defs/operationOutcomes" },
        "files": { "$ref": "#/$defs/files" }
      }
    },
    "rejected": {
      "type": "object",
      "description": "An operation failed to resolve or apply; the entire batch was rejected before any write. `operation` is the 0-based index of the offending request operation.",
      "required": ["kind", "operation", "error"],
      "additionalProperties": false,
      "properties": {
        "kind": { "const": "rejected" },
        "operation": {
          "type": "integer",
          "minimum": 0,
          "description": "0-based index into the request `operations` array of the operation that failed."
        },
        "error": { "$ref": "#/$defs/verbError" }
      }
    },
    "verbError": {
      "type": "object",
      "description": "Typed failure, mirroring clearhead-cli VerbError. Resolved under the workspace lock against trusted state.",
      "required": ["kind"],
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "not-found" },
            "query": { "type": "string" }
          },
          "required": ["kind", "query"]
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "ambiguous" },
            "query": { "type": "string" },
            "candidates": {
              "type": "array",
              "items": { "$ref": "#/$defs/canonicalId" }
            }
          },
          "required": ["kind", "query", "candidates"]
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "already-closed" },
            "id": { "$ref": "#/$defs/canonicalId" },
            "state": { "type": "string" },
            "query": { "type": "string" }
          },
          "required": ["kind", "id", "state", "query"]
        },
        {
          "additionalProperties": false,
          "description": "The mirror of already-closed for reopen: the query resolves to an action that is already open.",
          "properties": {
            "kind": { "const": "already-open" },
            "id": { "$ref": "#/$defs/canonicalId" },
            "state": { "type": "string" },
            "query": { "type": "string" }
          },
          "required": ["kind", "id", "state", "query"]
        },
        {
          "additionalProperties": false,
          "description": "A reopen refused because the target is archived; unarchive the named root first.",
          "properties": {
            "kind": { "const": "archived" },
            "id": { "$ref": "#/$defs/canonicalId" },
            "root": {
              "$ref": "#/$defs/canonicalId",
              "description": "Canonical id of the root to unarchive."
            },
            "query": { "type": "string" }
          },
          "required": ["kind", "id", "root", "query"]
        }
      ]
    }
  }
}
