Polisher-Control/shared/schemas/controller-job.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://polisher-suite.local/schemas/controller-job.schema.json",
  "title": "Controller Job Package",
  "description": "Translated execution package produced by polisher-post for polisher-control. Represents translated truth.",
  "type": "object",
  "required": [
    "schema_version",
    "controller_job_id",
    "job_id",
    "machine_id",
    "machine_capabilities_ref",
    "controller_version",
    "translated_at",
    "translated_by",
    "segments",
    "translation_losses"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "controller-job.v1"
    },
    "controller_job_id": {
      "type": "string",
      "description": "Stable unique identifier for this translated package."
    },
    "job_id": {
      "type": "string",
      "description": "Back-reference to the source planning job."
    },
    "machine_id": {
      "type": "string",
      "description": "Target machine identifier."
    },
    "machine_capabilities_ref": {
      "type": "string",
      "description": "Reference to the machine-capabilities document used for translation."
    },
    "controller_version": {
      "type": "string",
      "description": "Target controller software version."
    },
    "translated_at": {
      "type": "string",
      "format": "date-time"
    },
    "translated_by": {
      "type": "string",
      "description": "polisher-post version that performed the translation."
    },
    "translation_notes": {
      "type": "string",
      "description": "Summary of constraints applied during translation."
    },
    "segments": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/segment"
      }
    },
    "translation_losses": {
      "type": "array",
      "description": "Explicit record of every constraint, clip, or approximation applied.",
      "items": {
        "type": "object",
        "required": [
          "source_pass_id",
          "field",
          "description"
        ],
        "properties": {
          "source_pass_id": {
            "type": "string"
          },
          "field": {
            "type": "string"
          },
          "planned_value": {},
          "translated_value": {},
          "description": {
            "type": "string"
          }
        }
      }
    }
  },
  "$defs": {
    "segment": {
      "type": "object",
      "required": [
        "segment_id",
        "sequence_index",
        "source_pass_id",
        "duration_s",
        "commanded_force_n",
        "commanded_table_rpm",
        "commanded_spindle_rpm",
        "commanded_spindle_direction"
      ],
      "properties": {
        "segment_id": {
          "type": "string"
        },
        "sequence_index": {
          "type": "integer",
          "minimum": 1
        },
        "source_pass_id": {
          "type": "string",
          "description": "Back-reference to the planning pass this segment came from."
        },
        "duration_s": {
          "type": "number",
          "minimum": 0
        },
        "commanded_force_n": {
          "type": "number",
          "minimum": 0
        },
        "commanded_table_rpm": {
          "type": "number",
          "minimum": 0
        },
        "commanded_spindle_rpm": {
          "type": "number",
          "minimum": 0
        },
        "commanded_cam_amplitude_deg": {
          "type": "number"
        },
        "commanded_cam_offset_deg": {
          "type": "number"
        },
        "force_modulation": {
          "type": "object",
          "properties": {
            "harmonic": {
              "type": "integer"
            },
            "amplitude_n": {
              "type": "number"
            },
            "phase_deg": {
              "type": "number"
            }
          }
        },
        "dither_profile": {
          "type": "string"
        },
        "notes": {
          "type": "string"
        },
        "commanded_spindle_direction": {
          "type": "string",
          "enum": [
            "cw",
            "ccw"
          ],
          "description": "Toolhead spindle rotation direction, as viewed from above the toolhead looking down toward the mirror/tool contact. ODrive sign mapping is commissioned to match this physical convention."
        }
      }
    }
  }
}