Schema: operation-journal

{
  "$id": "https://australis.systems/schemas/htmx-ui-template-scaffold/operation-journal.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Canonical Draft 2020-12 envelope for the operation journal that records durable mutation state transitions for one operation. See package ARCHITECTURE.md 'Replace, Backup, Restore, Purge, And Recovery' and root docs/architecture/software-design-and-resilience.md \u00a7\u00a74.1 (determinism) and \u00a7\u00a75 (resilience). The schema enforces 11 states (no FAILED state); each transition has a timezone-aware timestamp, source state, target state, and string evidence. schema_version is major-version-pinned: only '1.0.0' documents are accepted.",
  "properties": {
    "operation_id": {
      "description": "Unique identifier of the operation being journaled. Binds the journal to receipts and backups.",
      "minLength": 1,
      "type": "string"
    },
    "schema_version": {
      "description": "Major-version-locked envelope version. Documents with any value other than '1.0.0' MUST fail validation, which enforces the major-version-1 contract.",
      "enum": [
        "1.0.0"
      ],
      "type": "string"
    },
    "state": {
      "description": "Current FSM state. The 11 canonical states are: PREFLIGHT, STAGED, BACKUP_VERIFIED, QUARANTINED, PROMOTED, VALIDATED, COMPLETED, ROLLING_BACK, ROLLED_BACK, ABORTED, RECOVERY_REQUIRED. FAILED is NOT a valid value; any document declaring 'FAILED' MUST fail validation.",
      "enum": [
        "PREFLIGHT",
        "STAGED",
        "BACKUP_VERIFIED",
        "QUARANTINED",
        "PROMOTED",
        "VALIDATED",
        "COMPLETED",
        "ROLLING_BACK",
        "ROLLED_BACK",
        "ABORTED",
        "RECOVERY_REQUIRED"
      ],
      "type": "string"
    },
    "transitions": {
      "description": "Append-only transition log, ordered chronologically.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "at": {
            "description": "RFC 3339 timestamp the transition fired.",
            "format": "date-time",
            "type": "string"
          },
          "evidence": {
            "description": "Pointer to transition evidence: a file path, a digest, a command id, or a free-form note. Evidence is a structured free-form string; the previous runtime model treating evidence as a dict is a contract break and MUST be removed.",
            "type": "string"
          },
          "from_state": {
            "description": "State before the transition. One of the 11 canonical states (no FAILED).",
            "enum": [
              "PREFLIGHT",
              "STAGED",
              "BACKUP_VERIFIED",
              "QUARANTINED",
              "PROMOTED",
              "VALIDATED",
              "COMPLETED",
              "ROLLING_BACK",
              "ROLLED_BACK",
              "ABORTED",
              "RECOVERY_REQUIRED"
            ],
            "type": "string"
          },
          "to_state": {
            "description": "State after the transition. One of the 11 canonical states (no FAILED).",
            "enum": [
              "PREFLIGHT",
              "STAGED",
              "BACKUP_VERIFIED",
              "QUARANTINED",
              "PROMOTED",
              "VALIDATED",
              "COMPLETED",
              "ROLLING_BACK",
              "ROLLED_BACK",
              "ABORTED",
              "RECOVERY_REQUIRED"
            ],
            "type": "string"
          }
        },
        "required": [
          "at",
          "from_state",
          "to_state",
          "evidence"
        ],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "schema_version",
    "operation_id",
    "state",
    "transitions"
  ],
  "title": "Operation Journal",
  "type": "object"
}