Schema: desired-state

{
  "$id": "https://australis.systems/schemas/htmx-ui-template-scaffold/desired-state.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Normalized target structure describing what each scaffolded artifact should become. Each entry pairs the current on-disk content digest (before_digest, or null when absent) with the proposed normalized content digest (desired_digest). The desired state feeds the diff step that produces a plan.",
  "properties": {
    "entries": {
      "description": "Ordered per-path entries from the desired-state diff. Order is stable for digest reproducibility.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "before_digest": {
            "description": "SHA-256 hex digest of the on-disk content BEFORE the operation (lowercase, 64 hex characters). Producers emit the empty-content SHA-256 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' for absent files; consumers MUST treat that exact digest as 'file absent'.",
            "pattern": "^[a-f0-9]{64}$",
            "type": "string"
          },
          "desired_digest": {
            "description": "SHA-256 hex digest of the canonical normalized content the operation should leave on disk.",
            "pattern": "^[a-f0-9]{64}$",
            "type": "string"
          },
          "kind": {
            "description": "Scaffolded artifact kind. Lets downstream tooling select the right verification path.",
            "enum": [
              "ROUTE_PAGE",
              "PARTIAL",
              "LAYOUT",
              "MACRO",
              "INTERACTIVE_COMPONENT",
              "FRAGMENT",
              "STATIC"
            ],
            "type": "string"
          },
          "path": {
            "description": "Target-relative path within the application anchor at which the entry should exist.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "path",
          "before_digest",
          "desired_digest",
          "kind"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "revision_id": {
      "description": "Optional revision identifier; when present it links this desired state to its parent revision in immutable history.",
      "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"
    }
  },
  "required": [
    "schema_version",
    "entries"
  ],
  "title": "Desired State",
  "type": "object"
}