@shipeasy/openapi 1.6.0 → 2.1.0

package/spec/components/schemas/gates.yaml

@@ -0,0 +1,890 @@
+ListGatesResponse:
+  type: object
+  properties:
+    data:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+            description: Stable opaque gate id (`gat_…`).
+          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 gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
+          enabled:
+            anyOf:
+              - type: boolean
+              - type: integer
+                minimum: 0
+                maximum: 1
+            description: Master switch. Returned as `1`/`0` from D1; treat truthy as enabled.
+          rolloutPct:
+            type: integer
+            minimum: 0
+            maximum: 10000
+            description: Current rollout in basis points (0–10000).
+          rules:
+            type: array
+            items:
+              type: object
+              properties:
+                attr:
+                  type: string
+                  minLength: 1
+                  description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
+                op:
+                  type: string
+                  enum:
+                    - eq
+                    - neq
+                    - in
+                    - not_in
+                    - gt
+                    - gte
+                    - lt
+                    - lte
+                    - contains
+                    - regex
+                    - semver_gt
+                    - semver_gte
+                    - semver_lt
+                    - semver_lte
+                    - gate_pass
+                    - exp_in
+                  description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate's name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment's name, `value` is a group name, `\"$holdout\"`, or `\"$any\"` — true when the caller is in that variant / the universe holdout / any variant)."
+                value:
+                  description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
+              required:
+                - attr
+                - op
+                - value
+              additionalProperties: false
+              description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
+          salt:
+            description: Hash salt used for percentage bucketing.
+            type: string
+          title:
+            anyOf:
+              - type: string
+              - type: "null"
+          description:
+            anyOf:
+              - type: string
+              - type: "null"
+          folder:
+            anyOf:
+              - type: string
+              - type: "null"
+          groupName:
+            description: "Group label (note: `groupName` in response, `group` in request)."
+            anyOf:
+              - type: string
+              - type: "null"
+          ownerEmail:
+            description: "Owner email (note: `ownerEmail` in response, `owner_email` in request)."
+            anyOf:
+              - type: string
+              - type: "null"
+          stack:
+            anyOf:
+              - type: array
+                items:
+                  oneOf:
+                    - type: object
+                      properties:
+                        id:
+                          type: string
+                          minLength: 1
+                          description: Client-supplied stable id for the stack entry (used for React keys, audit diffs, and as the default per-condition rollout salt).
+                        type:
+                          type: string
+                          const: condition
+                          description: Discriminator. `condition` = rule-based predicate sub-gate.
+                        name:
+                          description: Human label shown in the dashboard.
+                          type: string
+                        fromTemplate:
+                          description: Id of the project template this entry was seeded from, or `null` if hand-authored.
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                        pass:
+                          description: Combinator across `rules`. `all` = AND (default), `any` = OR.
+                          type: string
+                          enum:
+                            - all
+                            - any
+                        rules:
+                          default: []
+                          description: Predicates evaluated under `pass`. Empty array = match nothing.
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              attr:
+                                type: string
+                                minLength: 1
+                                description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
+                              op:
+                                type: string
+                                enum:
+                                  - eq
+                                  - neq
+                                  - in
+                                  - not_in
+                                  - gt
+                                  - gte
+                                  - lt
+                                  - lte
+                                  - contains
+                                  - regex
+                                  - semver_gt
+                                  - semver_gte
+                                  - semver_lt
+                                  - semver_lte
+                                  - gate_pass
+                                  - exp_in
+                                description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate's name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment's name, `value` is a group name, `\"$holdout\"`, or `\"$any\"` — true when the caller is in that variant / the universe holdout / any variant)."
+                              value:
+                                description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
+                            required:
+                              - attr
+                              - op
+                              - value
+                            additionalProperties: false
+                            description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
+                        rolloutPct:
+                          description: Per-condition rollout in basis points. After the rules match, the caller is bucketed at this %; in-bucket → gate `true`, otherwise fall through to the next entry. Absent ⇒ 10000 (100%, every matching caller passes).
+                          type: integer
+                          minimum: 0
+                          maximum: 10000
+                        bucketBy:
+                          description: Attribute used to hash the caller into the per-condition bucket. Default `userID`.
+                          type: string
+                        salt:
+                          description: Per-condition hash salt. Defaults to the entry `id`, then the gate salt.
+                          type: string
+                        ramp:
+                          type: object
+                          properties:
+                            from:
+                              type: integer
+                              minimum: 0
+                              maximum: 10000
+                              description: Start of the ramp in basis points (0–10000).
+                            to:
+                              type: integer
+                              minimum: 0
+                              maximum: 10000
+                              description: End of the ramp in basis points (0–10000).
+                            startAt:
+                              type: integer
+                              minimum: 0
+                              maximum: 9007199254740991
+                              description: Ramp start, epoch milliseconds (UTC).
+                            durationMs:
+                              type: integer
+                              exclusiveMinimum: 0
+                              maximum: 9007199254740991
+                              description: Ramp length in milliseconds.
+                          required:
+                            - from
+                            - to
+                            - startAt
+                            - durationMs
+                          additionalProperties: false
+                          description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
+                        locked:
+                          description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
+                          type: boolean
+                      required:
+                        - id
+                        - type
+                      additionalProperties: false
+                      description: Rule-based sub-gate. When the rules match and the caller falls in the per-condition rollout bucket, evaluation short-circuits and the gate returns `true`; otherwise it falls through to the next entry.
+                    - type: object
+                      properties:
+                        id:
+                          type: string
+                          minLength: 1
+                          description: Client-supplied stable id for the stack entry.
+                        type:
+                          type: string
+                          const: rollout
+                          description: Discriminator. `rollout` = percentage-bucket sub-gate.
+                        name:
+                          description: Human label shown in the dashboard.
+                          type: string
+                        fromTemplate:
+                          description: Source template id, or `null`.
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                        rolloutPct:
+                          type: integer
+                          minimum: 0
+                          maximum: 10000
+                          description: Bucket size in basis points (0–10000 = 0%–100%). `5000` = 50%, `100` = 1%, allows sub-1% precision.
+                        bucketBy:
+                          description: Attribute used to hash the caller into a bucket. Defaults to `user.userID`. Use e.g. `accountID` to bucket whole accounts together.
+                          type: string
+                        salt:
+                          description: Per-entry hash salt. Defaults to the gate's salt. Set explicitly to keep two rollouts independent or correlated across gates.
+                          type: string
+                        ramp:
+                          type: object
+                          properties:
+                            from:
+                              type: integer
+                              minimum: 0
+                              maximum: 10000
+                              description: Start of the ramp in basis points (0–10000).
+                            to:
+                              type: integer
+                              minimum: 0
+                              maximum: 10000
+                              description: End of the ramp in basis points (0–10000).
+                            startAt:
+                              type: integer
+                              minimum: 0
+                              maximum: 9007199254740991
+                              description: Ramp start, epoch milliseconds (UTC).
+                            durationMs:
+                              type: integer
+                              exclusiveMinimum: 0
+                              maximum: 9007199254740991
+                              description: Ramp length in milliseconds.
+                          required:
+                            - from
+                            - to
+                            - startAt
+                            - durationMs
+                          additionalProperties: false
+                          description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
+                        locked:
+                          description: If `true`, dashboard hides edit controls.
+                          type: boolean
+                      required:
+                        - id
+                        - type
+                        - rolloutPct
+                      additionalProperties: false
+                      description: Percentage-rollout sub-gate. Hashes `bucketBy` (default `userID`) with `salt` and returns `true` for `rolloutPct/10000` fraction of callers (or the ramp's effective % when `ramp` is set).
+                  description: One entry in the ordered gatekeeper stack. Evaluated top-to-bottom; first matching entry decides. Mix `condition` and `rollout` entries to express `internal-only` + `1% beta` + `50% public` in a single gate.
+              - type: "null"
+          updatedAt:
+            type: string
+            description: ISO-8601 timestamp of last mutation.
+        required:
+          - id
+          - name
+          - enabled
+          - rolloutPct
+          - updatedAt
+        additionalProperties: false
+    next_cursor:
+      anyOf:
+        - type: string
+        - type: "null"
+  required:
+    - data
+    - next_cursor
+  additionalProperties: false
+CreateGateRequest:
+  type: object
+  properties:
+    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 gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
+    enabled:
+      default: true
+      description: Master switch. Defaults to `true`. Set `false` to create the gate disabled (evaluates to `false` regardless of rules/rollout); flip on via `POST /{id}/enable` or PATCH.
+      type: boolean
+    rollout_pct:
+      default: 0
+      description: Initial rollout in **basis points** (0–10000 = 0%–100%) — `100` here means **1%**, not 100%. Use `rollout_percent` (0–100) below if you'd rather think in percent. Use `0` to create the gate dark and ramp via PATCH after deploy validation.
+      type: integer
+      minimum: 0
+      maximum: 10000
+    rollout_percent:
+      description: Initial rollout as a **percentage** (0–100, fractional ok). Friendlier alias for `rollout_pct`; converted internally to basis points (e.g. `100` here = 10000 bp = 100%). If both `rollout_pct` and `rollout_percent` are set, `rollout_percent` wins.
+      type: number
+      minimum: 0
+      maximum: 100
+    rules:
+      default: []
+      description: Targeting predicates. AND-combined. If non-empty, the gate returns `true` only for callers that satisfy every rule **and** fall under `rollout_pct`.
+      type: array
+      items:
+        type: object
+        properties:
+          attr:
+            type: string
+            minLength: 1
+            description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
+          op:
+            type: string
+            enum:
+              - eq
+              - neq
+              - in
+              - not_in
+              - gt
+              - gte
+              - lt
+              - lte
+              - contains
+              - regex
+              - semver_gt
+              - semver_gte
+              - semver_lt
+              - semver_lte
+              - gate_pass
+              - exp_in
+            description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate's name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment's name, `value` is a group name, `\"$holdout\"`, or `\"$any\"` — true when the caller is in that variant / the universe holdout / any variant)."
+          value:
+            description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
+        required:
+          - attr
+          - op
+          - value
+        additionalProperties: false
+        description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
+    salt:
+      description: Hash salt for percentage bucketing. Auto-generated if omitted. Provide explicitly to keep a gate's buckets stable across delete/recreate. **Immutable after create** — there is no PATCH for `salt` because changing it would re-bucket every caller.
+      type: string
+      minLength: 1
+      maxLength: 64
+    stack:
+      description: Optional gatekeeper stack. When provided, takes precedence over `rules` + `rollout_pct` at evaluation time. Omit (or pass `null`) for a flat gate.
+      anyOf:
+        - type: array
+          items:
+            oneOf:
+              - type: object
+                properties:
+                  id:
+                    type: string
+                    minLength: 1
+                    description: Client-supplied stable id for the stack entry (used for React keys, audit diffs, and as the default per-condition rollout salt).
+                  type:
+                    type: string
+                    const: condition
+                    description: Discriminator. `condition` = rule-based predicate sub-gate.
+                  name:
+                    description: Human label shown in the dashboard.
+                    type: string
+                  fromTemplate:
+                    description: Id of the project template this entry was seeded from, or `null` if hand-authored.
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                  pass:
+                    description: Combinator across `rules`. `all` = AND (default), `any` = OR.
+                    type: string
+                    enum:
+                      - all
+                      - any
+                  rules:
+                    default: []
+                    description: Predicates evaluated under `pass`. Empty array = match nothing.
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        attr:
+                          type: string
+                          minLength: 1
+                          description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
+                        op:
+                          type: string
+                          enum:
+                            - eq
+                            - neq
+                            - in
+                            - not_in
+                            - gt
+                            - gte
+                            - lt
+                            - lte
+                            - contains
+                            - regex
+                            - semver_gt
+                            - semver_gte
+                            - semver_lt
+                            - semver_lte
+                            - gate_pass
+                            - exp_in
+                          description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate's name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment's name, `value` is a group name, `\"$holdout\"`, or `\"$any\"` — true when the caller is in that variant / the universe holdout / any variant)."
+                        value:
+                          description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
+                      required:
+                        - attr
+                        - op
+                        - value
+                      additionalProperties: false
+                      description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
+                  rolloutPct:
+                    description: Per-condition rollout in basis points. After the rules match, the caller is bucketed at this %; in-bucket → gate `true`, otherwise fall through to the next entry. Absent ⇒ 10000 (100%, every matching caller passes).
+                    type: integer
+                    minimum: 0
+                    maximum: 10000
+                  bucketBy:
+                    description: Attribute used to hash the caller into the per-condition bucket. Default `userID`.
+                    type: string
+                  salt:
+                    description: Per-condition hash salt. Defaults to the entry `id`, then the gate salt.
+                    type: string
+                  ramp:
+                    type: object
+                    properties:
+                      from:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: Start of the ramp in basis points (0–10000).
+                      to:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: End of the ramp in basis points (0–10000).
+                      startAt:
+                        type: integer
+                        minimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp start, epoch milliseconds (UTC).
+                      durationMs:
+                        type: integer
+                        exclusiveMinimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp length in milliseconds.
+                    required:
+                      - from
+                      - to
+                      - startAt
+                      - durationMs
+                    additionalProperties: false
+                    description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
+                  locked:
+                    description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
+                    type: boolean
+                required:
+                  - id
+                  - type
+                additionalProperties: false
+                description: Rule-based sub-gate. When the rules match and the caller falls in the per-condition rollout bucket, evaluation short-circuits and the gate returns `true`; otherwise it falls through to the next entry.
+              - type: object
+                properties:
+                  id:
+                    type: string
+                    minLength: 1
+                    description: Client-supplied stable id for the stack entry.
+                  type:
+                    type: string
+                    const: rollout
+                    description: Discriminator. `rollout` = percentage-bucket sub-gate.
+                  name:
+                    description: Human label shown in the dashboard.
+                    type: string
+                  fromTemplate:
+                    description: Source template id, or `null`.
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                  rolloutPct:
+                    type: integer
+                    minimum: 0
+                    maximum: 10000
+                    description: Bucket size in basis points (0–10000 = 0%–100%). `5000` = 50%, `100` = 1%, allows sub-1% precision.
+                  bucketBy:
+                    description: Attribute used to hash the caller into a bucket. Defaults to `user.userID`. Use e.g. `accountID` to bucket whole accounts together.
+                    type: string
+                  salt:
+                    description: Per-entry hash salt. Defaults to the gate's salt. Set explicitly to keep two rollouts independent or correlated across gates.
+                    type: string
+                  ramp:
+                    type: object
+                    properties:
+                      from:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: Start of the ramp in basis points (0–10000).
+                      to:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: End of the ramp in basis points (0–10000).
+                      startAt:
+                        type: integer
+                        minimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp start, epoch milliseconds (UTC).
+                      durationMs:
+                        type: integer
+                        exclusiveMinimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp length in milliseconds.
+                    required:
+                      - from
+                      - to
+                      - startAt
+                      - durationMs
+                    additionalProperties: false
+                    description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
+                  locked:
+                    description: If `true`, dashboard hides edit controls.
+                    type: boolean
+                required:
+                  - id
+                  - type
+                  - rolloutPct
+                additionalProperties: false
+                description: Percentage-rollout sub-gate. Hashes `bucketBy` (default `userID`) with `salt` and returns `true` for `rolloutPct/10000` fraction of callers (or the ramp's effective % when `ramp` is set).
+            description: One entry in the ordered gatekeeper stack. Evaluated top-to-bottom; first matching entry decides. Mix `condition` and `rollout` entries to express `internal-only` + `1% beta` + `50% public` in a single gate.
+        - type: "null"
+    title:
+      description: Human-readable title shown in the dashboard. Free-form, no key format constraint.
+      type: string
+      maxLength: 140
+    description:
+      description: Long-form description / runbook. Markdown is rendered in the dashboard.
+      type: string
+      maxLength: 2000
+    folder:
+      $ref: ./common.yaml#/Folder
+    group:
+      description: Group label for dashboard organisation (e.g. team or product area).
+      type: string
+      maxLength: 64
+    owner_email:
+      description: Owner contact. Displayed verbatim; not used for auth.
+      type: string
+      maxLength: 190
+  required:
+    - name
+  additionalProperties: false
+  description: Body for `POST /api/admin/gates`. At minimum supply `name`; everything else has sensible defaults.
+CreateGateResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned gate id (`gat_…`).
+    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 gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
+  required:
+    - id
+    - name
+  additionalProperties: false
+UpdateGateRequest:
+  type: object
+  properties:
+    rollout_pct:
+      description: New rollout in **basis points** (0–10000 = 0%–100%) — `100` here means **1%**. Use `rollout_percent` (0–100) below for percent. Omit both to leave unchanged.
+      type: integer
+      minimum: 0
+      maximum: 10000
+    rollout_percent:
+      description: New rollout as a **percentage** (0–100). Friendlier alias for `rollout_pct`; converted internally. Wins over `rollout_pct` if both are supplied. Omit both to leave unchanged.
+      type: number
+      minimum: 0
+      maximum: 100
+    rules:
+      description: Replaces the rule list wholesale. To add a value to an `in` rule, send the full new `rules` array with the augmented `value` (e.g. previous `['US','CA']` → `['US','CA','GB']`).
+      type: array
+      items:
+        type: object
+        properties:
+          attr:
+            type: string
+            minLength: 1
+            description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
+          op:
+            type: string
+            enum:
+              - eq
+              - neq
+              - in
+              - not_in
+              - gt
+              - gte
+              - lt
+              - lte
+              - contains
+              - regex
+              - semver_gt
+              - semver_gte
+              - semver_lt
+              - semver_lte
+              - gate_pass
+              - exp_in
+            description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate's name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment's name, `value` is a group name, `\"$holdout\"`, or `\"$any\"` — true when the caller is in that variant / the universe holdout / any variant)."
+          value:
+            description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
+        required:
+          - attr
+          - op
+          - value
+        additionalProperties: false
+        description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
+    enabled:
+      description: Master switch. `false` makes the gate evaluate to `false` for every caller regardless of `rollout_pct`, `rules`, or `stack` — use as kill switch.
+      type: boolean
+    stack:
+      description: Replaces the gatekeeper stack wholesale. Send `null` to revert to flat `rules` + `rollout_pct` evaluation.
+      anyOf:
+        - type: array
+          items:
+            oneOf:
+              - type: object
+                properties:
+                  id:
+                    type: string
+                    minLength: 1
+                    description: Client-supplied stable id for the stack entry (used for React keys, audit diffs, and as the default per-condition rollout salt).
+                  type:
+                    type: string
+                    const: condition
+                    description: Discriminator. `condition` = rule-based predicate sub-gate.
+                  name:
+                    description: Human label shown in the dashboard.
+                    type: string
+                  fromTemplate:
+                    description: Id of the project template this entry was seeded from, or `null` if hand-authored.
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                  pass:
+                    description: Combinator across `rules`. `all` = AND (default), `any` = OR.
+                    type: string
+                    enum:
+                      - all
+                      - any
+                  rules:
+                    default: []
+                    description: Predicates evaluated under `pass`. Empty array = match nothing.
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        attr:
+                          type: string
+                          minLength: 1
+                          description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input.
+                        op:
+                          type: string
+                          enum:
+                            - eq
+                            - neq
+                            - in
+                            - not_in
+                            - gt
+                            - gte
+                            - lt
+                            - lte
+                            - contains
+                            - regex
+                            - semver_gt
+                            - semver_gte
+                            - semver_lt
+                            - semver_lte
+                            - gate_pass
+                            - exp_in
+                          description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte` (value is a dotted version like `4.2.0`). String: `contains` (substring), `regex` (JS-flavour pattern, value is the pattern string). Cross-resource references (evaluated only on the worker hot path, where both KV blobs load): `gate_pass` (`value` is another gate's name — true when that gate passes for the same caller); `exp_in` (`attr` is a running experiment's name, `value` is a group name, `\"$holdout\"`, or `\"$any\"` — true when the caller is in that variant / the universe holdout / any variant)."
+                        value:
+                          description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; group name / `"$holdout"` / `"$any"` for `exp_in`.'
+                      required:
+                        - attr
+                        - op
+                        - value
+                      additionalProperties: false
+                      description: Single targeting predicate. A gate's `rules` array is evaluated with AND semantics; use the gatekeeper `stack` for OR / fall-through logic.
+                  rolloutPct:
+                    description: Per-condition rollout in basis points. After the rules match, the caller is bucketed at this %; in-bucket → gate `true`, otherwise fall through to the next entry. Absent ⇒ 10000 (100%, every matching caller passes).
+                    type: integer
+                    minimum: 0
+                    maximum: 10000
+                  bucketBy:
+                    description: Attribute used to hash the caller into the per-condition bucket. Default `userID`.
+                    type: string
+                  salt:
+                    description: Per-condition hash salt. Defaults to the entry `id`, then the gate salt.
+                    type: string
+                  ramp:
+                    type: object
+                    properties:
+                      from:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: Start of the ramp in basis points (0–10000).
+                      to:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: End of the ramp in basis points (0–10000).
+                      startAt:
+                        type: integer
+                        minimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp start, epoch milliseconds (UTC).
+                      durationMs:
+                        type: integer
+                        exclusiveMinimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp length in milliseconds.
+                    required:
+                      - from
+                      - to
+                      - startAt
+                      - durationMs
+                    additionalProperties: false
+                    description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
+                  locked:
+                    description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
+                    type: boolean
+                required:
+                  - id
+                  - type
+                additionalProperties: false
+                description: Rule-based sub-gate. When the rules match and the caller falls in the per-condition rollout bucket, evaluation short-circuits and the gate returns `true`; otherwise it falls through to the next entry.
+              - type: object
+                properties:
+                  id:
+                    type: string
+                    minLength: 1
+                    description: Client-supplied stable id for the stack entry.
+                  type:
+                    type: string
+                    const: rollout
+                    description: Discriminator. `rollout` = percentage-bucket sub-gate.
+                  name:
+                    description: Human label shown in the dashboard.
+                    type: string
+                  fromTemplate:
+                    description: Source template id, or `null`.
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                  rolloutPct:
+                    type: integer
+                    minimum: 0
+                    maximum: 10000
+                    description: Bucket size in basis points (0–10000 = 0%–100%). `5000` = 50%, `100` = 1%, allows sub-1% precision.
+                  bucketBy:
+                    description: Attribute used to hash the caller into a bucket. Defaults to `user.userID`. Use e.g. `accountID` to bucket whole accounts together.
+                    type: string
+                  salt:
+                    description: Per-entry hash salt. Defaults to the gate's salt. Set explicitly to keep two rollouts independent or correlated across gates.
+                    type: string
+                  ramp:
+                    type: object
+                    properties:
+                      from:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: Start of the ramp in basis points (0–10000).
+                      to:
+                        type: integer
+                        minimum: 0
+                        maximum: 10000
+                        description: End of the ramp in basis points (0–10000).
+                      startAt:
+                        type: integer
+                        minimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp start, epoch milliseconds (UTC).
+                      durationMs:
+                        type: integer
+                        exclusiveMinimum: 0
+                        maximum: 9007199254740991
+                        description: Ramp length in milliseconds.
+                    required:
+                      - from
+                      - to
+                      - startAt
+                      - durationMs
+                    additionalProperties: false
+                    description: Linear rollout ramp. The effective rollout % interpolates `from`→`to` over `[startAt, startAt+durationMs]`, clamped outside that window, evaluated against the wall-clock at eval time. Overrides the entry's static `rolloutPct` while present.
+                  locked:
+                    description: If `true`, dashboard hides edit controls.
+                    type: boolean
+                required:
+                  - id
+                  - type
+                  - rolloutPct
+                additionalProperties: false
+                description: Percentage-rollout sub-gate. Hashes `bucketBy` (default `userID`) with `salt` and returns `true` for `rolloutPct/10000` fraction of callers (or the ramp's effective % when `ramp` is set).
+            description: One entry in the ordered gatekeeper stack. Evaluated top-to-bottom; first matching entry decides. Mix `condition` and `rollout` entries to express `internal-only` + `1% beta` + `50% public` in a single gate.
+        - type: "null"
+    title:
+      description: Human-readable title shown in the dashboard. Free-form, no key format constraint.
+      type: string
+      maxLength: 140
+    description:
+      description: Long-form description / runbook. Markdown is rendered in the dashboard.
+      type: string
+      maxLength: 2000
+    folder:
+      $ref: ./common.yaml#/Folder
+    group:
+      description: Group label for dashboard organisation (e.g. team or product area).
+      type: string
+      maxLength: 64
+    owner_email:
+      description: Owner contact. Displayed verbatim; not used for auth.
+      type: string
+      maxLength: 190
+  additionalProperties: false
+  description: Body for `PATCH /api/admin/gates/{id}`. Partial — only supplied fields change. Array fields (`rules`, `stack`) replace, not merge.
+UpdateGateResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Gate id that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Update returns only the id — re-fetch via `GET /api/admin/gates` for the full row.
+DeleteGateResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+  required:
+    - ok
+  additionalProperties: false
+EnableGateResponse:
+  type: object
+  properties:
+    id:
+      type: string
+    enabled:
+      type: boolean
+  required:
+    - id
+    - enabled
+  additionalProperties: false
+DisableGateResponse:
+  type: object
+  properties:
+    id:
+      type: string
+    enabled:
+      type: boolean
+  required:
+    - id
+    - enabled
+  additionalProperties: false