From f9628ef1eeb7d08bae61e5880ca1141fccfb425c Mon Sep 17 00:00:00 2001
From: Michael Heller <21163552+mdheller@users.noreply.github.com>
Date: Sat, 4 Jul 2026 21:09:26 -0400
Subject: [PATCH] fix(ci): repair the Validate Spec workflow + complete the
 CompressionEvaluation schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two coupled fixes that green the last dark workflow on main:

1. .github/workflows/validate.yml failed in 0s on EVERY commit for weeks
   ('workflow file issue') because two step 'name:' values contained an
   unquoted colon ('Guardrail: detect ...'), which YAML parses as a nested
   mapping — GitHub rejected the whole file. Quoted both names.

2. Un-breaking the workflow makes its dormant jobs run, which unmasked one
   content failure: examples/compressionevaluation.json carried fields absent
   from schemas/CompressionEvaluation.json (additionalProperties:false):
   truthSurfaceRef, deltaSurfaceRef, integrity{evaluationHash,signer,signature,
   signedAt}, notes, plus metrics.supportingMetrics + metrics.normalizationVersion.
   These are intentional (surface refs + signed integrity envelope), so added
   them to the schema as optional — additive, non-breaking.

Verified locally: validate.yml parses; all 263 top-level schemas compile under
ajv; both guardrail scripts pass; by-type example validation 170 pass / 0 fail;
openapi/asyncapi/jsonld parse; make validate green end-to-end.
---
 .github/workflows/validate.yml     |  4 ++--
 schemas/CompressionEvaluation.json | 33 +++++++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 849d2ff..8a39fb8 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -42,11 +42,11 @@ jobs:
           done
           exit $failed
 
-      - name: Guardrail: detect duplicate schema $id values
+      - name: "Guardrail: detect duplicate schema $id values"
         run: |
           python3 scripts/check_duplicate_schema_ids.py
 
-      - name: Guardrail: control-plane canonical wrapper $id resolution
+      - name: "Guardrail: control-plane canonical wrapper $id resolution"
         run: |
           python3 scripts/validate_control_plane_wrapper_ids.py
 
diff --git a/schemas/CompressionEvaluation.json b/schemas/CompressionEvaluation.json
index 0bb8927..a519be8 100644
--- a/schemas/CompressionEvaluation.json
+++ b/schemas/CompressionEvaluation.json
@@ -79,8 +79,14 @@
       "properties": {
         "novelty": { "type": "number", "description": "Primary novelty signal." },
         "redundancy": { "type": "number", "description": "Primary redundancy signal." },
+        "supportingMetrics": {
+          "type": ["object", "null"],
+          "additionalProperties": { "type": "number" },
+          "description": "Optional named supporting metrics (e.g. support, stability)."
+        },
         "confidence": { "type": ["number", "null"], "description": "Optional confidence score." },
-        "warnings": { "type": "array", "items": { "type": "string" }, "description": "Optional warnings." }
+        "warnings": { "type": "array", "items": { "type": "string" }, "description": "Optional warnings." },
+        "normalizationVersion": { "type": ["string", "null"], "description": "Optional version of the metric normalization applied." }
       }
     },
     "policyDecisionRef": {
@@ -98,6 +104,31 @@
       "pattern": "^urn:srcos:prov:",
       "description": "Optional provenance reference."
     },
+    "truthSurfaceRef": {
+      "type": ["string", "null"],
+      "pattern": "^urn:srcos:truth-surface:",
+      "description": "Optional reference to the truth surface this evaluation is grounded against."
+    },
+    "deltaSurfaceRef": {
+      "type": ["string", "null"],
+      "pattern": "^urn:srcos:delta-surface:",
+      "description": "Optional reference to the delta surface produced by this evaluation."
+    },
+    "integrity": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Optional signed integrity envelope for the evaluation record.",
+      "properties": {
+        "evaluationHash": { "type": "string", "description": "Content hash of the evaluation." },
+        "signer": { "type": ["string", "null"], "description": "Identity of the signer." },
+        "signature": { "type": ["string", "null"], "description": "Detached signature over the evaluation hash." },
+        "signedAt": { "type": ["string", "null"], "format": "date-time", "description": "Signing timestamp." }
+      }
+    },
+    "notes": {
+      "type": ["string", "null"],
+      "description": "Optional human-readable notes."
+    },
     "createdAt": {
       "type": "string",
       "format": "date-time",