{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mm.dreamineering.com/schemas/decision-trace.v1.json",
  "title": "Decision Trace",
  "description": "One human-owned decision carried from intention through permission and review. Null means unknown or not yet observed. Validation describes a record; it cannot grant authority or verify acceptance evidence.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "trace_id",
    "revision",
    "stage",
    "intention",
    "belief",
    "mandate",
    "review"
  ],
  "properties": {
    "schema_version": { "const": "1.0", "title": "Schema version", "default": "1.0" },
    "trace_id": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "title": "Trace ID",
      "description": "Choose a stable name for this decision; carry it through every handoff.",
      "default": "my-decision"
    },
    "revision": {
      "type": "integer",
      "minimum": 1,
      "title": "Revision",
      "description": "Preserve the accepted revision. Start a new draft revision if intention, prediction, or mandate changes.",
      "default": 1
    },
    "stage": {
      "enum": ["draft", "authorised", "reviewing", "reviewed"],
      "title": "Stage",
      "description": "Draft before acceptance; authorised after acceptance; reviewing after action or stop while the human decision is pending; reviewed after the human decides. A record is not permission.",
      "default": "draft"
    },
    "intention": {
      "type": "object",
      "additionalProperties": false,
      "title": "Intention",
      "description": "Before action: name who should benefit, the worthwhile change, and what must stay protected.",
      "required": ["beneficiary", "desired_change", "meaning", "protected_values", "baseline"],
      "properties": {
        "beneficiary": {
          "$ref": "#/definitions/answer",
          "title": "Beneficiary",
          "description": "Who should benefit, and who else is affected?"
        },
        "desired_change": {
          "$ref": "#/definitions/answer",
          "title": "Desired change",
          "description": "What observable condition should improve for that person?"
        },
        "meaning": {
          "$ref": "#/definitions/answer",
          "title": "Why it matters",
          "description": "Why is this change worth the effort?"
        },
        "protected_values": {
          "$ref": "#/definitions/answer",
          "title": "Protected values",
          "description": "What must not be traded away, including other people's consent?"
        },
        "baseline": {
          "$ref": "#/definitions/answer",
          "title": "Present baseline",
          "description": "What is the current condition, or how will the first bounded observation establish it?"
        }
      }
    },
    "belief": {
      "type": "object",
      "additionalProperties": false,
      "title": "Belief",
      "description": "Before action: separate what you observed from what you expect and what would change your mind.",
      "required": [
        "observations",
        "sources",
        "causal_explanation",
        "prediction",
        "confidence",
        "uncertainty",
        "falsifier"
      ],
      "properties": {
        "observations": {
          "$ref": "#/definitions/answer",
          "title": "Observations",
          "description": "What do the available observations show? State when no observation exists."
        },
        "sources": {
          "$ref": "#/definitions/answer",
          "title": "Sources",
          "description": "Where did each observation come from, and when?"
        },
        "causal_explanation": {
          "$ref": "#/definitions/answer",
          "title": "Causal explanation",
          "description": "Why might this move cause the desired change? Mark it as a belief."
        },
        "prediction": {
          "$ref": "#/definitions/answer",
          "title": "Prediction",
          "description": "What should happen by the review point? Freeze this before acting."
        },
        "confidence": {
          "$ref": "#/definitions/answer",
          "title": "Confidence",
          "description": "How confident are you, and why?"
        },
        "uncertainty": {
          "$ref": "#/definitions/answer",
          "title": "Uncertainty",
          "description": "What remains uncertain, and why is this bounded move still justified?"
        },
        "falsifier": {
          "$ref": "#/definitions/answer",
          "title": "Falsifier",
          "description": "Which observation would contradict the belief or require a different move?"
        }
      }
    },
    "mandate": {
      "type": "object",
      "additionalProperties": false,
      "title": "Mandate",
      "description": "Before delegated work: agree exact permissions, checks, stop, recovery, and human acceptance of this revision.",
      "required": [
        "human_owner",
        "actor",
        "allowed_inputs",
        "allowed_actions",
        "prohibited_actions",
        "next_move",
        "resources",
        "acceptance_criteria",
        "expires_at",
        "review_at",
        "stop_conditions",
        "recovery",
        "evidence_destination",
        "acceptance"
      ],
      "properties": {
        "human_owner": {
          "$ref": "#/definitions/answer",
          "title": "Human owner",
          "description": "Who rightfully owns this decision, permission, and stop?"
        },
        "actor": {
          "$ref": "#/definitions/answer",
          "title": "Delegated actor",
          "description": "Which person or agent will perform this bounded job?"
        },
        "allowed_inputs": {
          "$ref": "#/definitions/answer",
          "title": "Permitted inputs",
          "description": "Which exact information and tools may the actor use?"
        },
        "allowed_actions": {
          "$ref": "#/definitions/answer",
          "title": "Permitted actions",
          "description": "Which actions are permitted, and where?"
        },
        "prohibited_actions": {
          "$ref": "#/definitions/answer",
          "title": "Prohibited actions",
          "description": "Which actions, disclosures, contacts, or commitments are excluded?"
        },
        "next_move": {
          "$ref": "#/definitions/answer",
          "title": "Bounded next move",
          "description": "Describe the bounded work proposed for execution after human acceptance. Put the current HOLD, clarification, and responsible owner beside the trace, not in this field."
        },
        "resources": {
          "$ref": "#/definitions/answer",
          "title": "Resource limit",
          "description": "Bound time, effort, money, and tool use."
        },
        "acceptance_criteria": {
          "$ref": "#/definitions/answer",
          "title": "Evidence criteria",
          "description": "Which gauge and acceptance condition will show whether this move helped?"
        },
        "expires_at": {
          "$ref": "#/definitions/timestamp",
          "title": "Authority expiry",
          "description": "When does permission expire? Use an ISO timestamp with timezone."
        },
        "review_at": {
          "$ref": "#/definitions/timestamp",
          "title": "Review point",
          "description": "When will the human review the evidence? Use an ISO timestamp with timezone."
        },
        "stop_conditions": {
          "$ref": "#/definitions/answer",
          "title": "Stop conditions",
          "description": "What stops the work and returns control to the named human?"
        },
        "recovery": {
          "$ref": "#/definitions/answer",
          "title": "Recovery",
          "description": "How will the actor preserve evidence and restore a safe state?"
        },
        "evidence_destination": {
          "$ref": "#/definitions/answer",
          "title": "Evidence owner and destination",
          "description": "Who receives the evidence, where, and with what sharing permission?"
        },
        "acceptance": {
          "title": "Human acceptance",
          "description": "Leave null until the rightful human accepts this exact revision. Retain attributable evidence; an agent must not invent it.",
          "anyOf": [{ "type": "null" }, { "$ref": "#/definitions/acceptance" }]
        }
      }
    },
    "review": {
      "title": "Review",
      "description": "After action or stop: append evidence and the human's next decision. Until then leave null.",
      "anyOf": [{ "type": "null" }, { "$ref": "#/definitions/review" }]
    }
  },
  "definitions": {
    "answer": { "type": ["string", "null"], "minLength": 1, "pattern": "\\S" },
    "timestamp": {
      "type": ["string", "null"],
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$"
    },
    "acceptance": {
      "type": "object",
      "additionalProperties": false,
      "required": ["accepted_by", "revision", "accepted_at", "evidence"],
      "properties": {
        "accepted_by": { "type": "string", "minLength": 1, "pattern": "\\S" },
        "revision": { "type": "integer", "minimum": 1 },
        "accepted_at": { "allOf": [{ "$ref": "#/definitions/timestamp" }, { "type": "string" }] },
        "evidence": { "type": "string", "minLength": 1, "pattern": "\\S" }
      }
    },
    "review": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "of_revision",
        "work_performed",
        "evidence",
        "beneficiary_consequence",
        "exceptions",
        "variance",
        "remaining_uncertainty",
        "human_decision",
        "correction_owner",
        "next_review"
      ],
      "properties": {
        "of_revision": { "type": "integer", "minimum": 1, "title": "Accepted revision reviewed" },
        "work_performed": {
          "$ref": "#/definitions/answer",
          "title": "Work performed",
          "description": "What actually happened, including an early stop?"
        },
        "evidence": {
          "$ref": "#/definitions/answer",
          "title": "Evidence and provenance",
          "description": "Retain attributable observations, their dates, and their limits."
        },
        "beneficiary_consequence": {
          "$ref": "#/definitions/answer",
          "title": "Beneficiary consequence",
          "description": "What changed for the beneficiary? Use null if not observed."
        },
        "exceptions": {
          "$ref": "#/definitions/answer",
          "title": "Exceptions and side effects",
          "description": "Record departures, harm, costs, and stop events, including none observed when warranted."
        },
        "variance": {
          "$ref": "#/definitions/answer",
          "title": "Variance",
          "description": "Compare the original prediction and baseline with observations; retain confounders."
        },
        "remaining_uncertainty": {
          "$ref": "#/definitions/answer",
          "title": "Remaining uncertainty",
          "description": "Name missing evidence and what remains unproved."
        },
        "human_decision": {
          "$ref": "#/definitions/answer",
          "title": "Human decision",
          "description": "Record the human's continue, revise, stop, or further-observation decision and reasons. An agent's proposal is not the decision."
        },
        "correction_owner": {
          "$ref": "#/definitions/answer",
          "title": "Correction owner",
          "description": "Who owns the correction or the reasoned decision to retain the method?"
        },
        "next_review": {
          "$ref": "#/definitions/answer",
          "title": "Next review",
          "description": "When will missing evidence return, or why is no further review needed?"
        }
      }
    }
  },
  "allOf": [
    {
      "if": { "properties": { "stage": { "const": "authorised" } } },
      "then": {
        "properties": {
          "intention": { "additionalProperties": { "type": "string" } },
          "belief": { "additionalProperties": { "type": "string" } },
          "mandate": {
            "properties": { "acceptance": { "type": "object" } },
            "additionalProperties": { "type": "string" }
          },
          "review": { "type": "null" }
        }
      }
    },
    {
      "if": { "properties": { "stage": { "const": "reviewing" } } },
      "then": {
        "properties": {
          "review": {
            "allOf": [
              { "$ref": "#/definitions/review" },
              { "properties": { "human_decision": { "type": "null" } } }
            ]
          }
        }
      }
    },
    {
      "if": { "properties": { "stage": { "const": "reviewed" } } },
      "then": {
        "properties": {
          "review": {
            "allOf": [
              { "$ref": "#/definitions/review" },
              {
                "properties": {
                  "work_performed": { "type": "string" },
                  "evidence": { "type": "string" },
                  "exceptions": { "type": "string" },
                  "variance": { "type": "string" },
                  "remaining_uncertainty": { "type": "string" },
                  "human_decision": { "type": "string" },
                  "correction_owner": { "type": "string" },
                  "next_review": { "type": "string" }
                }
              }
            ]
          }
        }
      }
    }
  ]
}