[fm] Add guardrails for fact payload representations

nexus/fm/Cargo.toml

@@ -38,3 +38,7 @@ omicron-workspace-hack.workspace = true
 omicron-test-utils.workspace = true
 nexus-reconfigurator-planning.workspace = true
 ereport-types.workspace = true
+expectorate.workspace = true
+schemars.workspace = true
+strum.workspace = true
+omicron-uuid-kinds = { workspace = true, features = ["schemars08"] }

nexus/fm/output/README.md

@@ -0,0 +1,23 @@
+# FM fact payload guardrail goldens
+
+These files snapshot the persisted representation of every fault-management
+diagnosis engine (DE) fact payload, which is serialized into the opaque
+`fm_fact.payload` JSONB column:
+
+- `fm_fact_payload_schemas.json` — the JSON **schema** of each DE's payload type
+  (structure: variants, fields, types, and embedded-enum domains). Human-readable
+  `description` text is stripped before snapshotting, so editing a doc comment
+  (here or on an embedded type) does not register as a shape change.
+- `fm_fact_payload_samples.json` — one obviously-fake serialized **sample** per
+  payload variant (the exact on-disk bytes).
+
+They are checked by the `payload_stability` tests in
+`nexus/fm/src/diagnosis/mod.rs`. **If a test points you here, you changed the
+serialized shape of a persisted fact payload — that is a data migration**, not
+just a code change, because deployed databases already hold rows in the old
+shape.
+
+Before regenerating with `EXPECTORATE=overwrite cargo nextest run -p nexus-fm`,
+read the "Evolving persisted fact payloads" guidance at the top of
+`nexus/fm/src/diagnosis/mod.rs` to decide whether the change is additive
+(serde-compatible) or breaking (needs a JSONB data migration).

nexus/fm/output/fm_fact_payload_samples.json

@@ -0,0 +1,10 @@
+{
+  "physical_disk::zpool_unhealthy": {
+    "kind": "zpool_unhealthy",
+    "last_seen_health": "faulted",
+    "observed_in_inv": "33333333-3333-3333-3333-333333333333",
+    "physical_disk_id": "11111111-1111-1111-1111-111111111111",
+    "time_observed": "2000-01-01T00:00:00Z",
+    "zpool_id": "22222222-2222-2222-2222-222222222222"
+  }
+}

nexus/fm/output/fm_fact_payload_schemas.json

@@ -0,0 +1,124 @@
+{
+  "physical_disk": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "definitions": {
+      "CollectionUuid": {
+        "format": "uuid",
+        "type": "string",
+        "x-rust-type": {
+          "crate": "omicron-uuid-kinds",
+          "path": "omicron_uuid_kinds::CollectionUuid",
+          "version": "*"
+        }
+      },
+      "PhysicalDiskUuid": {
+        "format": "uuid",
+        "type": "string",
+        "x-rust-type": {
+          "crate": "omicron-uuid-kinds",
+          "path": "omicron_uuid_kinds::PhysicalDiskUuid",
+          "version": "*"
+        }
+      },
+      "ZpoolHealth": {
+        "oneOf": [
+          {
+            "enum": [
+              "online"
+            ],
+            "type": "string"
+          },
+          {
+            "enum": [
+              "degraded"
+            ],
+            "type": "string"
+          },
+          {
+            "enum": [
+              "faulted"
+            ],
+            "type": "string"
+          },
+          {
+            "enum": [
+              "offline"
+            ],
+            "type": "string"
+          },
+          {
+            "enum": [
+              "removed"
+            ],
+            "type": "string"
+          },
+          {
+            "enum": [
+              "unavailable"
+            ],
+            "type": "string"
+          }
+        ]
+      },
+      "ZpoolUuid": {
+        "format": "uuid",
+        "type": "string",
+        "x-rust-type": {
+          "crate": "omicron-uuid-kinds",
+          "path": "omicron_uuid_kinds::ZpoolUuid",
+          "version": "*"
+        }
+      }
+    },
+    "oneOf": [
+      {
+        "properties": {
+          "kind": {
+            "enum": [
+              "zpool_unhealthy"
+            ],
+            "type": "string"
+          },
+          "last_seen_health": {
+            "$ref": "#/definitions/ZpoolHealth"
+          },
+          "observed_in_inv": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/CollectionUuid"
+              }
+            ]
+          },
+          "physical_disk_id": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/PhysicalDiskUuid"
+              }
+            ]
+          },
+          "time_observed": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "zpool_id": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/ZpoolUuid"
+              }
+            ]
+          }
+        },
+        "required": [
+          "kind",
+          "last_seen_health",
+          "observed_in_inv",
+          "physical_disk_id",
+          "time_observed",
+          "zpool_id"
+        ],
+        "type": "object"
+      }
+    ],
+    "title": "DiskFact"
+  }
+}