=== META ===
{
  "id": "GTPX-PATCH-MODEL",
  "title": "GTPX Patch Model",
  "version": "0.2.0",
  "status": "draft",
  "updated": "2026-04-26",
  "authority": "09_runtime/GTPX-PATCH-MODEL.gtpx",
  "type": "runtime_patch",
  "project": "GTPX",
  "depends_on": [
    "09_runtime/GTPX-RUNTIME-MODEL.gtpx",
    "09_runtime/GTPX-DRY-RUN-MODEL.gtpx",
    "07_validation/GTPX-HASH-NORMALIZATION.gtpx"
  ]
}

=== DATA ===
{
  "purpose": "Defines how changes are proposed, validated, and applied in GTPX, including a canonical executable patch structure.",

  "patch_definition": "A patch is an explicit, structured, deterministic, and validated modification to an existing state, document, or execution context.",

  "patch_policy": {
    "patch_must_be_explicit": true,
    "patch_must_be_structured": true,
    "patch_must_be_deterministic": true,
    "patch_must_be_validated_before_commit": true,
    "implicit_changes_are_forbidden": true
  },

  "patch_lifecycle": [
    "propose_patch",
    "validate_patch",
    "dry_run_patch",
    "approve_patch",
    "commit_patch"
  ],

  "lifecycle_definitions": {
    "propose_patch": "Defines a structured change proposal.",
    "validate_patch": "Ensures patch follows contract and validation rules.",
    "dry_run_patch": "Simulates the effect of the patch.",
    "approve_patch": "Confirms patch is accepted for application.",
    "commit_patch": "Applies the patch as a real change."
  },

  "patch_structure": {
    "required_fields": [
      "patch_id",
      "target",
      "change_type",
      "before_state",
      "after_state",
      "justification"
    ]
  },

  "field_definitions": {
    "patch_id": "Unique identifier of the patch.",
    "target": "Defines what is being changed.",
    "change_type": "Defines type of change (add, modify, remove).",
    "before_state": "Defines current state.",
    "after_state": "Defines new state.",
    "justification": "Explains why the change is needed."
  },

  "canonical_patch_object": {
    "description": "Defines the executable canonical patch format used by runtime systems such as Synarch and Patch Manager.",

    "structure": {
      "meta": {
        "patch_id": "string",
        "patch_version": "string",
        "change_request_id": "string",
        "created_at": "timestamp",
        "created_by": "string",
        "status": "patch_status"
      },

      "context": {
        "plan_id": "string",
        "plan_version_before": "string",
        "plan_version_after": "string|null",
        "source_bundle_hash": "string"
      },

      "target": {
        "target_type": "string",
        "target_path": "string",
        "target_encoding": "UTF-8"
      },

      "operation": {
        "operation": "replace|insert_before|insert_after|append|prepend|create_file|delete_file|rename_file"
      },

      "match": {
        "match_type": "exact_string|regex|line_number|file_exists",
        "search_pattern": "string",
        "expected_match_count": "number",
        "allow_multiple_matches": "boolean"
      },

      "change": {
        "before_state": "string",
        "after_state": "string",
        "replace_content": "string",
        "position": "number|null"
      },

      "validation": {
        "required_checks": [
          "target_exists",
          "encoding_valid",
          "match_count_valid",
          "operation_valid",
          "result_hash_valid"
        ],
        "fail_policy": "fail_closed"
      },

      "dry_run": {
        "dry_run_required": "boolean",
        "dry_run_status": "validation_outcomes|null",
        "diff_required": "boolean",
        "risk_level": "low|medium|high|null"
      },

      "commit": {
        "commit_allowed": "boolean",
        "requires_passed_dry_run": "boolean",
        "backup_required": "boolean",
        "before_hash": "string|null",
        "after_hash": "string|null",
        "backup_path": "string|null"
      },

      "audit": {
        "audit_required": "boolean",
        "audit_id": "string|null",
        "audit_path": "string|null",
        "executor": "string|null",
        "result": "string|null"
      }
    }
  },

  "execution_requirements": [
    "patch_execution_must_be_deterministic",
    "same_input_must_produce_same_output",
    "match_result_must_be_unique_unless_explicitly_allowed",
    "dry_run_must_precede_commit",
    "commit_requires_backup",
    "all_changes_must_be_audited"
  ]
}

=== RULES ===
{
  "patch_id_must_be_unique": true,
  "patch_must_define_before_and_after": true,
  "patch_must_be_validated": true,
  "patch_must_support_dry_run": true,
  "patch_without_justification_is_invalid": true,
  "patch_must_be_traceable": true,
  "canonical_patch_object_is_authoritative_for_execution": true,
  "legacy_patch_structure_is_allowed_for_compatibility": true,
  "execution_must_follow_canonical_patch_object": true
}

=== STATUS ===
{
  "state": "draft",
  "open_questions": [
    "Confirm if patch approval must be human-only or can be automated.",
    "Confirm if batch patches are allowed.",
    "Define risk_level enum in GTPX-ENUMS",
    "Define execution error mapping"
  ],
  "next_step": "Align Patch Manager PRQ with canonical_patch_object and remove local patch spec duplication."
}