docs: scaffold polisher-control foundation

2026-05-26 16:23:04 +00:00
commit fa9c43fae8
52 changed files with 2224 additions and 0 deletions
--- a/shared/schemas/run-log.schema.json
+++ b/shared/schemas/run-log.schema.json
@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://polisher-suite.local/schemas/run-log.schema.json",
+  "title": "Run Log",
+  "description": "Canonical execution record emitted by polisher-control. Represents executed truth.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "run_id",
+    "job_id",
+    "controller_job_id",
+    "controller_version",
+    "machine_id",
+    "started_at",
+    "ended_at",
+    "result_state",
+    "segments"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "run-log.v1"
+    },
+    "run_id": {
+      "type": "string",
+      "description": "Stable unique identifier for this execution run."
+    },
+    "job_id": {
+      "type": "string",
+      "description": "Back-reference to the source planning job."
+    },
+    "controller_job_id": {
+      "type": "string",
+      "description": "Back-reference to the translated controller-job package."
+    },
+    "controller_version": {
+      "type": "string"
+    },
+    "machine_id": {
+      "type": "string"
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "ended_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "result_state": {
+      "type": "string",
+      "enum": ["completed", "completed_with_pause", "aborted", "faulted"]
+    },
+    "segments": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/executed_segment"
+      }
+    },
+    "commanded_summary": {
+      "type": "object",
+      "properties": {
+        "force_n": { "type": "number" },
+        "table_rpm": { "type": "number" },
+        "spindle_rpm": { "type": "number" }
+      }
+    },
+    "actual_summary": {
+      "type": "object",
+      "properties": {
+        "force_n_mean": { "type": "number" },
+        "force_n_min": { "type": "number" },
+        "force_n_max": { "type": "number" },
+        "table_rpm_mean": { "type": "number" },
+        "spindle_rpm_mean": { "type": "number" }
+      }
+    },
+    "alarms": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["timestamp", "code", "message"],
+        "properties": {
+          "timestamp": { "type": "string", "format": "date-time" },
+          "code": { "type": "string" },
+          "message": { "type": "string" },
+          "severity": { "type": "string", "enum": ["info", "warning", "critical"] }
+        }
+      }
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["timestamp", "type"],
+        "properties": {
+          "timestamp": { "type": "string", "format": "date-time" },
+          "type": { "type": "string" },
+          "detail": { "type": "string" }
+        }
+      }
+    },
+    "telemetry_ref": {
+      "type": "string",
+      "description": "Filename or path to the raw telemetry data file."
+    },
+    "operator_notes": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "executed_segment": {
+      "type": "object",
+      "required": [
+        "segment_id",
+        "source_pass_id",
+        "commanded_duration_s",
+        "actual_duration_s",
+        "result_state"
+      ],
+      "properties": {
+        "segment_id": { "type": "string" },
+        "source_pass_id": { "type": "string" },
+        "commanded_duration_s": { "type": "number" },
+        "actual_duration_s": { "type": "number" },
+        "result_state": {
+          "type": "string",
+          "enum": ["completed", "completed_with_pause", "aborted", "faulted", "skipped"]
+        },
+        "commanded": {
+          "type": "object",
+          "properties": {
+            "force_n": { "type": "number" },
+            "table_rpm": { "type": "number" },
+            "spindle_rpm": { "type": "number" },
+            "cam_amplitude_deg": { "type": "number" },
+            "cam_offset_deg": { "type": "number" }
+          }
+        },
+        "actual": {
+          "type": "object",
+          "properties": {
+            "force_n_mean": { "type": "number" },
+            "force_n_min": { "type": "number" },
+            "force_n_max": { "type": "number" },
+            "table_rpm_mean": { "type": "number" },
+            "spindle_rpm_mean": { "type": "number" }
+          }
+        },
+        "pause_windows": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["paused_at", "resumed_at"],
+            "properties": {
+              "paused_at": { "type": "string", "format": "date-time" },
+              "resumed_at": { "type": "string", "format": "date-time" },
+              "reason": { "type": "string" }
+            }
+          }
+        },
+        "anomaly_flags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "notes": { "type": "string" }
+      }
+    }
+  }
+}