docs: scaffold polisher-control foundation

shared/schemas/machine-capabilities.schema.json

@@ -0,0 +1,135 @@
+{
+  "$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"
+  ],
+  "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."
+    }
+  },
+  "$defs": {
+    "range_or_unknown": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": { "type": "number" },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "[min, max] range."
+        },
+        {
+          "type": "string",
+          "const": "unknown"
+        }
+      ]
+    }
+  }
+}