@shipeasy/openapi 2.2.0 → 2.4.0

package/spec/components/schemas/experiments.yaml

@@ -4,149 +4,7 @@ ListExperimentsResponse:
     data:
       type: array
       items:
-        type: object
-        properties:
-          id:
-            type: string
-            description: Stable opaque experiment id (`exp_…`).
-          name:
-            type: string
-            maxLength: 128
-            pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
-            description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
-          description:
-            anyOf:
-              - type: string
-              - type: "null"
-          hypothesis:
-            anyOf:
-              - type: string
-              - type: "null"
-          tag:
-            anyOf:
-              - type: string
-              - type: "null"
-          ownerEmail:
-            anyOf:
-              - type: string
-              - type: "null"
-          audience:
-            anyOf:
-              - type: string
-              - type: "null"
-          bucketBy:
-            anyOf:
-              - type: string
-                minLength: 1
-                maxLength: 128
-                pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
-                description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
-              - type: "null"
-          folder:
-            anyOf:
-              - type: string
-              - type: "null"
-          status:
-            type: string
-            enum:
-              - draft
-              - running
-              - stopped
-              - archived
-          universe:
-            type: string
-            description: Universe name this experiment draws from.
-          targetingGate:
-            anyOf:
-              - type: string
-              - type: "null"
-          allocationPct:
-            type: integer
-            minimum: -9007199254740991
-            maximum: 9007199254740991
-            description: Allocation in basis points (0–10000).
-          salt:
-            type: string
-          params:
-            type: object
-            additionalProperties:
-              type: string
-              enum:
-                - string
-                - bool
-                - number
-          groups:
-            type: array
-            items:
-              type: object
-              properties:
-                name:
-                  type: string
-                  minLength: 1
-                  maxLength: 64
-                  description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
-                weight:
-                  type: integer
-                  minimum: 0
-                  maximum: 10000
-                  description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
-                params:
-                  default: {}
-                  description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
-                  type: object
-                  additionalProperties: {}
-              required:
-                - name
-                - weight
-              additionalProperties: false
-              description: One variant in the experiment. Weights across all groups must sum to 10000.
-          significanceThreshold:
-            type: number
-          minRuntimeDays:
-            type: integer
-            minimum: -9007199254740991
-            maximum: 9007199254740991
-          minSampleSize:
-            type: integer
-            minimum: -9007199254740991
-            maximum: 9007199254740991
-          sequentialTesting:
-            type: boolean
-          startedAt:
-            anyOf:
-              - type: string
-              - type: "null"
-            description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
-          stoppedAt:
-            anyOf:
-              - type: string
-              - type: "null"
-          updatedAt:
-            type: string
-        required:
-          - id
-          - name
-          - description
-          - hypothesis
-          - tag
-          - ownerEmail
-          - audience
-          - bucketBy
-          - folder
-          - status
-          - universe
-          - targetingGate
-          - allocationPct
-          - salt
-          - params
-          - groups
-          - significanceThreshold
-          - minRuntimeDays
-          - minSampleSize
-          - sequentialTesting
-          - startedAt
-          - updatedAt
-        additionalProperties: false
+        $ref: ./experiment-api-row.yaml#/ExperimentApiRow
     next_cursor:
       anyOf:
         - type: string
@@ -156,149 +14,7 @@ ListExperimentsResponse:
     - next_cursor
   additionalProperties: false
 GetExperimentResponse:
-  type: object
-  properties:
-    id:
-      type: string
-      description: Stable opaque experiment id (`exp_…`).
-    name:
-      type: string
-      maxLength: 128
-      pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
-      description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
-    description:
-      anyOf:
-        - type: string
-        - type: "null"
-    hypothesis:
-      anyOf:
-        - type: string
-        - type: "null"
-    tag:
-      anyOf:
-        - type: string
-        - type: "null"
-    ownerEmail:
-      anyOf:
-        - type: string
-        - type: "null"
-    audience:
-      anyOf:
-        - type: string
-        - type: "null"
-    bucketBy:
-      anyOf:
-        - type: string
-          minLength: 1
-          maxLength: 128
-          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
-          description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
-        - type: "null"
-    folder:
-      anyOf:
-        - type: string
-        - type: "null"
-    status:
-      type: string
-      enum:
-        - draft
-        - running
-        - stopped
-        - archived
-    universe:
-      type: string
-      description: Universe name this experiment draws from.
-    targetingGate:
-      anyOf:
-        - type: string
-        - type: "null"
-    allocationPct:
-      type: integer
-      minimum: -9007199254740991
-      maximum: 9007199254740991
-      description: Allocation in basis points (0–10000).
-    salt:
-      type: string
-    params:
-      type: object
-      additionalProperties:
-        type: string
-        enum:
-          - string
-          - bool
-          - number
-    groups:
-      type: array
-      items:
-        type: object
-        properties:
-          name:
-            type: string
-            minLength: 1
-            maxLength: 64
-            description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
-          weight:
-            type: integer
-            minimum: 0
-            maximum: 10000
-            description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
-          params:
-            default: {}
-            description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
-            type: object
-            additionalProperties: {}
-        required:
-          - name
-          - weight
-        additionalProperties: false
-        description: One variant in the experiment. Weights across all groups must sum to 10000.
-    significanceThreshold:
-      type: number
-    minRuntimeDays:
-      type: integer
-      minimum: -9007199254740991
-      maximum: 9007199254740991
-    minSampleSize:
-      type: integer
-      minimum: -9007199254740991
-      maximum: 9007199254740991
-    sequentialTesting:
-      type: boolean
-    startedAt:
-      anyOf:
-        - type: string
-        - type: "null"
-      description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
-    stoppedAt:
-      anyOf:
-        - type: string
-        - type: "null"
-    updatedAt:
-      type: string
-  required:
-    - id
-    - name
-    - description
-    - hypothesis
-    - tag
-    - ownerEmail
-    - audience
-    - bucketBy
-    - folder
-    - status
-    - universe
-    - targetingGate
-    - allocationPct
-    - salt
-    - params
-    - groups
-    - significanceThreshold
-    - minRuntimeDays
-    - minSampleSize
-    - sequentialTesting
-    - startedAt
-    - updatedAt
-  additionalProperties: false
+  $ref: ./experiment-api-row.yaml#/ExperimentApiRow
 CreateExperimentRequest:
   type: object
   properties:
@@ -359,13 +75,19 @@ CreateExperimentRequest:
       description: Name of an existing universe in the project. Returns `422` if the universe doesn't exist.
     targeting_gate:
       default: null
-      description: Optional gate name. Only callers that pass the gate are enrolled in the experiment.
+      description: Optional gate name (a `targeting`-type flag). Only callers that pass the gate are enrolled in the experiment.
+      anyOf:
+        - type: string
+        - type: "null"
+    holdout_gate:
+      default: null
+      description: Optional per-experiment holdout gate — the name of a `holdout`-type flag (public % + whitelist). A caller the flag passes is *held out* (never assigned, sees the universe defaults). Distinct from the universe-level holdout.
       anyOf:
         - type: string
         - type: "null"
     allocation_pct:
       default: 0
-      description: Share of the (gated) audience allocated to the experiment, in basis points (0–10000 = 0%–100%). `0` = unallocated. Use `allocation_percent` (0–100) below to think in percent. Immutable while the experiment is running.
+      description: Share of the (gated) audience allocated to the experiment, in basis points (0–10000 = 0%–100%). `0` = unallocated. Under pooled assignment this is the size of the universe-pool slice claimed. Use `allocation_percent` (0–100) below to think in percent. Immutable while the experiment is running.
       type: integer
       minimum: 0
       maximum: 10000
@@ -374,6 +96,11 @@ CreateExperimentRequest:
       type: number
       minimum: 0
       maximum: 100
+    reserved_headroom:
+      description: Basis points of this experiment's split kept empty (0–10000) so a new variant can be appended into it while running without reshuffling. Group weights must sum to `10000 − reserved_headroom`. Defaults to the universe's `recommended_headroom` when omitted.
+      type: integer
+      minimum: 0
+      maximum: 10000
     salt:
       description: Hash salt for bucketing. Auto-generated if omitted. Immutable while running.
       type: string
@@ -388,7 +115,7 @@ CreateExperimentRequest:
           - string
           - bool
           - number
-      description: "Map of param-name → scalar type. Defines the shape of `groups[].params`. Example: `{ headline: 'string', show_cta: 'bool' }`."
+      description: "**Deprecated** — the universe now owns the config schema (`param_schema`). Retained for back-compat; new experiments should leave this empty and declare params on the universe. Map of param-name → scalar type."
     groups:
       minItems: 2
       type: array
@@ -404,18 +131,18 @@ CreateExperimentRequest:
             type: integer
             minimum: 0
             maximum: 10000
-            description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
+            description: Allocation weight in basis points (0–10000). Weights across all groups must sum to `10000 − reserved_headroom` (100% minus any reserved tail).
           params:
             default: {}
-            description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
+            description: Per-variant **override map** — a subset of the universe's `param_schema` keys. A key the variant doesn't set inherits the universe default. Unknown keys (not in the universe schema) are rejected.
             type: object
             additionalProperties: {}
         required:
           - name
           - weight
         additionalProperties: false
-        description: One variant in the experiment. Weights across all groups must sum to 10000.
-      description: Two or more variants. Weights must sum to exactly 10000 (100%). Immutable while running.
+        description: One variant. Its `params` may only override keys declared on the universe schema.
+      description: Two or more variants. Weights must sum to `10000 − reserved_headroom`. Existing weights are immutable while running, but a new variant may be appended into the reserved tail.
     significance_threshold:
       default: 0.05
       description: p-value cutoff used by the analysis pass. Defaults to `0.05`. Values other than 0.05 require Pro plan or higher.
@@ -516,11 +243,21 @@ UpdateExperimentRequest:
       anyOf:
         - type: string
         - type: "null"
+    holdout_gate:
+      description: Per-experiment holdout gate — the name of a `holdout`-type flag, or `null` to clear. A caller the flag passes is held out.
+      anyOf:
+        - type: string
+        - type: "null"
     allocation_pct:
       description: Basis-points allocation (0–10000). Use `allocation_percent` (0–100) for percent. Immutable while the experiment is running.
       type: integer
       minimum: 0
       maximum: 10000
+    reserved_headroom:
+      description: Basis points of the split kept empty for appended variants. Group weights must sum to `10000 − reserved_headroom`. May be shrunk (never grown into existing weights) while running when appending a variant.
+      type: integer
+      minimum: 0
+      maximum: 10000
     allocation_percent:
       description: Allocation as a **percentage** (0–100). Friendlier alias for `allocation_pct`; converted to basis points server-side. Wins over `allocation_pct` if both are supplied. Immutable while running.
       type: number
@@ -542,9 +279,9 @@ UpdateExperimentRequest:
           - string
           - bool
           - number
-      description: "Map of param-name → scalar type. Defines the shape of `groups[].params`. Example: `{ headline: 'string', show_cta: 'bool' }`."
+      description: "**Deprecated** — the universe owns the config schema (`param_schema`). Retained for back-compat. Map of param-name → scalar type."
     groups:
-      description: Replacement groups. Weights must sum to 10000. Immutable while running.
+      description: Replacement groups. Weights must sum to `10000 − reserved_headroom`. Existing weights/values are immutable while running; a new variant may be appended into the reserved tail.
       minItems: 2
       type: array
       items:
@@ -559,17 +296,17 @@ UpdateExperimentRequest:
             type: integer
             minimum: 0
             maximum: 10000
-            description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
+            description: Allocation weight in basis points (0–10000). Weights across all groups must sum to `10000 − reserved_headroom`.
           params:
             default: {}
-            description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
+            description: Per-variant **override map** — a subset of the universe's `param_schema` keys. Unknown keys are rejected; unset keys inherit the universe default.
             type: object
             additionalProperties: {}
         required:
           - name
           - weight
         additionalProperties: false
-        description: One variant in the experiment. Weights across all groups must sum to 10000.
+        description: One variant. Its `params` may only override keys declared on the universe schema.
     significance_threshold:
       type: number
       minimum: 0.0001
@@ -594,7 +331,7 @@ UpdateExperimentRequest:
       items:
         $ref: ./common.yaml#/ExperimentInlineMetric
   additionalProperties: false
-  description: Body for `PATCH /api/admin/experiments/{id}`. Partial — only supplied fields change. `allocation_pct`, `groups`, `salt`, `universe`, `params` are immutable while the experiment is running (stop first).
+  description: Body for `PATCH /api/admin/experiments/{id}`. Partial — only supplied fields change. `allocation_pct`, `salt`, `universe` and existing group weights/values are immutable while running (stop first); a new variant may still be appended into the reserved tail.
 UpdateExperimentResponse:
   type: object
   properties:
@@ -662,6 +399,12 @@ SetExperimentMetricsRequest:
               - guardrail
               - secondary
             description: Metric role. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
+          min_effect_of_interest:
+            description: Per-experiment override of the metric's `default_min_effect_of_interest` (relative, 0–1) — the smallest change worth acting on for THIS experiment's decision, which depends on the intervention's cost/risk. `null`/omitted falls back to the metric default. For a `guardrail` this is the non-inferiority margin (how large a regression is tolerated); for a `goal` it is the superiority threshold.
+            default: null
+            anyOf:
+              - type: number
+              - type: "null"
         required:
           - metric_id
           - role
@@ -689,9 +432,15 @@ SetExperimentMetricsResponse:
               - goal
               - guardrail
               - secondary
+          min_effect_of_interest:
+            description: The resolved per-experiment override, or `null` when this attachment inherits the metric's `default_min_effect_of_interest`.
+            anyOf:
+              - type: number
+              - type: "null"
         required:
           - metric_id
           - role
+          - min_effect_of_interest
         additionalProperties: false
   required:
     - id
@@ -725,46 +474,8 @@ GetExperimentResultsResponse:
     results:
       type: array
       items:
-        type: object
-        properties:
-          metric:
-            type: string
-          group_name:
-            type: string
-          ds:
-            type: string
-            description: Date slice (`YYYY-MM-DD`).
-          n:
-            anyOf:
-              - type: number
-              - type: "null"
-          mean:
-            anyOf:
-              - type: number
-              - type: "null"
-          delta_pct:
-            anyOf:
-              - type: number
-              - type: "null"
-          p_value:
-            anyOf:
-              - type: number
-              - type: "null"
-          srm_detected:
-            anyOf:
-              - type: number
-              - type: "null"
-            description: "`1` if sample-ratio mismatch detected, else `0`."
-        required:
-          - metric
-          - group_name
-          - ds
-          - n
-          - mean
-          - delta_pct
-          - p_value
-          - srm_detected
-        additionalProperties: false
+        $ref: "#/ExperimentResultRow"
+      description: One analysis row per metric/group/day — the persisted `experiment_results` rows for this experiment.
     verdict:
       type: string
       enum:
@@ -807,50 +518,144 @@ GetExperimentTimeseriesResponse:
     series:
       type: array
       items:
-        type: object
-        properties:
-          metric:
-            type: string
-          group_name:
-            type: string
-          ds:
-            type: string
-            description: Date slice (`YYYY-MM-DD`).
-          n:
-            anyOf:
-              - type: number
-              - type: "null"
-          mean:
-            anyOf:
-              - type: number
-              - type: "null"
-          delta_pct:
-            anyOf:
-              - type: number
-              - type: "null"
-          p_value:
-            anyOf:
-              - type: number
-              - type: "null"
-          srm_detected:
-            anyOf:
-              - type: number
-              - type: "null"
-            description: "`1` if sample-ratio mismatch detected, else `0`."
-        required:
-          - metric
-          - group_name
-          - ds
-          - n
-          - mean
-          - delta_pct
-          - p_value
-          - srm_detected
-        additionalProperties: false
+        $ref: "#/ExperimentResultRow"
+      description: Every daily analysis slice (same row shape as `/results`), oldest to newest.
   required:
     - experiment
     - series
   additionalProperties: false
+ExperimentResultRow:
+  type: object
+  description: One persisted analysis row (`experiment_results`) for a single metric/group/day slice. Camel-case wire names; nullable statistics are `null` on control rows, empty arms, or when the analysis pass hasn't produced them.
+  properties:
+    metric:
+      type: string
+      description: Metric name this row was computed for.
+    groupName:
+      type: string
+      description: Variant (group) label the row belongs to, e.g. `control` or `treatment`.
+    ds:
+      type: string
+      description: Date slice (`YYYY-MM-DD`).
+    n:
+      description: Sample size (exposed units) in this group for the slice, or `null` when unknown.
+      anyOf:
+        - type: integer
+        - type: "null"
+    mean:
+      description: Per-unit metric mean in this group, or `null` on empty arms.
+      anyOf:
+        - type: number
+        - type: "null"
+    variance:
+      description: Per-unit metric variance in this group, or `null` on empty arms.
+      anyOf:
+        - type: number
+        - type: "null"
+    delta:
+      description: Absolute difference vs. control (metric units). `null` on the control row.
+      anyOf:
+        - type: number
+        - type: "null"
+    deltaPct:
+      description: Relative difference vs. control, in percent. `null` on the control row.
+      anyOf:
+        - type: number
+        - type: "null"
+    ci95Low:
+      description: Lower bound of the 95% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
+      anyOf:
+        - type: number
+        - type: "null"
+    ci95High:
+      description: Upper bound of the 95% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
+      anyOf:
+        - type: number
+        - type: "null"
+    ci99Low:
+      description: Lower bound of the 99% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
+      anyOf:
+        - type: number
+        - type: "null"
+    ci99High:
+      description: Upper bound of the 99% confidence interval on `delta`, or `null`. Kept for back-compat — prefer `ciLow`/`ciHigh`.
+      anyOf:
+        - type: number
+        - type: "null"
+    ciLow:
+      description: Lower bound of the confidence interval at the project's configured `ci_confidence` (not always 95%), or `null`. When both `ciLow`/`ciHigh` are `null`, fall back to `ci95Low`/`ci95High` (pre-migration rows).
+      anyOf:
+        - type: number
+        - type: "null"
+    ciHigh:
+      description: Upper bound of the confidence interval at the project's configured `ci_confidence` (not always 95%), or `null`. When both `ciLow`/`ciHigh` are `null`, fall back to `ci95Low`/`ci95High` (pre-migration rows).
+      anyOf:
+        - type: number
+        - type: "null"
+    pValue:
+      description: Two-sided p-value vs. control, or `null` on the control row / empty arms.
+      anyOf:
+        - type: number
+        - type: "null"
+    expectedN:
+      description: Sample size per arm the power calculation expects for a conclusive read, or `null` when not computed.
+      anyOf:
+        - type: integer
+        - type: "null"
+    realizedMde:
+      description: "Realized minimum detectable effect (absolute, in metric units) — the smallest true effect this run could detect at the experiment's significance level and target power GIVEN the observed variance and per-arm sample sizes. A derived OUTPUT, not an input knob; compare it against the metric's minimum effect of interest to judge whether the run is adequately powered. `null` on the control row and on empty arms."
+      anyOf:
+        - type: number
+        - type: "null"
+    srmPValue:
+      description: p-value of the sample-ratio-mismatch chi-squared test, or `null` when not computed.
+      anyOf:
+        - type: number
+        - type: "null"
+    srmDetected:
+      type: integer
+      description: "`1` if sample-ratio mismatch detected, else `0`."
+    msprtSignificant:
+      description: "Sequential (mSPRT) significance flag: `1` significant, `0` not, `null` when sequential testing is off or not computed."
+      anyOf:
+        - type: integer
+        - type: "null"
+    msprtLambda:
+      description: mSPRT mixture likelihood-ratio statistic, or `null` when sequential testing is off or not computed.
+      anyOf:
+        - type: number
+        - type: "null"
+    isFinal:
+      type: integer
+      description: "`1` when this row belongs to the final analysis pass after the experiment stopped, else `0`."
+    peekWarning:
+      type: integer
+      description: "`1` when the row was read before `min_runtime_days`/`min_sample_size` were met (peeking inflates false positives), else `0`."
+  required:
+    - metric
+    - groupName
+    - ds
+    - n
+    - mean
+    - variance
+    - delta
+    - deltaPct
+    - ci95Low
+    - ci95High
+    - ci99Low
+    - ci99High
+    - ciLow
+    - ciHigh
+    - pValue
+    - expectedN
+    - realizedMde
+    - srmPValue
+    - srmDetected
+    - msprtSignificant
+    - msprtLambda
+    - isFinal
+    - peekWarning
+  additionalProperties: false
 ReanalyzeExperimentResponse:
   type: object
   properties:
@@ -858,8 +663,218 @@ ReanalyzeExperimentResponse:
       type: string
     queued:
       type: boolean
-      const: true
+      description: "`true` when the analysis job was enqueued; `false` when the worker enqueue failed or the analysis queue is not configured (retry later)."
   required:
     - id
     - queued
   additionalProperties: false
+CreateExperimentReadoutRequest:
+  type: object
+  description: Body for `POST /api/admin/experiments/{id}/readouts`. Mints an immutable, dated readout snapshot of the current results view — "this is what we saw when we decided".
+  properties:
+    kind:
+      type: string
+      enum:
+        - manual
+        - ship
+        - stop
+      description: Why the snapshot is being minted — `manual` ("Share readout"), or automatically on `ship` / `stop`.
+    acknowledgedCaveatIds:
+      type: array
+      items:
+        type: string
+        description: Caveat id, as surfaced in the results view's caveat list.
+      description: Ids of the open caveats the caller ticked (decision-gating acknowledgment). Unlisted caveats are stored as unacknowledged.
+    requireAllAcknowledged:
+      type: boolean
+      description: When `true`, refuse (`422`) to mint while any open caveat is not listed in `acknowledgedCaveatIds` — server-side ship gating.
+  required:
+    - kind
+  additionalProperties: false
+CreateExperimentReadoutResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Id of the newly minted readout snapshot.
+  required:
+    - id
+  additionalProperties: false
+ExperimentReadoutMetric:
+  type: object
+  description: Frozen per-metric numbers as rendered at mint time. Display-shaped, not row-shaped — the snapshot keeps rendering exactly what was decided on even if derivations change later.
+  properties:
+    name:
+      type: string
+      description: Metric name.
+    role:
+      type: string
+      enum:
+        - goal
+        - guardrail
+        - secondary
+      description: Metric role at mint time. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
+    delta:
+      description: Absolute difference vs. control (metric units), or `null`.
+      anyOf:
+        - type: number
+        - type: "null"
+    deltaPct:
+      description: Relative difference vs. control in percent, or `null`.
+      anyOf:
+        - type: number
+        - type: "null"
+    ci:
+      description: "Two-item `[low, high]` confidence interval on the delta at the project's configured confidence, or `null`."
+      anyOf:
+        - type: array
+          items:
+            type: number
+          minItems: 2
+          maxItems: 2
+        - type: "null"
+    p:
+      description: p-value vs. control, or `null`.
+      anyOf:
+        - type: number
+        - type: "null"
+    sig:
+      type: boolean
+      description: Whether the metric was statistically significant at mint time.
+    pass:
+      type: boolean
+      description: Guardrail pass/fail at mint time. Omitted for metrics where pass/fail doesn't apply.
+  required:
+    - name
+    - role
+    - delta
+    - deltaPct
+    - ci
+    - p
+    - sig
+  additionalProperties: false
+ExperimentReadoutCaveat:
+  type: object
+  description: One caveat from the results view, frozen with its acknowledgment state at mint time.
+  properties:
+    id:
+      type: string
+      description: Stable caveat id.
+    severity:
+      type: string
+      enum:
+        - info
+        - warn
+        - danger
+      description: Caveat severity as rendered in the results view.
+    text:
+      type: string
+      description: Human-readable caveat text.
+    acknowledged:
+      type: boolean
+      description: Whether the caller ticked this caveat when minting (decision-gating acknowledgment).
+  required:
+    - id
+    - severity
+    - text
+    - acknowledged
+  additionalProperties: false
+ExperimentReadoutApiRow:
+  type: object
+  description: An immutable, dated readout snapshot — the frozen results view captured when a decision was made. Never updated after insert.
+  properties:
+    id:
+      type: string
+      description: Stable readout id.
+    experimentId:
+      type: string
+      description: Id of the experiment the snapshot belongs to.
+    experimentName:
+      type: string
+      description: Experiment name at mint time (denormalised — survives renames).
+    kind:
+      type: string
+      enum:
+        - manual
+        - ship
+        - stop
+      description: Why the snapshot was minted — `manual` ("Share readout"), or automatically on `ship` / `stop`.
+    createdBy:
+      type: string
+      description: Email of the actor who minted the snapshot.
+    createdAt:
+      type: string
+      description: ISO-8601 mint timestamp.
+    verdict:
+      type: string
+      description: Server-computed verdict at mint time (e.g. `ship`, `hold`, `wait`, `invalid`).
+    title:
+      type: string
+      description: Headline of the results view at mint time.
+    why:
+      type: string
+      description: One-line explanation backing the verdict at mint time.
+    configHash:
+      type: string
+      description: sha-256 hex over the assignment-relevant config (salt, groups, allocation, universe, gate) — the snapshot is only comparable to the live view while this hash still matches.
+    metricsJson:
+      description: Frozen per-metric numbers as rendered at mint time, or `null` for legacy rows without a metrics slice.
+      anyOf:
+        - type: array
+          items:
+            $ref: "#/ExperimentReadoutMetric"
+        - type: "null"
+    caveatsJson:
+      description: The caveat list with its acknowledgment state at mint time, or `null` for legacy rows without one.
+      anyOf:
+        - type: array
+          items:
+            $ref: "#/ExperimentReadoutCaveat"
+        - type: "null"
+    usersJson:
+      description: Enrollment at mint time — per-group sample sizes plus the number of days the experiment had been running — or `null` when not captured.
+      anyOf:
+        - type: object
+          properties:
+            groups:
+              type: array
+              items:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Group label.
+                  n:
+                    type: number
+                    description: Enrolled units in the group at mint time.
+                required:
+                  - name
+                  - n
+                additionalProperties: false
+                description: One group's enrollment at mint time.
+              description: Per-group enrollment counts.
+            days:
+              type: number
+              description: Days the experiment had been running at mint time.
+          required:
+            - groups
+            - days
+          additionalProperties: false
+        - type: "null"
+  required:
+    - id
+    - experimentId
+    - experimentName
+    - kind
+    - createdBy
+    - createdAt
+    - verdict
+    - title
+    - why
+    - configHash
+    - metricsJson
+    - caveatsJson
+    - usersJson
+  additionalProperties: false
+GetExperimentReadoutResponse:
+  $ref: "#/ExperimentReadoutApiRow"