Schema: plan

{
  "$id": "https://australis.systems/schemas/htmx-ui-template-scaffold/plan.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "plan_kind": {
            "const": "mapped_route_scaffold"
          }
        },
        "required": [
          "plan_kind"
        ]
      },
      "then": {
        "required": [
          "input_bindings"
        ]
      }
    }
  ],
  "description": "Ordered mutation plan produced from a desired-state diff. The plan carries one canonical digest that approval documents MUST reference verbatim, plus per-path ownership_class and conflict_classification maps. Operations are required ordered; downstream tooling MUST execute them in array order.",
  "properties": {
    "api_operation_candidates": {
      "type": "array"
    },
    "before_state_digest": {
      "description": "SHA-256 hex digest of the pre-plan target state used to derive this plan. Detects mid-plan concurrent writes.",
      "pattern": "^[a-f0-9]{64}$",
      "type": "string"
    },
    "browser_page_candidates": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "handler_expression": {
            "minLength": 1,
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "proposed_path": {
            "minLength": 1,
            "type": "string"
          },
          "route_local_layers_present": {
            "type": "boolean"
          },
          "source_line": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "proposed_path"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "compatibility_profile": {
      "minLength": 1,
      "type": "string"
    },
    "conflict_classification": {
      "additionalProperties": {
        "enum": [
          "ABSENT",
          "IDENTICAL",
          "MANAGED_OUTDATED",
          "MANAGED_DRIFT",
          "ROUTE_OWNED",
          "USER_OWNED",
          "TYPE_MISMATCH",
          "CASE_COLLISION",
          "PATH_ESCAPE",
          "PLAN_STALE"
        ],
        "type": "string"
      },
      "description": "Per-path conflict classification. Values are taken from the AUTHORITATIVE set in ARCHITECTURE.md (Reconcile Semantics). A missing key means no conflict was detected.",
      "type": "object"
    },
    "corpus_revision": {
      "minLength": 1,
      "type": "string"
    },
    "desired_state_digest": {
      "description": "SHA-256 hex digest of the desired state that produced this plan.",
      "pattern": "^[a-f0-9]{64}$",
      "type": "string"
    },
    "digest": {
      "description": "SHA-256 hex digest of the canonical (sorted-key, allow_unicode=False) YAML form of this plan, including input_bindings when present. Approval documents MUST bind to this digest exactly.",
      "pattern": "^[a-f0-9]{64}$",
      "type": "string"
    },
    "input_bindings": {
      "additionalProperties": false,
      "description": "Exact planning-input digests for a mapped route scaffold. The canonical plan digest covers this entire object, so approval binds these inputs together with the proposed operations.",
      "properties": {
        "analysis_evidence": {
          "description": "Canonical SHA-256 digest of the exact analysis argument used at planning, including the entire REVIEW_ONLY wrapper and unresolved evidence when supplied.",
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        },
        "capability_tree": {
          "description": "SHA-256 digest of the exact capability tree contract file bytes that were schema-validated and checked for document_status: ACTIVE at planning; reconcile performs no external reload.",
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        },
        "route_artifact_selection": {
          "description": "SHA-256 digest of the exact normative-reference route artifact selection file bytes used at planning.",
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        },
        "route_contract": {
          "description": "SHA-256 digest of the exact route contract file bytes that were schema-validated and checked for document_status: ACTIVE at planning; reconcile performs no external reload.",
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        },
        "route_word_layout_selection": {
          "description": "SHA-256 digest of the exact normative-reference route word layout selection file bytes used at planning.",
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        },
        "template_registration": {
          "description": "SHA-256 digest of the exact template registration contract file bytes that were schema-validated and checked for document_status: ACTIVE at planning; reconcile performs no external reload.",
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        }
      },
      "required": [
        "analysis_evidence",
        "route_contract",
        "template_registration",
        "capability_tree",
        "route_artifact_selection",
        "route_word_layout_selection"
      ],
      "type": "object"
    },
    "manifest_digest": {
      "pattern": "^[a-f0-9]{64}$",
      "type": "string"
    },
    "operations": {
      "description": "Required ordered proposals. Downstream tooling MUST execute entries in array order.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "artifact": {
            "type": "string"
          },
          "before_digest": {
            "description": "SHA-256 hex digest of the on-disk content before the operation (lowercase, 64 hex characters). Omit when not applicable.",
            "pattern": "^[a-f0-9]{64}$",
            "type": "string"
          },
          "desired_content": {
            "type": "string"
          },
          "desired_digest": {
            "description": "SHA-256 hex digest of the canonical content the operation will produce.",
            "pattern": "^[a-f0-9]{64}$",
            "type": "string"
          },
          "kind": {
            "description": "Discriminator that selects the per-kind execution branch.",
            "enum": [
              "CREATE",
              "UPDATE",
              "PRESERVE",
              "CONFLICT",
              "DELETE",
              "UPGRADE"
            ],
            "type": "string"
          },
          "layout_profile": {
            "type": "string"
          },
          "owning_page_route_id": {
            "minLength": 1,
            "type": "string"
          },
          "path": {
            "description": "Target-relative path the operation refers to.",
            "minLength": 1,
            "type": "string"
          },
          "rationale": {
            "description": "Human-readable rationale. Producers SHOULD include one for CONFLICT and DELETE operations.",
            "type": "string"
          },
          "response_mode": {
            "enum": [
              "HTML_PAGE",
              "HTML_PARTIAL"
            ],
            "type": "string"
          },
          "route_id": {
            "type": "string"
          },
          "route_tree_profile": {
            "enum": [
              "PAGE_ONLY",
              "PAGE_WITH_HTMX_PARTIALS"
            ],
            "type": "string"
          }
        },
        "required": [
          "kind",
          "path"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "ownership_class": {
      "additionalProperties": {
        "enum": [
          "TOOL_MANAGED",
          "ROUTE_OWNED",
          "USER_OWNED",
          "PROTECTED"
        ],
        "type": "string"
      },
      "description": "Per-path ownership class. Values are taken from the AUTHORITATIVE set in ARCHITECTURE.md (Asset Ownership).",
      "type": "object"
    },
    "parent_revision_id": {
      "description": "Optional parent revision identifier for chain-of-history tracing.",
      "minLength": 1,
      "type": "string"
    },
    "plan_kind": {
      "enum": [
        "route_scaffold",
        "analysis_scaffold",
        "mapped_route_scaffold",
        "asset_sync"
      ],
      "type": "string"
    },
    "proposed_operations": {
      "items": {
        "$ref": "#/properties/operations/items"
      },
      "type": "array"
    },
    "revision_id": {
      "description": "Optional revision identifier; when present it links this plan to its parent revision in immutable history.",
      "minLength": 1,
      "type": "string"
    },
    "scaffold_rule": {
      "minLength": 1,
      "type": "string"
    },
    "schema_version": {
      "description": "Major-version-locked envelope. 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"
    },
    "selected_scaffold_files": {
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "status": {
      "const": "REVIEW_ONLY",
      "type": "string"
    },
    "unresolved_evidence": {
      "type": "array"
    }
  },
  "required": [
    "schema_version",
    "digest",
    "before_state_digest",
    "desired_state_digest",
    "operations",
    "ownership_class",
    "conflict_classification"
  ],
  "title": "Scaffold Plan",
  "type": "object"
}