Polisher-Control/shared/schemas/machine-capabilities.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://polisher-suite.local/schemas/machine-capabilities.schema.json",
  "title": "Machine Capabilities",
  "description": "Conservative declaration of what a machine+controller can safely execute. Unknown capabilities must be explicitly marked rather than assumed.",
  "type": "object",
  "required": [
    "schema_version",
    "machine_id",
    "machine_family",
    "controller_version",
    "supported_motion_families",
    "force_range_n",
    "table_rpm_range",
    "spindle_rpm_range",
    "supported_spindle_directions"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "machine-capabilities.v1"
    },
    "machine_id": {
      "type": "string"
    },
    "machine_family": {
      "type": "string"
    },
    "machine_name": {
      "type": "string"
    },
    "controller_version": {
      "type": "string"
    },
    "last_verified": {
      "type": "string",
      "format": "date-time",
      "description": "When these capabilities were last confirmed on the real machine."
    },
    "supported_motion_families": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "force_range_n": {
      "$ref": "#/$defs/range_or_unknown"
    },
    "table_rpm_range": {
      "$ref": "#/$defs/range_or_unknown"
    },
    "spindle_rpm_range": {
      "$ref": "#/$defs/range_or_unknown"
    },
    "cam_amplitude_range_deg": {
      "$ref": "#/$defs/range_or_unknown"
    },
    "cam_offset_range_deg": {
      "$ref": "#/$defs/range_or_unknown"
    },
    "force_modulation": {
      "type": "object",
      "description": "Force modulation capabilities. Omit entirely if unknown.",
      "properties": {
        "supported": {
          "type": "boolean"
        },
        "max_harmonics": {
          "type": "integer"
        },
        "max_amplitude_n": {
          "type": "number"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "supported_dither_profiles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of dither profile names the controller can handle. Empty = none supported."
    },
    "segment_duration_limits": {
      "type": "object",
      "properties": {
        "min_s": {
          "type": "number"
        },
        "max_s": {
          "type": "number"
        }
      }
    },
    "pause_resume_support": {
      "type": "boolean"
    },
    "telemetry_channels": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "unit"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "sample_rate_hz": {
            "type": "number"
          },
          "notes": {
            "type": "string"
          }
        }
      }
    },
    "safety_limits": {
      "type": "object",
      "description": "Hard safety limits that the controller enforces regardless of job requests.",
      "properties": {
        "max_force_n": {
          "type": "number"
        },
        "max_table_rpm": {
          "type": "number"
        },
        "max_spindle_rpm": {
          "type": "number"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "known_constraints": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-text list of known limitations, quirks, or warnings."
    },
    "unknowns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Capabilities that have NOT been verified. Explicit unknowns prevent fake certainty."
    },
    "supported_spindle_directions": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "cw",
          "ccw"
        ]
      },
      "minItems": 1,
      "uniqueItems": true,
      "description": "Toolhead spindle rotation directions supported by the controller UI/protocol."
    }
  },
  "$defs": {
    "range_or_unknown": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "number"
          },
          "minItems": 2,
          "maxItems": 2,
          "description": "[min, max] range."
        },
        {
          "type": "string",
          "const": "unknown"
        }
      ]
    }
  }
}