From 9b69be8ab53c436763a9e1f20ef116d1fdc91fa2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Fri, 31 Jul 2026 01:15:45 +0200
Subject: [PATCH] fix(openapi): declare shrunkR and tier on
 DiscoveredCorrelation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The correlation-discovery engine always sets shrunkR (the
sample-size-shrunk effect) and tier (the phrasing-confidence class)
on every surfaced pair, but the closed DiscoveredCorrelation schema
never declared either — same defect class as the dashboard snapshot:
additionalProperties: false rejecting a field the runtime actually
sends. Both are required, matching src/lib/insights/correlation-discovery.ts.
---
 docs/api/openapi.yaml                      | 14 ++++++++++++++
 src/lib/openapi/routes/insights/schemas.ts | 10 ++++++++++
 2 files changed, 24 insertions(+)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 9bf7231e3..b3441a552 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -29870,6 +29870,18 @@ components:
         qValue:
           type: number
           description: Benjamini-Hochberg FDR-adjusted q-value (≤ the surface threshold).
+        shrunkR:
+          type: number
+          description: Sample-size-shrunk effect (r shrunk toward null by depth), used for ranking and the effect-size floor.
+            Display still uses raw `r`.
+        tier:
+          type: string
+          enum:
+            - high
+            - moderate
+            - faint
+          description: "Phrasing-confidence tier the narration honours: `faint` is hedged, `high` is stated plainly, `moderate`
+            sits between. A below-floor pair never reaches this list."
         interpretation:
           type: string
           description: Conservative, descriptive interpretation — never causal.
@@ -29904,6 +29916,8 @@ components:
         - r
         - pValue
         - qValue
+        - shrunkR
+        - tier
         - interpretation
         - lagDays
       additionalProperties: false
diff --git a/src/lib/openapi/routes/insights/schemas.ts b/src/lib/openapi/routes/insights/schemas.ts
index 93ecf9f55..2e3c51ffd 100644
--- a/src/lib/openapi/routes/insights/schemas.ts
+++ b/src/lib/openapi/routes/insights/schemas.ts
@@ -303,6 +303,16 @@ export const discoveredCorrelation = z
       .describe(
         "Benjamini-Hochberg FDR-adjusted q-value (≤ the surface threshold).",
       ),
+    shrunkR: z
+      .number()
+      .describe(
+        "Sample-size-shrunk effect (r shrunk toward null by depth), used for ranking and the effect-size floor. Display still uses raw `r`.",
+      ),
+    tier: z
+      .enum(["high", "moderate", "faint"])
+      .describe(
+        "Phrasing-confidence tier the narration honours: `faint` is hedged, `high` is stated plainly, `moderate` sits between. A below-floor pair never reaches this list.",
+      ),
     interpretation: z
       .string()
       .describe("Conservative, descriptive interpretation — never causal."),