Fix #149: [milestone Milestone 5 ] Pipeline health and SLA monitoring — add end-to-end latency tracking, per-stag...

schemas/index.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "protocol": "AEP",
-  "description": "Registry of canonical WasmAgent protocol schemas \u2014 the single source of truth for every cross-repository contract. Downstream repos consume via @wasmagent/protocol (npm) and wasmagent-protocol (PyPI). Covers: AEP, compliance, AgentBOM, MCP Posture, Trust Passport.",
+  "description": "Registry of canonical WasmAgent protocol schemas \u2014 the single source of truth for every cross-repository contract. Downstream repos consume via @wasmagent/protocol (npm) and wasmagent-protocol (PyPI). Covers: AEP, compliance, AgentBOM, MCP Posture, Trust Passport, Pipeline health.",
   "canonical_host": "https://wasmagent.dev/schemas/",
   "schemas": [
     {
@@ -184,6 +184,54 @@
         "open-agent-audit"
       ],
       "summary": "Trust Passport \u2014 signed, expiring, verifiable trust-state artifact for AI agents."
+    },
+    {
+      "id": "pipeline-health-record",
+      "title": "PipelineHealthRecord",
+      "path": "schemas/pipeline/pipeline-health-record.schema.json",
+      "canonical_id": "https://wasmagent.dev/schemas/pipeline/pipeline-health-record.schema.json",
+      "version": "pipeline-health-record/v1",
+      "stability": "evolving",
+      "owners": [
+        "trace-pipeline"
+      ],
+      "consumers": [
+        "trace-pipeline",
+        "wasmagent-ops"
+      ],
+      "summary": "Composite pipeline health snapshot \u2014 rolls up end-to-end latency, per-stage success rates, backlog/alert status, and the schema-evolution canary result shared across the production trace pipeline."
+    },
+    {
+      "id": "sla-metrics",
+      "title": "SlaMetrics",
+      "path": "schemas/pipeline/sla-metrics.schema.json",
+      "canonical_id": "https://wasmagent.dev/schemas/pipeline/sla-metrics.schema.json",
+      "version": "sla-metrics/v1",
+      "stability": "evolving",
+      "owners": [
+        "trace-pipeline"
+      ],
+      "consumers": [
+        "trace-pipeline",
+        "wasmagent-ops"
+      ],
+      "summary": "Latency and per-stage success-rate measurements for a pipeline window \u2014 end-to-end latency tracking and per-stage success rates."
+    },
+    {
+      "id": "backlog-status",
+      "title": "BacklogStatus",
+      "path": "schemas/pipeline/backlog-status.schema.json",
+      "canonical_id": "https://wasmagent.dev/schemas/pipeline/backlog-status.schema.json",
+      "version": "backlog-status/v1",
+      "stability": "evolving",
+      "owners": [
+        "trace-pipeline"
+      ],
+      "consumers": [
+        "trace-pipeline",
+        "wasmagent-ops"
+      ],
+      "summary": "Point-in-time backlog state for a single pipeline queue \u2014 drives alerting on backlog buildup (depth/age threshold breaches)."
     }
   ]
 }

schemas/pipeline/backlog-status.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wasmagent.dev/schemas/pipeline/backlog-status.schema.json",
+  "title": "BacklogStatus",
+  "description": "Point-in-time backlog state for a single pipeline queue (backlog-status/v1). Drives alerting on backlog buildup: when depth or oldest-item age breaches a threshold, or arrival exceeds drain, the queue is accumulating work faster than it can drain. Emitted by trace-pipeline and consumed by wasmagent-ops; rolled up into pipeline-health-record alerts as backlog_buildup.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "pipeline_id",
+    "queue",
+    "measured_at_ms",
+    "depth",
+    "arrival_rate_per_second",
+    "drain_rate_per_second",
+    "breaches_threshold"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "backlog-status/v1",
+      "description": "Schema version identifier. Always 'backlog-status/v1'."
+    },
+    "pipeline_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "queue": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the queue/stage this backlog describes (e.g. 'validation', 'ingest')."
+    },
+    "measured_at_ms": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "depth": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Current number of unprocessed items in the queue."
+    },
+    "oldest_item_age_ms": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Age of the oldest unprocessed item in milliseconds."
+    },
+    "arrival_rate_per_second": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Mean rate at which items are entering the queue."
+    },
+    "drain_rate_per_second": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Mean rate at which items are leaving the queue (processed or dropped)."
+    },
+    "growth_rate_per_second": {
+      "type": "number",
+      "description": "arrival_rate_per_second - drain_rate_per_second. Positive values indicate buildup."
+    },
+    "high_watermark": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Maximum observed depth over the measurement window."
+    },
+    "threshold_depth": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Alert threshold for depth; depth above this triggers backlog_buildup alerting."
+    },
+    "threshold_age_ms": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Alert threshold for oldest_item_age_ms."
+    },
+    "breaches_threshold": {
+      "type": "boolean",
+      "description": "True iff depth > threshold_depth OR oldest_item_age_ms > threshold_age_ms (for whichever thresholds are set). Rolled up into pipeline-health-record alerts."
+    }
+  }
+}

schemas/pipeline/pipeline-health-record.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wasmagent.dev/schemas/pipeline/pipeline-health-record.schema.json",
+  "title": "PipelineHealthRecord",
+  "description": "Composite pipeline health snapshot (pipeline-health-record/v1). Rolls up SLA metrics (end-to-end latency + per-stage success rates), per-queue backlog status, active alerts (validation failures, backlog buildup, latency SLO breaches, canary failures), and the result of automated schema-evolution canary testing against wasmagent-protocol updates. Single source of truth shared by trace-pipeline (emitter) and wasmagent-ops (consumer).",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "pipeline_id",
+    "recorded_at_ms",
+    "overall_status",
+    "sla",
+    "alerts",
+    "canary"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "pipeline-health-record/v1",
+      "description": "Schema version identifier. Always 'pipeline-health-record/v1'."
+    },
+    "pipeline_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "recorded_at_ms": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "overall_status": {
+      "type": "string",
+      "enum": [
+        "healthy",
+        "degraded",
+        "unhealthy"
+      ],
+      "description": "Derived rollup: healthy = no alerts and SLOs met; degraded = warning alerts or near-breach; unhealthy = critical alert or SLO breach."
+    },
+    "sla": {
+      "$ref": "sla-metrics.schema.json",
+      "description": "Latency and per-stage success-rate measurements for this snapshot's window."
+    },
+    "backlogs": {
+      "type": "array",
+      "description": "Per-queue backlog status. Queues whose breaches_threshold is true SHOULD also appear as backlog_buildup alerts.",
+      "items": {
+        "$ref": "backlog-status.schema.json"
+      }
+    },
+    "alerts": {
+      "type": "array",
+      "description": "Active alerts fired in this snapshot's window. validation_failure covers schema/validation rejections; backlog_buildup covers queue depth/age breaches.",
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "severity",
+          "message",
+          "first_observed_at_ms"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "validation_failure",
+              "backlog_buildup",
+              "latency_slo_breach",
+              "canary_failure"
+            ]
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "info",
+              "warning",
+              "critical"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "description": "Optional pipeline stage/queue the alert is scoped to."
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1
+          },
+          "first_observed_at_ms": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "count": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Number of occurrences in the window."
+          }
+        }
+      }
+    },
+    "canary": {
+      "type": "object",
+      "description": "Result of automated canary testing of schema evolution: the pipeline re-runs its validation fixtures against a candidate wasmagent-protocol update before adoption, so a breaking schema change fails here instead of in production.",
+      "required": [
+        "protocol_version",
+        "status",
+        "checked_at_ms"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "protocol_version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The wasmagent-protocol package version the canary validated against (e.g. '0.1.7')."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pass",
+            "fail",
+            "skipped"
+          ],
+          "description": "pass = all sampled fixtures still validate under the candidate protocol; fail = at least one broke (also surfaces a canary_failure alert); skipped = canary not run."
+        },
+        "schemas_checked": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of canonical schemas exercised by the canary."
+        },
+        "failures": {
+          "type": "array",
+          "description": "Per-fixture canary failures. SHOULD be non-empty iff status is 'fail'.",
+          "items": {
+            "type": "object",
+            "required": [
+              "schema_id",
+              "fixture",
+              "reason"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "schema_id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "fixture": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Path/id of the fixture that regressed."
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "checked_at_ms": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}