{
  "openapi": "3.1.0",
  "info": {
    "title": "GroundIT — Engage & Exit",
    "version": "0.1.0",
    "license": {
      "name": "Proprietary — GroundIT/Sysmedac internal"
    },
    "description": "The workforce as a sourcing/retention channel — job referrals through a milestone-gated bonus, a post-exit alumni & rehire pool, structured peer/manager recognition, the official broadcast announcement feed (with an Immutable read-receipt ledger), and maker-checker promotions & salary revisions typically seeded off an appraisal calibration — all `engage.*`. Voluntary separation through a guided 3-step resignation wizard with an ESOP-impact note, multi-department clearance & no-dues gating full-&-final settlement, and confidential exit feedback feeding attrition analytics — `exit.*`. See ../../api-docs/00-api-overview-and-conventions.md.\n"
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "security": [
    {
      "bearerJWT": []
    }
  ],
  "tags": [
    {
      "name": "engage",
      "description": "Job referrals & payout, alumni & rehire, rewards & recognition, announcement feed, promotions & salary revision."
    },
    {
      "name": "exit",
      "description": "Resignation wizard, clearance & no-dues, exit feedback."
    },
    {
      "name": "referral",
      "description": "Job referrals & the milestone-gated bonus payout (ENG-F01)."
    },
    {
      "name": "share_link",
      "description": "Scoped, expiring referral share links (ENG-F01)."
    },
    {
      "name": "referral_payout",
      "description": "Milestone-gated referral bonus payout, maker-checker (ENG-F01)."
    },
    {
      "name": "alumni_profile",
      "description": "Post-exit alumni network profile (ENG-F02)."
    },
    {
      "name": "rehire_request",
      "description": "Alumni rehire interest, forwarded into recruitment (ENG-F02)."
    },
    {
      "name": "rnr_category",
      "description": "HR-configured award categories (ENG-F03)."
    },
    {
      "name": "rnr_nomination",
      "description": "Peer/manager recognition nominations, maker-checker (ENG-F03)."
    },
    {
      "name": "celebration_wish",
      "description": "Peer birthday/anniversary wishes & threaded replies (ENG-F04)."
    },
    {
      "name": "announcement",
      "description": "Official broadcast feed + Immutable read-receipt ledger (ENG-F04)."
    },
    {
      "name": "promotion",
      "description": "Grade/designation change proposals, maker-checker (ENG-F05)."
    },
    {
      "name": "salary_revision",
      "description": "Pay-revision proposals, maker-checker (ENG-F05)."
    },
    {
      "name": "resignation",
      "description": "3-step resignation wizard & approval (EXT-F01)."
    },
    {
      "name": "exit_clearance",
      "description": "Multi-department clearance case & F&F gate (EXT-F02)."
    },
    {
      "name": "no_dues",
      "description": "Per-department no-dues sign-off lines (EXT-F02)."
    },
    {
      "name": "exit_feedback",
      "description": "Confidential exit-interview feedback (EXT-F03)."
    }
  ],
  "x-reuse-anchors": {
    "parameters": {
      "path_id": {
        "$ref": "#/components/parameters/PathId"
      },
      "page_size": {
        "$ref": "#/components/parameters/PageSize"
      },
      "page_after": {
        "$ref": "#/components/parameters/PageAfter"
      },
      "page_before": {
        "$ref": "#/components/parameters/PageBefore"
      },
      "accept_language": {
        "$ref": "#/components/parameters/AcceptLanguage"
      },
      "idempotency_key": {
        "$ref": "#/components/parameters/IdempotencyKey"
      },
      "if_match": {
        "$ref": "#/components/parameters/IfMatch"
      }
    },
    "responses": {
      "unauthorized": {
        "$ref": "#/components/responses/Unauthorized"
      },
      "forbidden": {
        "$ref": "#/components/responses/Forbidden"
      },
      "not_found": {
        "$ref": "#/components/responses/NotFound"
      },
      "conflict": {
        "$ref": "#/components/responses/Conflict"
      },
      "unprocessable": {
        "$ref": "#/components/responses/UnprocessableEntity"
      },
      "locked": {
        "$ref": "#/components/responses/Locked"
      },
      "too_many": {
        "$ref": "#/components/responses/TooManyRequests"
      },
      "precondition_required": {
        "$ref": "#/components/responses/PreconditionRequired"
      },
      "precondition_failed": {
        "$ref": "#/components/responses/PreconditionFailed"
      }
    },
    "headers": {
      "etag": {
        "$ref": "#/components/headers/ETag"
      },
      "location": {
        "$ref": "#/components/headers/Location"
      },
      "idem_replayed": {
        "$ref": "#/components/headers/IdempotencyReplayed"
      }
    }
  },
  "paths": {
    "/referrals": {
      "post": {
        "operationId": "engage.referral.create",
        "summary": "Refer a candidate (or file a general talent referral)",
        "description": "The Refer-a-candidate form's **Submit Referral** (ENG-S02) — creates `engage.referrals` (`channel='DIRECT'`, `status='SUBMITTED'`). The referred candidate enters the recruitment pipeline by **domain event** (REC-F03); this call never writes a `recruit` table, and `candidate_id` back-fills once the event is consumed (fsd 10 ENG-S02, db 11 §1.1). Server `dedupe_key` (normalized email/phone hash) blocks duplicate sourcing of the same candidate — 409 on a hit. When the referrer is an alumnus (reached from `ENG-S04` \"Refer a Friend\"), send `is_alumni_referral: true` + `alumni_id`.\n",
        "tags": [
          "engage",
          "referral"
        ],
        "x-token": "engage.referral.create",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S02"
        ],
        "x-touches-entities": [
          "engage.referrals",
          "engage.alumni_network"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral.submitted",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferralCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Referral created and `SUBMITTED`.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Referral"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "get": {
        "operationId": "engage.referral.list",
        "summary": "My referrals",
        "description": "The employee's own referrals by status — search + filter chips (`ENG-S01`). Own rows only (`referrer_employee_id = self`, `XC-F04`); `In review`/`In pipeline`/`Hired`/`Paid` chip groupings are client-composed over `status` per the fsd 10 ENG-S01 chip-to-enum mapping.\n",
        "tags": [
          "engage",
          "referral"
        ],
        "x-token": "engage.referral.list",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S01"
        ],
        "x-touches-entities": [
          "engage.referrals",
          "engage.referral_status",
          "engage.referral_payouts"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text search over `referee_name`/`referral_no` (ENG-S01 search field).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ReferralStatus"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `submitted_at`, `-submitted_at`, `status`. Default `-submitted_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of the caller's own referrals.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referrals/leaderboard": {
      "get": {
        "operationId": "engage.referral.list_leaderboard",
        "summary": "Referral leaderboard",
        "description": "Top referrers ranked by hired/paid referral count (ENG-S01 \"leaderboard entry\" — my rank; ENG-S11 \"Leaderboard\" panel — top referrers tenant-wide). Grouped `referrals` by `referrer_employee_id`, no cross-schema join. Rank-ordered server-side; `sort` is not accepted.\n",
        "tags": [
          "engage",
          "referral"
        ],
        "x-token": "engage.referral.list_leaderboard",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S01",
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referrals"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked page of referrers; the caller's own row is flagged `is_self`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralLeaderboardPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referrals/admin": {
      "get": {
        "operationId": "engage.referral.list_admin",
        "summary": "Referral pipeline (Recruiter/HR/Finance)",
        "description": "Tenant-wide referral pipeline grid — referral, referrer, candidate, opening, stage, status (`ENG-S11`).",
        "tags": [
          "engage",
          "referral"
        ],
        "x-token": "engage.referral.list_admin",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referrals",
          "engage.referral_status"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "referrer_employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ReferralStatus"
            }
          },
          {
            "name": "job_opening_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `submitted_at`, `-submitted_at`, `status`, `referrer_employee_id`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of referrals.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referrals/{id}": {
      "get": {
        "operationId": "engage.referral.get",
        "summary": "Referral detail & bonus tracker",
        "description": "One referral end to end — the pipeline timeline (`referral_status`, projected from `recruit.candidate.stage_changed`, no join), the milestone bonus card (`referral_payouts`), and any share link (`ENG-S03`).\n",
        "tags": [
          "engage",
          "referral"
        ],
        "x-token": "engage.referral.get",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S03"
        ],
        "x-touches-entities": [
          "engage.referrals",
          "engage.referral_status",
          "engage.referral_payouts",
          "engage.share_links"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          }
        ],
        "responses": {
          "200": {
            "description": "The referral with its pipeline timeline, payouts, and share link.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referrals/{id}/withdraw": {
      "post": {
        "operationId": "engage.referral.withdraw",
        "summary": "Withdraw a referral (pre-hire)",
        "description": "`status='WITHDRAWN'` while pre-`HIRED` (`ENG-S03` \"Withdraw referral\"). 409 `STATE_TRANSITION_INVALID` once `HIRED`+.",
        "tags": [
          "engage",
          "referral"
        ],
        "x-token": "engage.referral.withdraw",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S03"
        ],
        "x-touches-entities": [
          "engage.referrals"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral.withdrawn",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawn.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Referral"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/share-links": {
      "post": {
        "operationId": "engage.share_link.create",
        "summary": "Mint a scoped, expiring referral share link",
        "description": "The `ENG-S02` \"Share a link\" sheet — mints an unguessable, channel-tagged, expiring token (`status='ACTIVE'`). An apply-through on the careers surface (REC-F02) resolves the token and creates the attributed `referrals` row (`CONSUMED`); this call never writes a `recruit` table (db 11 §1.1).\n",
        "tags": [
          "engage",
          "share_link"
        ],
        "x-token": "engage.share_link.create",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S02"
        ],
        "x-touches-entities": [
          "engage.share_links"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShareLinkCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Share link minted.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareLink"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/share-links/admin": {
      "get": {
        "operationId": "engage.share_link.list_admin",
        "summary": "Share-links admin panel",
        "description": "Tenant-wide share links for revoke/audit (`ENG-S11` share-links admin panel).",
        "tags": [
          "engage",
          "share_link"
        ],
        "x-token": "engage.share_link.list_admin",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.share_links"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ShareLinkStatus"
            }
          },
          {
            "name": "referrer_employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `created_at`, `-created_at`, `expires_at`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of share links.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareLinkPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/share-links/{id}/revoke": {
      "post": {
        "operationId": "engage.share_link.revoke",
        "summary": "Revoke a share link",
        "description": "`ACTIVE → REVOKED` (`ENG-S11` \"Revoke\"). Audited (`XC-F06`).",
        "tags": [
          "engage",
          "share_link"
        ],
        "x-token": "engage.share_link.revoke",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.share_links"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.share_link.revoked",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShareLink"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referral-payouts": {
      "get": {
        "operationId": "engage.referral_payout.list",
        "summary": "Referral bonus payouts (Finance)",
        "description": "Milestone-gated payouts across the workforce — eligible/pending/approved/paid (`ENG-S11` payouts grid).",
        "tags": [
          "engage",
          "referral_payout"
        ],
        "x-token": "engage.referral_payout.list",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referral_payouts"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ReferralPayoutStatus"
            }
          },
          {
            "name": "referral_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "name": "milestone",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ReferralPayoutMilestone"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `eligible_on`, `-eligible_on`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of payouts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPayoutPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referral-payouts/{id}/submit": {
      "post": {
        "operationId": "engage.referral_payout.submit",
        "summary": "Submit an eligible payout for approval",
        "description": "`ELIGIBLE → PENDING_APPROVAL`, `submitted_by` stamped (the maker) and routed to the approvals inbox (`XC-F12`) — `ENG-S11` \"an `ELIGIBLE` payout awaits maker submission\" (fsd 10 §W3 States).\n",
        "tags": [
          "engage",
          "referral_payout"
        ],
        "x-token": "engage.referral_payout.submit",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referral_payouts",
          "xc.approval_inbox"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral_payout.submitted",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Submitted for approval.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referral-payouts/{id}/approve": {
      "post": {
        "operationId": "engage.referral_payout.approve",
        "summary": "Approve a referral payout (four-eyes)",
        "description": "`PENDING_APPROVAL → APPROVED`, `approved_by`/`approved_at`/`approval_ref` stamped; **four-eyes** `submitted_by <> approved_by` (db 11 §1.1 check). Emits the payable to payroll (PAY-F04); `pay_disbursement_ref`/`payslip_ref`/`paid_at` back-fill on disbursement confirmation (`ENG-S11` \"Approve payout\").\n",
        "tags": [
          "engage",
          "referral_payout"
        ],
        "x-token": "engage.referral_payout.approve",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referral_payouts"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral_payout.approved",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approved; disbursement instruction raised to `pay`.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referral-payouts/{id}/reject": {
      "post": {
        "operationId": "engage.referral_payout.reject",
        "summary": "Reject a referral payout",
        "description": "`PENDING_APPROVAL → REJECTED` (`ENG-S11`). `decision_note` is recorded on the approval envelope (`xc.approval_inbox`, `XC-F12`), not a column on this table.",
        "tags": [
          "engage",
          "referral_payout"
        ],
        "x-token": "engage.referral_payout.reject",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referral_payouts"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral_payout.rejected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rejected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referral-payouts/{id}/hold": {
      "post": {
        "operationId": "engage.referral_payout.hold",
        "summary": "Put a matured payout on hold",
        "description": "Any pre-`PAID` status `→ ON_HOLD` with a mandatory `hold_reason` (`ENG-S11`, db 11 §1.1).",
        "tags": [
          "engage",
          "referral_payout"
        ],
        "x-token": "engage.referral_payout.hold",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referral_payouts"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral_payout.held",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferralPayoutHoldInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "On hold.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/referral-payouts/{id}/cancel": {
      "post": {
        "operationId": "engage.referral_payout.cancel",
        "summary": "Cancel a matured payout",
        "description": "Voids a pre-`PAID` milestone — typically the hire exits before a retention boundary, an `exit.*`-driven cancellation (db 11 §1.1 Lifecycle). `ENG-S11`.\n",
        "tags": [
          "engage",
          "referral_payout"
        ],
        "x-token": "engage.referral_payout.cancel",
        "x-realizes-features": [
          "ENG-F01"
        ],
        "x-screens": [
          "ENG-S11"
        ],
        "x-touches-entities": [
          "engage.referral_payouts"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.referral_payout.cancelled",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelled.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/alumni-profiles/me": {
      "get": {
        "operationId": "engage.alumni_profile.get_me",
        "summary": "My alumni network profile",
        "description": "The alumnus's post-exit connected-pool home — role, scoped document-access window, rehire status, consent (`ENG-S04`). Created **post-exit** by an `exit.*` event; never written by this module directly (db 11 §1.2).\n",
        "tags": [
          "engage",
          "alumni_profile"
        ],
        "x-token": "engage.alumni_profile.get_me",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S04"
        ],
        "x-touches-entities": [
          "engage.alumni_network"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "responses": {
          "200": {
            "description": "The caller's alumni profile.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlumniProfile"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/alumni-profiles/me/opt-out": {
      "post": {
        "operationId": "engage.alumni_profile.opt_out",
        "summary": "Opt out of the alumni network",
        "description": "`consent_status='OPTED_OUT'` + `opted_out_at` — access withdrawn, the row is retained for audit (`ENG-S04` \"Opt-Out\" confirm sheet; db 11 §1.2). Excluded from directory/referral surfaces thereafter.\n",
        "tags": [
          "engage",
          "alumni_profile"
        ],
        "x-token": "engage.alumni_profile.opt_out",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S04"
        ],
        "x-touches-entities": [
          "engage.alumni_network"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.alumni_profile.opted_out",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Opted out.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlumniProfile"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/alumni-profiles/admin": {
      "get": {
        "operationId": "engage.alumni_profile.list_admin",
        "summary": "Alumni roster (HR)",
        "description": "The alumni roster — exit type, separation date, eligibility, consent, status (`ENG-S12`).",
        "tags": [
          "engage",
          "alumni_profile"
        ],
        "x-token": "engage.alumni_profile.list_admin",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S12"
        ],
        "x-touches-entities": [
          "engage.alumni_network"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/AlumniStatus"
            }
          },
          {
            "name": "rehire_eligibility",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RehireEligibility"
            }
          },
          {
            "name": "consent_status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/AlumniConsent"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `separation_date`, `-separation_date`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of alumni profiles.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlumniProfilePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/alumni-profiles/{id}": {
      "patch": {
        "operationId": "engage.alumni_profile.update_admin",
        "summary": "Set rehire eligibility / document-access window (HR)",
        "description": "`writes→engage.alumni_network.rehire_eligibility`/`.document_access_until` (`ENG-S12`). Consent is self-service only — never HR-writable.",
        "tags": [
          "engage",
          "alumni_profile"
        ],
        "x-token": "engage.alumni_profile.update_admin",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S12"
        ],
        "x-touches-entities": [
          "engage.alumni_network"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AlumniProfileUpdateAdmin"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlumniProfile"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rehire-requests": {
      "post": {
        "operationId": "engage.rehire_request.create",
        "summary": "Express rehire interest",
        "description": "The `ENG-S05` \"Express Interest\" action — creates `engage.rehire_requests` (`status='EXPRESSED'`). Gated by `alumni_network.rehire_eligibility` (`NOT_ELIGIBLE` disables submission).\n",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.create",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S05"
        ],
        "x-touches-entities": [
          "engage.rehire_requests",
          "engage.alumni_network"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rehire_request.expressed",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RehireRequestCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Interest expressed.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "get": {
        "operationId": "engage.rehire_request.list",
        "summary": "My rehire requests",
        "description": "The alumnus's own rehire requests and their status (`ENG-S05` \"My Rehire Requests\").",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.list",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S05"
        ],
        "x-touches-entities": [
          "engage.rehire_requests"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RehireStatus"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `created_at`, `-created_at`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of the caller's own rehire requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequestPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rehire-requests/{id}/withdraw": {
      "post": {
        "operationId": "engage.rehire_request.withdraw",
        "summary": "Withdraw a rehire request",
        "description": "`status='WITHDRAWN'` (`ENG-S05`).",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.withdraw",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S05"
        ],
        "x-touches-entities": [
          "engage.rehire_requests"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rehire_request.withdrawn",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RehireRequestDecisionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Withdrawn.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rehire-requests/admin": {
      "get": {
        "operationId": "engage.rehire_request.list_admin",
        "summary": "Rehire requests (HR/Recruiter)",
        "description": "Tenant-wide rehire requests for review/shortlist/forward (`ENG-S12`).",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.list_admin",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S12"
        ],
        "x-touches-entities": [
          "engage.rehire_requests"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RehireStatus"
            }
          },
          {
            "name": "job_opening_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `created_at`, `-created_at`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of rehire requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequestPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rehire-requests/{id}/shortlist": {
      "post": {
        "operationId": "engage.rehire_request.shortlist",
        "summary": "Shortlist a rehire request",
        "description": "`UNDER_REVIEW → SHORTLISTED`, `reviewed_by`/`reviewed_at` stamped (`ENG-S12` \"Review\").",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.shortlist",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S12"
        ],
        "x-touches-entities": [
          "engage.rehire_requests"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rehire_request.shortlisted",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Shortlisted.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rehire-requests/{id}/forward": {
      "post": {
        "operationId": "engage.rehire_request.forward",
        "summary": "Forward a shortlisted request into recruitment",
        "description": "`SHORTLISTED → FORWARDED_TO_RECRUIT`, `forwarded_at` stamped; emits the event that **creates a `recruit.candidates` row** (source rehire/`INTERNAL`) — `candidate_id` back-fills, never a `recruit` table write (db 11 §1.2, `ENG-S12`).\n",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.forward",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S12"
        ],
        "x-touches-entities": [
          "engage.rehire_requests"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rehire_request.forwarded_to_recruit",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Forwarded to recruitment.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rehire-requests/{id}/reject": {
      "post": {
        "operationId": "engage.rehire_request.reject",
        "summary": "Reject a rehire request",
        "description": "`→ REJECTED`, `decision_reason` required (`ENG-S12`).",
        "tags": [
          "engage",
          "rehire_request"
        ],
        "x-token": "engage.rehire_request.reject",
        "x-realizes-features": [
          "ENG-F02"
        ],
        "x-screens": [
          "ENG-S12"
        ],
        "x-touches-entities": [
          "engage.rehire_requests"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rehire_request.rejected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RehireRequestDecisionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rejected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RehireRequest"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-categories": {
      "get": {
        "operationId": "engage.rnr_category.list",
        "summary": "List award categories",
        "description": "Active award categories — used both by the mobile nominate form's category picker (`ENG-S06`) and the HR config grid (`ENG-S09`). Tenant-extensible lookup, not an enum (db 11 §1.3).\n",
        "tags": [
          "engage",
          "rnr_category"
        ],
        "x-token": "engage.rnr_category.list",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S06",
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_categories"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RnrCategoryStatus"
            }
          },
          {
            "name": "award_type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/RnrAwardType"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `category_code`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of award categories.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrCategoryPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "engage.rnr_category.create",
        "summary": "Create an award category (HR)",
        "description": "`ENG-S09` \"Award Categories\" `+` modal — creates `engage.rnr_categories` (`status='ACTIVE'` default).",
        "tags": [
          "engage",
          "rnr_category"
        ],
        "x-token": "engage.rnr_category.create",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_categories"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RnrCategoryCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Category created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrCategory"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-categories/{id}": {
      "get": {
        "operationId": "engage.rnr_category.get",
        "summary": "Get an award category",
        "description": "Single category detail, for the `ENG-S09` edit modal.",
        "tags": [
          "engage",
          "rnr_category"
        ],
        "x-token": "engage.rnr_category.get",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_categories"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "The category.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrCategory"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "engage.rnr_category.update",
        "summary": "Edit an award category (HR)",
        "description": "Edits name/description/amount/approval/periodicity/quota/status (`ENG-S09`, db 11 §1.3).",
        "tags": [
          "engage",
          "rnr_category"
        ],
        "x-token": "engage.rnr_category.update",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_categories"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RnrCategoryUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrCategory"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-nominations": {
      "post": {
        "operationId": "engage.rnr_nomination.create",
        "summary": "Nominate a colleague",
        "description": "The `ENG-S06` \"Submit Nomination\" form — creates `engage.rnr_nominations` (`DRAFT`→`SUBMITTED`). A `requires_approval` category routes to the approvals inbox (`SUBMITTED→PENDING_APPROVAL`, `XC-F12`); otherwise `SUBMITTED→AWARDED` directly. No self-nomination (`nominee_employee_id <> nominator_employee_id`, db 11 §1.3 check). A category's `max_nominations_per_period` quota is enforced server-side — 409 on breach.\n",
        "tags": [
          "engage",
          "rnr_nomination"
        ],
        "x-token": "engage.rnr_nomination.create",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S06"
        ],
        "x-touches-entities": [
          "engage.rnr_nominations",
          "engage.rnr_categories"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rnr_nomination.submitted",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RnrNominationCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Nomination submitted (`SUBMITTED`, `PENDING_APPROVAL`, or `AWARDED` per category config).",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrNomination"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-nominations/feed": {
      "get": {
        "operationId": "engage.rnr_nomination.list_feed",
        "summary": "Recognition feed",
        "description": "Announced nominations (`is_announced=true`) — the `ENG-S06` feed and the `ENG-S09` \"Recognition Feed\" panel. Tenant-wide, RBAC-visible (not row-owned).\n",
        "tags": [
          "engage",
          "rnr_nomination"
        ],
        "x-token": "engage.rnr_nomination.list_feed",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S06",
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_nominations"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `awarded_at`, `-awarded_at`. Default `-awarded_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of announced nominations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrNominationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-nominations/leaderboard": {
      "get": {
        "operationId": "engage.rnr_nomination.list_leaderboard",
        "summary": "Recognition leaderboard",
        "description": "Nominees ranked by award count over All-time / This-quarter / This-year (`ENG-S09` \"Leaderboard\" panel). Rank-ordered server-side; `sort` is not accepted.",
        "tags": [
          "engage",
          "rnr_nomination"
        ],
        "x-token": "engage.rnr_nomination.list_leaderboard",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_nominations"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "`ALL_TIME` (default) · `QUARTER` · `YEAR`.",
            "schema": {
              "type": "string",
              "enum": [
                "ALL_TIME",
                "QUARTER",
                "YEAR"
              ],
              "default": "ALL_TIME"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked page of nominees.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrLeaderboardPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-nominations/admin": {
      "get": {
        "operationId": "engage.rnr_nomination.list_admin",
        "summary": "Pending nominations (HR/Manager)",
        "description": "The `ENG-S09` \"Pending Nominations\" grid — all nominations, filterable by status.",
        "tags": [
          "engage",
          "rnr_nomination"
        ],
        "x-token": "engage.rnr_nomination.list_admin",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_nominations"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/NominationStatus"
            }
          },
          {
            "name": "category_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "name": "nominee_employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `created_at`, `-created_at`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of nominations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrNominationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-nominations/{id}/approve": {
      "post": {
        "operationId": "engage.rnr_nomination.approve",
        "summary": "Approve a nomination (four-eyes)",
        "description": "`PENDING_APPROVAL → APPROVED → AWARDED`, `approved_by`/`approved_at`/`approval_ref` stamped (`submitted_by <> approver`, `XC-F12`). A monetary category emits the payable to payroll (PAY-F04, `pay_disbursement_ref` back-fills) and announces the win (`is_announced=true`, `XC-F05`/`XC-F09`). `ENG-S09` \"Approve\".\n",
        "tags": [
          "engage",
          "rnr_nomination"
        ],
        "x-token": "engage.rnr_nomination.approve",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_nominations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rnr_nomination.awarded",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approved and awarded.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrNomination"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/rnr-nominations/{id}/reject": {
      "post": {
        "operationId": "engage.rnr_nomination.reject",
        "summary": "Reject a nomination",
        "description": "`PENDING_APPROVAL → REJECTED` (`ENG-S09` \"Reject\"). `decision_note` recorded on the approval envelope (`xc.approval_inbox`), not a column on this table.",
        "tags": [
          "engage",
          "rnr_nomination"
        ],
        "x-token": "engage.rnr_nomination.reject",
        "x-realizes-features": [
          "ENG-F03"
        ],
        "x-screens": [
          "ENG-S09"
        ],
        "x-touches-entities": [
          "engage.rnr_nominations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.rnr_nomination.rejected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rejected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RnrNomination"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/celebration-wishes": {
      "get": {
        "operationId": "engage.celebration_wish.list",
        "summary": "A colleague's celebration wishes",
        "description": "The wishes (and threaded replies) for one subject's celebration moment — the `ENG-S07` \"Received\" view. Single-level thread (`parent_wish_id` may only reference a top-level wish, db 11 §1.4 check).\n",
        "tags": [
          "engage",
          "celebration_wish"
        ],
        "x-token": "engage.celebration_wish.list",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S07"
        ],
        "x-touches-entities": [
          "engage.celebration_wishes"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "subject_employee_id",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "name": "occasion_date",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/DateOnlyRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `occurred_at`, `-occurred_at`. Default `occurred_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of wishes (and their replies) for the subject's celebration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CelebrationWishPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "engage.celebration_wish.create",
        "summary": "Send a wish or reply to one",
        "description": "The `ENG-S07` \"Send\" (frame 68, top-level wish, `parent_wish_id` null) and \"Reply\" (frame 70, thanks reply, `parent_wish_id` set) actions — both write `engage.celebration_wishes` (db 11 §1.4). The celebration **card** itself is a derived moment off `people` birth/join-date (`XC-F08`), not stored here.\n",
        "tags": [
          "engage",
          "celebration_wish"
        ],
        "x-token": "engage.celebration_wish.create",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S07"
        ],
        "x-touches-entities": [
          "engage.celebration_wishes"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.celebration_wish.sent",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CelebrationWishCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Wish (or reply) sent.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CelebrationWish"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements": {
      "get": {
        "operationId": "engage.announcement.list",
        "summary": "Announcement feed (employee)",
        "description": "The official broadcast feed, pinned-first — `ENG-S08`. Audience is **RBAC-targeted server-side** (`audience_type`/`audience_filter`), never a client join; only `PUBLISHED` (and not yet `expires_at`) notices addressed to the caller are returned. The feed surfaces as **Home-feed cards + Notifications entries** (G-14③ decided 2026-07-02, `design-docs/04`; design round adds the card mappings) — specced to the FSD data contract.\n**Implementation note (2026-07-31).** Forward keyset paging (`page[after]`) is live; `page[before]` is accepted by the contract but not yet implemented and currently returns `422 VALIDATION_FAILED`. `prev_cursor` is therefore always `null`.\n",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.list",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S08"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/AnnouncementCategory"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `is_pinned`, `published_at`, `-published_at`. Default `-is_pinned,-published_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of the caller's targeted, published announcements.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "engage.announcement.create",
        "summary": "Compose an announcement (HR)",
        "description": "`ENG-S10` compose wizard — creates `engage.announcements` (`status='DRAFT'`, or `'SCHEDULED'` when `publish_at` is set).",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.create",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnnouncementCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Announcement created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/admin": {
      "get": {
        "operationId": "engage.announcement.list_admin",
        "summary": "Announcements console (HR)",
        "description": "The `ENG-S10` grid — no./title/category/audience/status/publish-date/read-ack% across all statuses (Draft · Scheduled · Published · Expired/Archived tabs).\n**Implementation note (2026-07-31).** As on `engage.announcement.list`, only forward (`page[after]`) paging is implemented; `page[before]` returns `422 VALIDATION_FAILED` and `prev_cursor` is always `null`. `target_count` is not derived yet and is returned as `null`.\n",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.list_admin",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements",
          "engage.announcement_reads"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/AnnouncementStatus"
            }
          },
          {
            "name": "audience_type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/AnnouncementAudience"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `publish_at`, `-publish_at`, `status`. Default `-publish_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of announcements with read/ack rollups.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdminPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/admin/exports": {
      "post": {
        "operationId": "engage.announcement.export",
        "summary": "Export the announcements grid",
        "description": "Generates a capped, filtered CSV export of the announcements console (`ENG-S10` \"Export\").",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.export",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "status": {
                    "$ref": "#/components/schemas/AnnouncementStatus"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presigned download handle for the generated export.",
            "headers": {
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileDownloadRef"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/{id}": {
      "get": {
        "operationId": "engage.announcement.get",
        "summary": "Announcement detail",
        "description": "Title/body/attachments plus the caller's own read/ack state (`ENG-S08` detail); when the caller is HR, the response also carries the read/ack rollup used by the `ENG-S10` detail drawer. Same G-14③ resolution as `engage.announcement.list` (Home-feed cards + notifications) for the employee-facing use.\n",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.get",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S08",
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements",
          "engage.announcement_reads"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "The announcement.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "engage.announcement.update",
        "summary": "Edit a draft/scheduled announcement (HR)",
        "description": "Edits content/targeting/schedule before it is `PUBLISHED` (`ENG-S10`).",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.update",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnnouncementUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/{id}/publish": {
      "post": {
        "operationId": "engage.announcement.publish",
        "summary": "Publish an announcement (HR)",
        "description": "`DRAFT`/`SCHEDULED → PUBLISHED`, `published_at` stamped; surfaces on the feed (`XC-F09`) and pushes (`XC-F05`) to the targeted audience only (`ENG-S10` \"Publish\").",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.publish",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.announcement.published",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Published.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/{id}/archive": {
      "post": {
        "operationId": "engage.announcement.archive",
        "summary": "Archive an announcement (HR)",
        "description": "`→ ARCHIVED`, retired from the feed but retained (`ENG-S10` \"Archive/Expire\").",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.archive",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.announcement.archived",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Archived.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/{id}/cancel": {
      "post": {
        "operationId": "engage.announcement.cancel",
        "summary": "Discard a draft or scheduled announcement (HR)",
        "description": "Soft-deletes a `DRAFT` or `SCHEDULED` notice so it leaves the ENG-S10 grid. Gated by `engage.announcement.update` (no extra token — deliberate reuse, same family as `work.project_allocation.split`). Published notices use `engage.announcement.archive`. `coverage.py` reports `x-token != operationId` for this path; that is a gate gap, not drift.\n",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement.update",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S10"
        ],
        "x-touches-entities": [
          "engage.announcements"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Discarded.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/announcements/{id}/reads": {
      "post": {
        "operationId": "engage.announcement_read.create",
        "summary": "Record a read or acknowledgement receipt",
        "description": "Opening a notice writes a **`READ`** receipt (`channel='MOBILE'`/`'WEB'`); the sticky **Acknowledge** CTA on a `requires_acknowledgement` notice writes an **`ACKNOWLEDGED`** receipt — both **append-only**, a re-read/re-ack is a new row, never an edit (`ENG-S08`, db 11 §1.4, Immutable). Same G-14③ resolution as the feed (Home-feed cards + notifications).\n**Idempotent per `(announcement, employee, event_type)`** — the ledger's unique index makes a duplicate row impossible, so re-posting the same receipt under a NEW `Idempotency-Key` returns `201` with the receipt already on file rather than an error. `409` is reserved for `IDEMPOTENCY_KEY_REUSE` (same key, different body). An `ACKNOWLEDGED` receipt against a notice with `requires_acknowledgement: false` is `422`.\n",
        "tags": [
          "engage",
          "announcement"
        ],
        "x-token": "engage.announcement_read.create",
        "x-realizes-features": [
          "ENG-F04"
        ],
        "x-screens": [
          "ENG-S08"
        ],
        "x-touches-entities": [
          "engage.announcement_reads"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.announcement.read",
        "x-rls-scope": "self",
        "x-append-only": true,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnnouncementReadCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Receipt recorded.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnnouncementRead"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/promotions": {
      "post": {
        "operationId": "engage.promotion.create",
        "summary": "Propose a promotion / role change (HR/Manager)",
        "description": "`ENG-S13` propose — creates `engage.promotions` (`status='DRAFT'` or `'PENDING_APPROVAL'` when `submit: true`). Typically seeded by `perform.calibration.signed` (`source='CALIBRATION'`, `calibration_ref` required, PRF-F02) or created manually (`source='MANUAL'`).\n",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.create",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.promotion.submitted",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromotionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Promotion proposal created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "get": {
        "operationId": "engage.promotion.list",
        "summary": "Promotions console grid (HR/Manager/Finance)",
        "description": "The `ENG-S13` promotions grid — employee, type, from→to designation/grade, effective date, status.",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.list",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/PromotionStatus"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `effective_date`, `-effective_date`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of promotions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromotionPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/promotions/{id}": {
      "get": {
        "operationId": "engage.promotion.get",
        "summary": "Get a promotion proposal",
        "description": "Full proposal detail for the `ENG-S13` drawer.",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.get",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          }
        ],
        "responses": {
          "200": {
            "description": "The promotion proposal.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "engage.promotion.update",
        "summary": "Edit a draft promotion proposal (HR/Manager)",
        "description": "Edits placement/effective-date/justification while `DRAFT` (`ENG-S13`); pass `submit: true` to move `DRAFT → PENDING_APPROVAL`.",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.update",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.promotion.submitted",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromotionUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated (and, if `submit: true`, now `PENDING_APPROVAL`).",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/promotions/{id}/approve": {
      "post": {
        "operationId": "engage.promotion.approve",
        "summary": "Approve a promotion (four-eyes)",
        "description": "`PENDING_APPROVAL → APPROVED` (→ `SCHEDULED` if `effective_date` is future, else `EFFECTED` immediately); `submitted_by <> approved_by` (db 11 §1.5 check). On `EFFECTED` an event updates `people`/`org` placement (ORG-F06) and generates the promotion letter (DOC-F03) — `engage` never writes those tables. `ENG-S13` \"Approve\".\n",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.approve",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.promotion.approved",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approved.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/promotions/{id}/effect": {
      "post": {
        "operationId": "engage.promotion.effect",
        "summary": "Effect a scheduled promotion (HR)",
        "description": "`SCHEDULED → EFFECTED`, on or after `effective_date`. In one transaction it writes the org placement, opens the `people.position_history` period (`change_reason='PROMOTION'`, `source_ref` = this promotion) and, when the promotion carries a linked salary revision, opens the `pay.employee_compensation` row with `revision_reason='PROMOTION'` — each through the owning module's own service seam, so `engage` still writes no `people`/`pay` table.\n\n**Why this is a human action and not a nightly sweep.** `ENG-S13`'s spec says the effect happens \"by event\", and the outbox → jobs tier is that rail — but the jobs tier is a separate process that reaches the database through raw SQL and cannot call a domain service, so every scheduled transition in this corpus is a SQL function. Effecting a promotion is not expressible that way without reimplementing `pay`'s compensation writer — its pay-group and currency resolution, its refusals and its deliberately figure-free audit row — in a second language, which is exactly the two-writer shape ENG-F05 exists to remove. The automatic sweep is therefore deferred to the issue that builds that rail; until then a `SCHEDULED` promotion is effected from the console on the day.\n\nRefuses before `effective_date`, and refuses when the employee's placement has drifted since the proposal was raised (`409`) — an approver decided on the placement they were shown, and a stale decision must not silently overwrite a later move.\n",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.effect",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions",
          "engage.salary_revisions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.promotion.effected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Effected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/promotions/{id}/reject": {
      "post": {
        "operationId": "engage.promotion.reject",
        "summary": "Reject a promotion",
        "description": "`PENDING_APPROVAL → REJECTED` (`ENG-S13` \"Reject\").",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.reject",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.promotion.rejected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rejected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/promotions/{id}/cancel": {
      "post": {
        "operationId": "engage.promotion.cancel",
        "summary": "Cancel a promotion before effect",
        "description": "Any pre-`EFFECTED` status `→ CANCELLED` (withdrawn before effect, `ENG-S13`).",
        "tags": [
          "engage",
          "promotion"
        ],
        "x-token": "engage.promotion.cancel",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.promotions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.promotion.cancelled",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelled.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/salary-revisions": {
      "post": {
        "operationId": "engage.salary_revision.create",
        "summary": "Propose a salary revision (HR/Finance)",
        "description": "`ENG-S13` propose — creates `engage.salary_revisions` (`status='DRAFT'` or `'PENDING_APPROVAL'` when `submit: true`); optionally linked to a `promotions` row (`promotion_id`). Typically seeded by `perform.calibration.signed` (`source='CALIBRATION'`, PRF-F02).\n",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.create",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions",
          "engage.promotions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.salary_revision.submitted",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SalaryRevisionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Salary-revision proposal created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "get": {
        "operationId": "engage.salary_revision.list",
        "summary": "Salary-revisions console grid (HR/Finance)",
        "description": "The `ENG-S13` salary-revisions grid — employee, type, current→revised CTC, increment %, effective date, status.",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.list",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "name": "employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/SalaryRevisionStatus"
            }
          },
          {
            "name": "fiscal_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `effective_date`, `-effective_date`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of salary revisions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevisionPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/salary-revisions/{id}": {
      "get": {
        "operationId": "engage.salary_revision.get",
        "summary": "Get a salary-revision proposal",
        "description": "Full proposal detail for the `ENG-S13` drawer.",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.get",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          }
        ],
        "responses": {
          "200": {
            "description": "The salary-revision proposal.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "engage.salary_revision.update",
        "summary": "Edit a draft salary-revision proposal (HR/Finance)",
        "description": "Edits amounts/structure/effective-date while `DRAFT` (`ENG-S13`); pass `submit: true` to move `DRAFT → PENDING_APPROVAL`.",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.update",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.salary_revision.submitted",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SalaryRevisionUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated (and, if `submit: true`, now `PENDING_APPROVAL`).",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/salary-revisions/{id}/approve": {
      "post": {
        "operationId": "engage.salary_revision.approve",
        "summary": "Approve a salary revision (four-eyes, incl. Finance)",
        "description": "`PENDING_APPROVAL → APPROVED` (→ `SCHEDULED`/`EFFECTED`); `submitted_by <> approved_by` (db 11 §1.5 check). On `EFFECTED` an event updates the **pay structure** (ORG-F06 → `pay`; the next payroll run picks it up) and generates the increment letter (DOC-F03). `ENG-S13` \"Approve\".\n",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.approve",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.salary_revision.approved",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approved.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/salary-revisions/{id}/reject": {
      "post": {
        "operationId": "engage.salary_revision.reject",
        "summary": "Reject a salary revision",
        "description": "`PENDING_APPROVAL → REJECTED` (`ENG-S13` \"Reject\").",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.reject",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.salary_revision.rejected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rejected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/salary-revisions/{id}/cancel": {
      "post": {
        "operationId": "engage.salary_revision.cancel",
        "summary": "Cancel a salary revision before effect",
        "description": "Any pre-`EFFECTED` status `→ CANCELLED` (`ENG-S13`).",
        "tags": [
          "engage",
          "salary_revision"
        ],
        "x-token": "engage.salary_revision.cancel",
        "x-realizes-features": [
          "ENG-F05"
        ],
        "x-screens": [
          "ENG-S13"
        ],
        "x-touches-entities": [
          "engage.salary_revisions"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "engage.salary_revision.cancelled",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": "engage",
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelled.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations": {
      "post": {
        "operationId": "exit.resignation.create",
        "summary": "File a resignation (create-and-submit)",
        "description": "GAP-36 minimal slice (#964): creates `exit.resignations` AND submits it in the SAME transaction — `status='SUBMITTED'`, `wizard_step='REVIEW'`, `submitted_at`/`resignation_date` stamped, emitting `exit.resignation.submitted`. This deliberately COLLAPSES the 3-step wizard `EXT-S01` otherwise describes (`.create`→DRAFT, `.update`→REVIEW+ESOP snapshot, `.submit`→ SUBMITTED, all three specced below): GAP-36 scopes the API slice to exactly create/get_me/ withdraw, so this single call performs what would otherwise be Steps 1 and 3 at once. A future slice may reinstate the separate DRAFT/`.update`/`.submit` path without breaking this operation's request/response shape — `ResignationCreate` is unchanged either way. `notice_period_days` is ALWAYS server-derived from the caller's legal entity's effective compliance pack (`rules.statutory.exit.noticePeriodDays`, `XC-F01`) — there is no `notice_period_days` property on the request body, so a client cannot supply one even by accident; a pack with no employment-notice rule configured yet 422s naming the field rather than guessing a statutory default (ADR 0005). A **one-active-resignation guard** applies (`unique (employee_id) where status NOT IN ('REJECTED','WITHDRAWN')`, db 11 §2.1) — 409 on a second active attempt.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.create",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S01"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.resignation.submitted",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResignationCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Resignation filed and submitted for approval.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/me": {
      "get": {
        "operationId": "exit.resignation.get_me",
        "summary": "My resignation status",
        "description": "The caller's current (most recent active) resignation — status timeline, LWD, ESOP recap, withdraw eligibility (`EXT-S02`).\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.get_me",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S02"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "responses": {
          "200": {
            "description": "The caller's resignation.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/for-approval": {
      "get": {
        "operationId": "exit.resignation.list_for_approval",
        "summary": "Resignations routed to me for a decision",
        "description": "The **approver-scoped** read of `exit.resignations` — the resignations whose `xc.approval_inbox` envelope is routed to the caller, at `TEAM` scope. It exists because a resignation has **no console route**: the unified approvals drawer (`XC-S15` / `XC-S18`) is its only decision surface, and that drawer's evidence lane is a batched read of this list. Before it, a routed line manager could *decide* an exit and could not *see* it — no last working day, no notice shortfall, no reason (#1647, #1331). Same response shape, filters and sort whitelist as `exit.resignation.list_admin`; the only difference is the scope, and therefore which rows come back. Confinement is in the DATABASE, not the handler: migration `0230` adds a `TEAM`-gated leg to `exit.resignations`' RESTRICTIVE ownership overlay that admits a row only when the caller is the `current_approver_id` or `effective_approver_id` on its envelope, so a manager cannot read a colleague's unrelated resignation even if a handler forgot its predicate.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.list_for_approval",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations",
          "xc.approval_inbox"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "team",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ResignationStatus"
            }
          },
          {
            "name": "employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `-submitted_at` (default), `submitted_at`, `approved_last_working_day`, `-approved_last_working_day`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The resignations routed to the caller for a decision.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResignationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/admin": {
      "get": {
        "operationId": "exit.resignation.list_admin",
        "summary": "Separation dashboard grid (HR)",
        "description": "The `EXT-S05` grid — tabs On Notice · Clearance · Completed This Month · All; employee, LWD, notice period, exit reason, clearance progress, F&F status.",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.list_admin",
        "x-realizes-features": [
          "EXT-F01",
          "EXT-F02",
          "EXT-F03"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations",
          "exit.exit_clearances",
          "exit.exit_feedback"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ResignationStatus"
            }
          },
          {
            "name": "employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `-submitted_at` (**default**), `submitted_at`, `approved_last_working_day`, `-approved_last_working_day`, `status`. `-submitted_at` is the default because `approved_last_working_day` is NULL until a resignation is accepted, so ordering on it sorts every row still awaiting a decision LAST — and off the page entirely once a tenant has a page-size worth of settled separations (#1647). Nullable sort columns order `NULLS LAST`.\n",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of resignations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResignationPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "exit.resignation.create_admin",
        "summary": "Initiate an involuntary separation (HR)",
        "description": "`EXT-S05` \"+ Initiate Separation\" — HR-initiated `exit.resignations` row for an involuntary exit (fsd 10 EXT-S05).",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.create_admin",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResignationCreateAdmin"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Involuntary separation record created.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/admin/exports": {
      "post": {
        "operationId": "exit.resignation.export",
        "summary": "Export the exit report",
        "description": "Generates a capped, filtered CSV export of the separation dashboard (`EXT-S05` \"Export Exit Report\").",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.export",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "status": {
                    "$ref": "#/components/schemas/ResignationStatus"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presigned download handle for the generated export.",
            "headers": {
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileDownloadRef"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/{id}": {
      "get": {
        "operationId": "exit.resignation.get_admin",
        "summary": "Get a resignation (HR detail drawer)",
        "description": "Full resignation detail for the `EXT-S05` drawer — resignation review, ESOP note, approval trail.",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.get_admin",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          }
        ],
        "responses": {
          "200": {
            "description": "The resignation.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "exit.resignation.update",
        "summary": "Continue the wizard (Step 2 · Review) or edit a draft",
        "description": "Edits `DRAFT` fields, or advances `wizard_step: NOTICE → REVIEW` (`EXT-S01` Step 2 \"Review\") — reaching `REVIEW` synchronously reads the ESOP-impact snapshot from `pay` (PAY-F05) and stamps `esop_impact` (a display snapshot; the live truth stays in `pay`, db 11 §2.1). Still `DRAFT` until `.submit`.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.update",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S01"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResignationUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated (ESOP-impact snapshot stamped if `wizard_step` reached `REVIEW`).",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/{id}/submit": {
      "post": {
        "operationId": "exit.resignation.submit",
        "summary": "Confirm resignation (wizard Step 3 · Confirm)",
        "description": "`EXT-S01` Step 3 \"Confirm Resignation\" — `DRAFT → SUBMITTED`, `submitted_at`/`resignation_date` stamped; routed to the manager/HR approver via the unified inbox (`SUBMITTED→PENDING_APPROVAL`, `XC-F12`). 409 `STATE_TRANSITION_INVALID` once past `DRAFT`.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.submit",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S01"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.resignation.submitted",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Submitted; routed for approval.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/{id}/withdraw": {
      "post": {
        "operationId": "exit.resignation.withdraw",
        "summary": "Withdraw a resignation (pre-approval)",
        "description": "`status='WITHDRAWN'` + `withdrawal_reason`, allowed only while `status ∈ {SUBMITTED, PENDING_APPROVAL}` (`EXT-S02` \"Withdraw\"; the data model supports pre-approval withdrawal despite the wizard's \"irreversible\" copy — fsd 10 §1.4). 409 `STATE_TRANSITION_INVALID` once `APPROVED`+.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.withdraw",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S02"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.resignation.withdrawn",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResignationWithdrawInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Withdrawn.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/{id}/approve": {
      "post": {
        "operationId": "exit.resignation.approve",
        "summary": "Approve a resignation (manager/HR)",
        "description": "`PENDING_APPROVAL → APPROVED`, `approved_by`/`approved_at`/`approval_ref`/ `approved_last_working_day` stamped; **emits `exit.resignation.approved`**, which opens `exit_clearances` (EXT-F02, db 11 §2.1). `EXT-S05` \"Approve\" (approver may be the reporting Manager via `XC-F12`).\n\n**Not implemented as a route, deliberately (`#1331`).** Submitting a resignation projects an `xc.approval_inbox` envelope (`request_type = 'RESIGNATION'`, migration `0195`), and the decision is taken with `xc.approval_inbox.decide`, which calls the `exit` module's own transition through `ApprovalSourceActionRouter` (ADR 0036). The inbox is the **single** decision surface — a live module route beside a live chain is the two-writer shape `security-docs/04` exists to prevent — exactly as `recruit.requisitions`/`recruit.offers` resolved the same question. This operation and its token stay chartered but unminted; if a console-local entrance is ever wanted it must reach the same transition, the way `engage.promotion.approve` does.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.approve",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.resignation.approved",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResignationApproveInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approved; clearance opened.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/{id}/reject": {
      "post": {
        "operationId": "exit.resignation.reject",
        "summary": "Reject a resignation",
        "description": "`PENDING_APPROVAL → REJECTED`; despite the approver-named columns, `approved_by`/`approved_at` are stamped on rejection too (db 11 §2.1 Notes). `EXT-S05` \"Reject\".\n\n**Not implemented as a route, deliberately (`#1331`)** — see `exit.resignation.approve` above: the unified approvals inbox is the single decision surface for this envelope.\n",
        "tags": [
          "exit",
          "resignation"
        ],
        "x-token": "exit.resignation.reject",
        "x-realizes-features": [
          "EXT-F01"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.resignation.rejected",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionNoteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rejected.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/exit-clearances/me": {
      "get": {
        "operationId": "exit.exit_clearance.get_me",
        "summary": "My clearance & no-dues",
        "description": "The departing employee's clearance progress — department lines and dues, plus the F&F gate flag (computed/released in `pay`, PAY-F07) — `EXT-S03`. Read-only for the employee; sign-off is the department owners' (`EXT-S06`).\n",
        "tags": [
          "exit",
          "exit_clearance"
        ],
        "x-token": "exit.exit_clearance.get_me",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S03"
        ],
        "x-touches-entities": [
          "exit.exit_clearances",
          "exit.no_dues"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "responses": {
          "200": {
            "description": "The caller's clearance case with its department lines.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitClearanceDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/exit-clearances/admin": {
      "get": {
        "operationId": "exit.exit_clearance.list_admin",
        "summary": "Clearance cases board (department owners/HR)",
        "description": "The `EXT-S06` clearance-cases grid — clearance no., employee, LWD, progress, status.",
        "tags": [
          "exit",
          "exit_clearance"
        ],
        "x-token": "exit.exit_clearance.list_admin",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S06"
        ],
        "x-touches-entities": [
          "exit.exit_clearances"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ClearanceStatus"
            }
          },
          {
            "name": "employee_id",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `last_working_day`, `-last_working_day`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of clearance cases.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitClearancePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/exit-clearances/{id}": {
      "get": {
        "operationId": "exit.exit_clearance.get_admin",
        "summary": "Get a clearance case (department detail)",
        "description": "The `EXT-S06` per-case detail — the five no-dues lines (IT · Finance · Admin · HR · Manager), each with owner/status/dues/asset-return/sign-off.",
        "tags": [
          "exit",
          "exit_clearance"
        ],
        "x-token": "exit.exit_clearance.get_admin",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S06"
        ],
        "x-touches-entities": [
          "exit.exit_clearances",
          "exit.no_dues"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          }
        ],
        "responses": {
          "200": {
            "description": "The clearance case with its department lines.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitClearanceDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/no-dues/{id}/sign-off": {
      "post": {
        "operationId": "exit.no_dues.sign_off",
        "summary": "Clear a department no-dues line",
        "description": "`→ CLEARED`, `signed_off_by`/`signed_off_at` stamped (`EXT-S06` \"Clear\"). When this is the last line, the parent `exit_clearances` moves to `CLEARED` and **`exit.clearance.completed`** fires — releasing F&F in `pay` (PAY-F07) and reconciling asset return (AST-F02, db 11 §2.2).\n",
        "tags": [
          "exit",
          "no_dues"
        ],
        "x-token": "exit.no_dues.sign_off",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S06"
        ],
        "x-touches-entities": [
          "exit.no_dues",
          "exit.exit_clearances"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.no_dues.cleared",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoDuesRemarksInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Line cleared (parent `CLEARED` + F&F released if this was the last line).",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoDuesLine"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/no-dues/{id}/waive": {
      "post": {
        "operationId": "exit.no_dues.waive",
        "summary": "Waive a department no-dues line",
        "description": "`→ WAIVED`, `signed_off_by`/`signed_off_at` stamped — cleared with dues authorised-waived (`EXT-S06` \"Waive\"). Same cascade as `.sign_off` when it is the last line.",
        "tags": [
          "exit",
          "no_dues"
        ],
        "x-token": "exit.no_dues.waive",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S06"
        ],
        "x-touches-entities": [
          "exit.no_dues",
          "exit.exit_clearances"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.no_dues.waived",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoDuesRemarksInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Line waived (parent `CLEARED` + F&F released if this was the last line).",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoDuesLine"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/no-dues/{id}/flag-dues": {
      "post": {
        "operationId": "exit.no_dues.flag_dues",
        "summary": "Flag outstanding dues on a no-dues line",
        "description": "`→ DUES_PENDING` + `dues_amount`/`currency_code` — blocks the parent clearance until settled; feeds F&F recovery (`EXT-S06` \"Flag Dues\").",
        "tags": [
          "exit",
          "no_dues"
        ],
        "x-token": "exit.no_dues.flag_dues",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S06"
        ],
        "x-touches-entities": [
          "exit.no_dues"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.no_dues.dues_flagged",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoDuesFlagDuesInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dues flagged.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoDuesLine"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/no-dues/{id}/force-complete": {
      "post": {
        "operationId": "exit.no_dues.force_complete",
        "summary": "Force-complete a stuck no-dues line (HR override)",
        "description": "HR override of a stuck line — `EXT-S05` \"Force Complete\", mandatory `remarks`, audited (`XC-F06`). Distinct from `.sign_off`/`.waive` (department-owner actions); this is the HR escalation path.\n",
        "tags": [
          "exit",
          "no_dues"
        ],
        "x-token": "exit.no_dues.force_complete",
        "x-realizes-features": [
          "EXT-F02"
        ],
        "x-screens": [
          "EXT-S05"
        ],
        "x-touches-entities": [
          "exit.no_dues"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.no_dues.force_completed",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NoDuesForceCompleteInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Force-completed.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NoDuesLine"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/resignations/{id}/exit-feedback": {
      "post": {
        "operationId": "exit.exit_feedback.create",
        "summary": "Submit exit feedback",
        "description": "The `EXT-S04` confidential questionnaire — creates `exit.exit_feedback` (`status='SUBMITTED'`), **one per separation** (`unique (resignation_id)`, db 11 §2.3). When `is_anonymous`, `employee_id` is not stored; attribution is thereafter **RBAC-restricted** for HR consumers, never shown, and never surfaced individually in analytics (`XC-F15`, db 11 §2.3 Notes, rev. 2026-07-02).\n",
        "tags": [
          "exit",
          "exit_feedback"
        ],
        "x-token": "exit.exit_feedback.create",
        "x-realizes-features": [
          "EXT-F03"
        ],
        "x-screens": [
          "EXT-S04"
        ],
        "x-touches-entities": [
          "exit.exit_feedback",
          "exit.resignations"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.exit_feedback.submitted",
        "x-rls-scope": "self",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExitFeedbackCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Feedback submitted.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitFeedback"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/exit-feedback/admin": {
      "get": {
        "operationId": "exit.exit_feedback.list_admin",
        "summary": "Exit feedback grid (HR)",
        "description": "The `EXT-S07` feedback grid — primary reason, ratings, recommend/rejoin, status; anonymous rows un-attributed.",
        "tags": [
          "exit",
          "exit_feedback"
        ],
        "x-token": "exit.exit_feedback.list_admin",
        "x-realizes-features": [
          "EXT-F03"
        ],
        "x-screens": [
          "EXT-S07"
        ],
        "x-touches-entities": [
          "exit.exit_feedback"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/FeedbackStatus"
            }
          },
          {
            "name": "primary_reason",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ResignationReason"
            }
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PageBefore"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort whitelist: `submitted_at`, `-submitted_at`, `status`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-wide page of exit feedback.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitFeedbackPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/exit-feedback/{id}": {
      "get": {
        "operationId": "exit.exit_feedback.get_admin",
        "summary": "Get exit feedback (HR review detail)",
        "description": "The `EXT-S07` detail review — full ratings/comments; respondent null when anonymous.",
        "tags": [
          "exit",
          "exit_feedback"
        ],
        "x-token": "exit.exit_feedback.get_admin",
        "x-realizes-features": [
          "EXT-F03"
        ],
        "x-screens": [
          "EXT-S07"
        ],
        "x-touches-entities": [
          "exit.exit_feedback"
        ],
        "x-idempotent": false,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": null,
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          }
        ],
        "responses": {
          "200": {
            "description": "The feedback submission.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitFeedback"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/exit-feedback/{id}/review": {
      "post": {
        "operationId": "exit.exit_feedback.review",
        "summary": "Mark exit feedback reviewed (HR)",
        "description": "`SUBMITTED → REVIEWED` (`EXT-S07` \"Review\"). Confidential, HR-only handling; audited (`XC-F06`).",
        "tags": [
          "exit",
          "exit_feedback"
        ],
        "x-token": "exit.exit_feedback.review",
        "x-realizes-features": [
          "EXT-F03"
        ],
        "x-screens": [
          "EXT-S07"
        ],
        "x-touches-entities": [
          "exit.exit_feedback"
        ],
        "x-idempotent": true,
        "x-market": "both",
        "x-sync-async": "sync",
        "x-emits-event": "exit.exit_feedback.reviewed",
        "x-rls-scope": "tenant",
        "x-append-only": false,
        "x-entitlement": null,
        "x-provisional": null,
        "parameters": [
          {
            "$ref": "#/components/parameters/PathId"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "$ref": "#/components/parameters/IfMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "Marked reviewed.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExitFeedback"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/PreconditionFailed"
          },
          "423": {
            "$ref": "#/components/responses/Locked"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerJWT": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Product session token. Two mint paths, one contract (ADR 0010): employees/managers authenticate against Keycloak (mobile + web); workspace staff arrive from the One portal via bridge-token SSO (`POST /api/sso/exchange` verifies the platform's Ed25519 token and mints the product session). The token carries IDENTITY ONLY — `sub`, `tenantUid`, `principal_class`, MFA level, session ref, `exp`. Roles/permissions are re-resolved server-side per request. Enforcement is layered: gateway (TLS/WAF/routing only — NEVER trusted for auth) → NestJS auth guard (validates token, builds the request auth-context) → entitlement middleware (subscription-status → feature-flag → numeric-limit, ADR 0009) → `SET LOCAL app.tenant_id` / `app.user_id` → Postgres FORCED RLS. `tenantUid` is NEVER a path, query, or body parameter.\n"
      }
    },
    "schemas": {
      "UuidRef": {
        "$ref": "#/components/schemas/Uuid"
      },
      "DateOnlyRef": {
        "$ref": "#/components/schemas/DateOnly"
      },
      "TimestampRef": {
        "$ref": "#/components/schemas/Timestamp"
      },
      "RateRef": {
        "$ref": "#/components/schemas/Rate"
      },
      "MoneyRef": {
        "$ref": "#/components/schemas/Money"
      },
      "CurrencyCodeRef": {
        "$ref": "#/components/schemas/CurrencyCode"
      },
      "BusinessNoRef": {
        "$ref": "#/components/schemas/BusinessNo"
      },
      "LocalizedTextRef": {
        "$ref": "#/components/schemas/LocalizedText"
      },
      "FileDownloadRef": {
        "$ref": "#/components/schemas/FileDownload"
      },
      "AuditMetaRef": {
        "$ref": "#/components/schemas/AuditMeta"
      },
      "AppendOnlyMetaRef": {
        "$ref": "#/components/schemas/AppendOnlyMeta"
      },
      "CursorPageRef": {
        "$ref": "#/components/schemas/CursorPage"
      },
      "DecisionNoteInput": {
        "type": "object",
        "description": "Generic optional free-text decision body shared by approve/reject/cancel/submit actions in this file. None of `engage.referral_payouts` / `rnr_nominations` / `promotions` / `salary_revisions` / `exit.resignations` carries a `decision_note` column (db 11) — when supplied, this is recorded on the approval envelope (`xc.approval_inbox`, `XC-F12`), not a column on the module's own entity.\n",
        "additionalProperties": false,
        "properties": {
          "decision_note": {
            "type": "string"
          }
        }
      },
      "ReferralChannel": {
        "type": "string",
        "enum": [
          "DIRECT",
          "SHARE_LINK",
          "ALUMNI"
        ],
        "description": "engage.referral_channel (db 11 §1.1)."
      },
      "ReferralStatus": {
        "type": "string",
        "enum": [
          "SUBMITTED",
          "IN_REVIEW",
          "IN_PIPELINE",
          "HIRED",
          "PAYOUT_DUE",
          "PAID",
          "REJECTED",
          "EXPIRED",
          "WITHDRAWN"
        ],
        "description": "referrals.status lifecycle (db 11 §1.1)."
      },
      "ReferralPipelineStage": {
        "type": "string",
        "enum": [
          "SUBMITTED",
          "SCREENING",
          "INTERVIEW",
          "OFFER",
          "HIRED",
          "RETENTION",
          "REJECTED"
        ],
        "description": "engage.referral_pipeline_stage — referral_status.stage (db 11 §1.1)."
      },
      "ReferralPayoutMilestone": {
        "type": "string",
        "enum": [
          "ON_JOIN",
          "POST_PROBATION",
          "RETENTION_6M",
          "RETENTION_12M"
        ],
        "description": "engage.referral_payout_milestone (db 11 §1.1)."
      },
      "ReferralPayoutStatus": {
        "type": "string",
        "enum": [
          "PENDING",
          "ELIGIBLE",
          "PENDING_APPROVAL",
          "APPROVED",
          "REJECTED",
          "PAID",
          "ON_HOLD",
          "CANCELLED"
        ],
        "description": "referral_payouts.status lifecycle (db 11 §1.1)."
      },
      "ShareChannel": {
        "type": "string",
        "enum": [
          "COPY",
          "WHATSAPP",
          "EMAIL",
          "LINKEDIN",
          "SMS"
        ],
        "description": "engage.share_channel (db 11 §1.1)."
      },
      "ShareLinkStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "EXPIRED",
          "REVOKED",
          "CONSUMED"
        ],
        "description": "share_links.status lifecycle (db 11 §1.1)."
      },
      "AlumniExitType": {
        "type": "string",
        "enum": [
          "RESIGNATION",
          "RETIREMENT",
          "TERMINATION",
          "END_OF_CONTRACT"
        ],
        "description": "engage.alumni_exit_type (db 11 §1.2)."
      },
      "RehireEligibility": {
        "type": "string",
        "enum": [
          "ELIGIBLE",
          "NOT_ELIGIBLE",
          "CONDITIONAL",
          "UNDER_REVIEW"
        ],
        "description": "engage.rehire_eligibility (db 11 §1.2)."
      },
      "AlumniConsent": {
        "type": "string",
        "enum": [
          "OPTED_IN",
          "OPTED_OUT",
          "PENDING"
        ],
        "description": "engage.alumni_consent (db 11 §1.2)."
      },
      "AlumniStatus": {
        "type": "string",
        "enum": [
          "INVITED",
          "ACTIVE",
          "OPTED_OUT",
          "REHIRED",
          "INACTIVE"
        ],
        "description": "alumni_network.status lifecycle (db 11 §1.2)."
      },
      "RehireStatus": {
        "type": "string",
        "enum": [
          "EXPRESSED",
          "UNDER_REVIEW",
          "SHORTLISTED",
          "FORWARDED_TO_RECRUIT",
          "REJECTED",
          "WITHDRAWN"
        ],
        "description": "engage.rehire_status — rehire_requests.status lifecycle (db 11 §1.2)."
      },
      "RnrAwardType": {
        "type": "string",
        "enum": [
          "PEER_TO_PEER",
          "MANAGER",
          "SPOT",
          "VALUE_BASED",
          "MILESTONE"
        ],
        "description": "engage.rnr_award_type (db 11 §1.3)."
      },
      "RnrPeriodicity": {
        "type": "string",
        "enum": [
          "CONTINUOUS",
          "MONTHLY",
          "QUARTERLY",
          "ANNUAL"
        ],
        "description": "engage.rnr_periodicity (db 11 §1.3)."
      },
      "RnrCategoryStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "INACTIVE"
        ],
        "description": "rnr_categories.status (db 11 §1.3)."
      },
      "NominationStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "SUBMITTED",
          "PENDING_APPROVAL",
          "APPROVED",
          "REJECTED",
          "AWARDED",
          "WITHDRAWN"
        ],
        "description": "engage.nomination_status — rnr_nominations.status lifecycle (db 11 §1.3)."
      },
      "CelebrationOccasion": {
        "type": "string",
        "enum": [
          "BIRTHDAY",
          "WORK_ANNIVERSARY"
        ],
        "description": "engage.celebration_occasion (db 11 §1.4)."
      },
      "AnnouncementAudience": {
        "type": "string",
        "enum": [
          "ORG_WIDE",
          "LEGAL_ENTITY",
          "LOCATION",
          "DEPARTMENT",
          "GRADE",
          "CUSTOM"
        ],
        "description": "engage.announcement_audience (db 11 §1.4)."
      },
      "AnnouncementCategory": {
        "type": "string",
        "enum": [
          "GENERAL",
          "POLICY",
          "EVENT",
          "HOLIDAY",
          "CELEBRATION",
          "URGENT"
        ],
        "description": "engage.announcement_category (db 11 §1.4)."
      },
      "AnnouncementPriority": {
        "type": "string",
        "enum": [
          "NORMAL",
          "IMPORTANT",
          "CRITICAL"
        ],
        "description": "announcements.priority (db 11 §1.4)."
      },
      "AnnouncementStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "SCHEDULED",
          "PUBLISHED",
          "EXPIRED",
          "ARCHIVED"
        ],
        "description": "engage.announcement_status — announcements.status lifecycle (db 11 §1.4)."
      },
      "AnnouncementReadEvent": {
        "type": "string",
        "enum": [
          "READ",
          "ACKNOWLEDGED"
        ],
        "description": "engage.announcement_read_event (db 11 §1.4)."
      },
      "AnnouncementReadChannel": {
        "type": "string",
        "enum": [
          "WEB",
          "MOBILE",
          "PUSH"
        ],
        "description": "announcement_reads.channel (db 11 §1.4)."
      },
      "PromotionType": {
        "type": "string",
        "enum": [
          "PROMOTION",
          "LATERAL",
          "ROLE_CHANGE"
        ],
        "description": "engage.promotion_type (db 11 §1.5)."
      },
      "CareerChangeSource": {
        "type": "string",
        "enum": [
          "CALIBRATION",
          "APPRAISAL",
          "MANUAL"
        ],
        "description": "engage.career_change_source — shared by promotions.source and salary_revisions.source (db 11 §1.5)."
      },
      "PromotionStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "PENDING_APPROVAL",
          "APPROVED",
          "REJECTED",
          "SCHEDULED",
          "EFFECTED",
          "CANCELLED"
        ],
        "description": "engage.promotion_status lifecycle (db 11 §1.5)."
      },
      "SalaryRevisionType": {
        "type": "string",
        "enum": [
          "INCREMENT",
          "PROMOTION_LINKED",
          "MARKET_CORRECTION",
          "RETENTION",
          "DEMOTION"
        ],
        "description": "engage.salary_revision_type (db 11 §1.5)."
      },
      "SalaryRevisionStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "PENDING_APPROVAL",
          "APPROVED",
          "REJECTED",
          "SCHEDULED",
          "EFFECTED",
          "CANCELLED"
        ],
        "description": "engage.salary_revision_status lifecycle (db 11 §1.5)."
      },
      "ResignationStep": {
        "type": "string",
        "enum": [
          "INTENT",
          "NOTICE",
          "REVIEW"
        ],
        "description": "exit.resignation_step — resignations.wizard_step (db 11 §2.1); the 3 visual wizard steps (Details/Review/Confirm) map Details→{INTENT+NOTICE}, Review+Confirm→REVIEW (fsd 10 §1.3)."
      },
      "ResignationReason": {
        "type": "string",
        "enum": [
          "BETTER_OPPORTUNITY",
          "COMPENSATION",
          "RELOCATION",
          "HIGHER_STUDIES",
          "PERSONAL",
          "HEALTH",
          "WORK_ENVIRONMENT",
          "CAREER_CHANGE",
          "RETIREMENT",
          "OTHER"
        ],
        "description": "exit.resignation_reason — shared by resignations.reason and exit_feedback.primary_reason (db 11 §2.1/§2.3)."
      },
      "ResignationStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "SUBMITTED",
          "PENDING_APPROVAL",
          "APPROVED",
          "REJECTED",
          "WITHDRAWN",
          "CLEARANCE_IN_PROGRESS",
          "SETTLED",
          "COMPLETED"
        ],
        "description": "exit.resignation_status lifecycle (db 11 §2.1)."
      },
      "ClearanceStatus": {
        "type": "string",
        "enum": [
          "INITIATED",
          "IN_PROGRESS",
          "PENDING_DUES",
          "CLEARED",
          "BLOCKED",
          "CANCELLED"
        ],
        "description": "exit.clearance_status — exit_clearances.status lifecycle (db 11 §2.2)."
      },
      "ClearanceDepartment": {
        "type": "string",
        "enum": [
          "IT",
          "FINANCE",
          "ADMIN",
          "HR",
          "MANAGER"
        ],
        "description": "exit.clearance_department (db 11 §2.2)."
      },
      "NoDuesStatus": {
        "type": "string",
        "enum": [
          "PENDING",
          "IN_PROGRESS",
          "CLEARED",
          "DUES_PENDING",
          "WAIVED"
        ],
        "description": "exit.no_dues_status lifecycle (db 11 §2.2)."
      },
      "FeedbackChannel": {
        "type": "string",
        "enum": [
          "SELF_SERVE",
          "INTERVIEW"
        ],
        "description": "exit.feedback_channel — exit_feedback.conducted_via (db 11 §2.3)."
      },
      "FeedbackStatus": {
        "type": "string",
        "enum": [
          "PENDING",
          "SUBMITTED",
          "REVIEWED"
        ],
        "description": "exit.feedback_status — exit_feedback.status lifecycle (db 11 §2.3)."
      },
      "ReferralCreate": {
        "type": "object",
        "description": "ENG-S02 Refer-a-candidate form input → `engage.referrals`.",
        "required": [
          "referee_name"
        ],
        "additionalProperties": false,
        "properties": {
          "job_opening_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "null = general talent referral."
          },
          "referee_name": {
            "type": "string"
          },
          "referee_email": {
            "type": [
              "string",
              "null"
            ],
            "description": "One of email/phone required (feeds `dedupe_key`)."
          },
          "referee_phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "relationship": {
            "type": [
              "string",
              "null"
            ]
          },
          "resume_file_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Pre-uploaded object-storage handle (XC-F07) resolving to `resume_storage_key`/`resume_content_hash`."
          },
          "is_alumni_referral": {
            "type": "boolean",
            "default": false
          },
          "alumni_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Required when `is_alumni_referral` (the alumnus who referred, reached from ENG-S04)."
          }
        }
      },
      "Referral": {
        "description": "engage.referrals — the referral master record (db 11 §1.1).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "referral_no",
              "referrer_employee_id",
              "is_alumni_referral",
              "referee_name",
              "channel",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "referral_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "referrer_employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "referrer_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection (not a join)."
              },
              "is_alumni_referral": {
                "type": "boolean"
              },
              "alumni_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "job_opening_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "job_opening_title": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→recruit.job_openings, by projection — never a join (fsd 10 ENG-S01)."
              },
              "candidate_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Set once the referral lands in the recruit pipeline (REC-F03)."
              },
              "referee_name": {
                "type": "string"
              },
              "referee_email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "referee_phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "resume": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/FileDownloadRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "relationship": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "channel": {
                "$ref": "#/components/schemas/ReferralChannel"
              },
              "status": {
                "$ref": "#/components/schemas/ReferralStatus"
              },
              "submitted_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ReferralPipelineStep": {
        "type": "object",
        "description": "engage.referral_status row — a projected pipeline-stage transition (db 11 §1.1). Read-only; projected from `recruit.candidate.stage_changed`, never a join.",
        "properties": {
          "stage": {
            "$ref": "#/components/schemas/ReferralPipelineStage"
          },
          "is_current": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "enum": [
              "EVENT",
              "MANUAL"
            ]
          },
          "effective_at": {
            "$ref": "#/components/schemas/TimestampRef"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ReferralDetail": {
        "description": "ENG-S03 referral detail — the referral plus its pipeline timeline, payouts, and share link.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Referral"
          },
          {
            "type": "object",
            "properties": {
              "pipeline_history": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReferralPipelineStep"
                }
              },
              "payouts": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              },
              "share_link": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/ShareLink"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "ReferralPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Referral"
                }
              }
            }
          }
        ]
      },
      "ReferralLeaderboardEntry": {
        "type": "object",
        "description": "One ranked row of the referral leaderboard (fsd 10 ENG-S01/ENG-S11) — grouped `referrals` by `referrer_employee_id`, no cross-schema join.",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "referrer_employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "referrer_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "ref→people.employees, by projection."
          },
          "hired_count": {
            "type": "integer"
          },
          "paid_count": {
            "type": "integer"
          },
          "is_self": {
            "type": "boolean",
            "description": "Flags the caller's own row."
          }
        }
      },
      "ReferralLeaderboardPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReferralLeaderboardEntry"
                }
              }
            }
          }
        ]
      },
      "ShareLinkCreate": {
        "type": "object",
        "description": "ENG-S02 \"Share a link\" sheet input → `engage.share_links`.",
        "required": [
          "channel"
        ],
        "additionalProperties": false,
        "properties": {
          "job_opening_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "channel": {
            "$ref": "#/components/schemas/ShareChannel"
          },
          "max_uses": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "ShareLink": {
        "description": "engage.share_links — a scoped, expiring referral share link (db 11 §1.1).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "referrer_employee_id",
              "token",
              "channel",
              "status",
              "use_count"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "referral_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "referrer_employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "referrer_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "job_opening_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "job_opening_title": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→recruit.job_openings, by projection."
              },
              "token": {
                "type": "string"
              },
              "channel": {
                "$ref": "#/components/schemas/ShareChannel"
              },
              "status": {
                "$ref": "#/components/schemas/ShareLinkStatus"
              },
              "expires_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "max_uses": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "use_count": {
                "type": "integer"
              },
              "last_used_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ShareLinkPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ShareLink"
                }
              }
            }
          }
        ]
      },
      "ReferralPayoutHoldInput": {
        "type": "object",
        "required": [
          "hold_reason"
        ],
        "additionalProperties": false,
        "properties": {
          "hold_reason": {
            "type": "string"
          }
        }
      },
      "ReferralPayout": {
        "description": "engage.referral_payouts — one milestone-gated bonus instalment (db 11 §1.1).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "referral_id",
              "milestone",
              "payout_amount",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "referral_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "milestone": {
                "$ref": "#/components/schemas/ReferralPayoutMilestone"
              },
              "payout_amount": {
                "$ref": "#/components/schemas/MoneyRef"
              },
              "eligible_on": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DateOnlyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "$ref": "#/components/schemas/ReferralPayoutStatus"
              },
              "submitted_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "pay_disbursement_ref": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Soft `ref→pay` posting id (PAY-F04)."
              },
              "payslip_ref": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "ref→pay.payslips — back-filled on disbursement."
              },
              "paid_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "hold_reason": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ReferralPayoutPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ReferralPayout"
                }
              }
            }
          }
        ]
      },
      "AlumniProfileUpdateAdmin": {
        "type": "object",
        "description": "ENG-S12 eligibility/doc-access editor input.",
        "additionalProperties": false,
        "properties": {
          "rehire_eligibility": {
            "$ref": "#/components/schemas/RehireEligibility"
          },
          "document_access_until": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DateOnlyRef"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "AlumniProfile": {
        "description": "engage.alumni_network — the post-exit alumni profile (db 11 §1.2).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "alumni_no",
              "employee_id",
              "separation_date",
              "exit_type",
              "rehire_eligibility",
              "consent_status",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "alumni_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "separation_date": {
                "$ref": "#/components/schemas/DateOnlyRef"
              },
              "exit_type": {
                "$ref": "#/components/schemas/AlumniExitType"
              },
              "rehire_eligibility": {
                "$ref": "#/components/schemas/RehireEligibility"
              },
              "personal_email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "personal_phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "consent_status": {
                "$ref": "#/components/schemas/AlumniConsent"
              },
              "consent_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "opted_out_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "document_access_until": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DateOnlyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "$ref": "#/components/schemas/AlumniStatus"
              },
              "last_designation": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "AlumniProfilePage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AlumniProfile"
                }
              }
            }
          }
        ]
      },
      "RehireRequestCreate": {
        "type": "object",
        "description": "ENG-S05 \"Express Interest\" input → `engage.rehire_requests`.",
        "additionalProperties": false,
        "properties": {
          "job_opening_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "null = general interest."
          },
          "interest_note": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "RehireRequestDecisionInput": {
        "type": "object",
        "description": "Shared by `.withdraw` (alumnus) and `.reject` (HR) — maps to `rehire_requests.decision_reason` (db 11 §1.2).",
        "additionalProperties": false,
        "properties": {
          "decision_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "RehireRequest": {
        "description": "engage.rehire_requests — an alumnus's expression of rehire interest (db 11 §1.2).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "alumni_id",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "alumni_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "job_opening_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "job_opening_title": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→recruit.job_openings, by projection."
              },
              "candidate_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Set when forwarded into the pipeline (REC-F03)."
              },
              "status": {
                "$ref": "#/components/schemas/RehireStatus"
              },
              "interest_note": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "reviewed_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "reviewed_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "forwarded_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "decision_reason": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "RehireRequestPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RehireRequest"
                }
              }
            }
          }
        ]
      },
      "RnrCategoryCreate": {
        "type": "object",
        "description": "ENG-S09 \"Award Categories\" create modal input → `engage.rnr_categories`.",
        "required": [
          "category_code",
          "name",
          "award_type"
        ],
        "additionalProperties": false,
        "properties": {
          "category_code": {
            "type": "string"
          },
          "name": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "award_type": {
            "$ref": "#/components/schemas/RnrAwardType"
          },
          "is_monetary": {
            "type": "boolean",
            "default": false
          },
          "award_amount": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MoneyRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Required when `is_monetary`."
          },
          "requires_approval": {
            "type": "boolean",
            "default": true
          },
          "periodicity": {
            "$ref": "#/components/schemas/RnrPeriodicity"
          },
          "badge_icon_file_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "max_nominations_per_period": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "RnrCategoryUpdate": {
        "type": "object",
        "description": "ENG-S09 edit modal input.",
        "additionalProperties": false,
        "properties": {
          "name": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "is_monetary": {
            "type": "boolean"
          },
          "award_amount": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MoneyRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "requires_approval": {
            "type": "boolean"
          },
          "periodicity": {
            "$ref": "#/components/schemas/RnrPeriodicity"
          },
          "badge_icon_file_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "max_nominations_per_period": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "status": {
            "$ref": "#/components/schemas/RnrCategoryStatus"
          }
        }
      },
      "RnrCategory": {
        "description": "engage.rnr_categories — an HR-configured award category (db 11 §1.3).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "category_code",
              "name",
              "award_type",
              "is_monetary",
              "requires_approval",
              "periodicity",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "category_code": {
                "type": "string"
              },
              "name": {
                "$ref": "#/components/schemas/LocalizedTextRef"
              },
              "description": {
                "$ref": "#/components/schemas/LocalizedTextRef"
              },
              "award_type": {
                "$ref": "#/components/schemas/RnrAwardType"
              },
              "is_monetary": {
                "type": "boolean"
              },
              "award_amount": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/MoneyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "requires_approval": {
                "type": "boolean"
              },
              "periodicity": {
                "$ref": "#/components/schemas/RnrPeriodicity"
              },
              "badge_icon": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/FileDownloadRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "max_nominations_per_period": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "status": {
                "$ref": "#/components/schemas/RnrCategoryStatus"
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "RnrCategoryPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RnrCategory"
                }
              }
            }
          }
        ]
      },
      "RnrNominationCreate": {
        "type": "object",
        "description": "ENG-S06 \"Submit Nomination\" form input → `engage.rnr_nominations`.",
        "required": [
          "category_id",
          "nominee_employee_id",
          "citation"
        ],
        "additionalProperties": false,
        "properties": {
          "category_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "nominee_employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "citation": {
            "type": "string"
          }
        }
      },
      "RnrNomination": {
        "description": "engage.rnr_nominations — a recognition nomination (db 11 §1.3).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "nomination_no",
              "category_id",
              "nominee_employee_id",
              "nominator_employee_id",
              "citation",
              "status",
              "is_announced"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "nomination_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "category_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "category_name": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/LocalizedTextRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "ref→engage.rnr_categories, by projection."
              },
              "nominee_employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "nominee_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "nominator_employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "nominator_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "citation": {
                "type": "string"
              },
              "status": {
                "$ref": "#/components/schemas/NominationStatus"
              },
              "approved_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "award_amount": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/MoneyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "pay_disbursement_ref": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Soft `ref→pay` posting id (PAY-F04)."
              },
              "awarded_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "is_announced": {
                "type": "boolean"
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "RnrNominationPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RnrNomination"
                }
              }
            }
          }
        ]
      },
      "RnrLeaderboardEntry": {
        "type": "object",
        "description": "One ranked row of the recognition leaderboard (fsd 10 ENG-S09) — grouped `rnr_nominations` by `nominee_employee_id`.",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "nominee_employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "nominee_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "ref→people.employees, by projection."
          },
          "award_count": {
            "type": "integer"
          }
        }
      },
      "RnrLeaderboardPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RnrLeaderboardEntry"
                }
              }
            }
          }
        ]
      },
      "CelebrationWishCreate": {
        "type": "object",
        "description": "ENG-S07 \"Send\" (top-level wish) / \"Reply\" (thanks) input → `engage.celebration_wishes`.",
        "required": [
          "subject_employee_id",
          "message"
        ],
        "additionalProperties": false,
        "properties": {
          "subject_employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "occasion": {
            "$ref": "#/components/schemas/CelebrationOccasion"
          },
          "occasion_date": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DateOnlyRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Derived server-side from the subject's birth/join-date when omitted."
          },
          "message": {
            "type": "string"
          },
          "parent_wish_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "null = a top-level wish; set = a reply to that (top-level) wish."
          }
        }
      },
      "CelebrationWish": {
        "description": "engage.celebration_wishes — a peer birthday/anniversary wish or reply (db 11 §1.4).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "subject_employee_id",
              "occasion",
              "occasion_date",
              "wisher_employee_id",
              "message",
              "occurred_at"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "subject_employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "subject_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "occasion": {
                "$ref": "#/components/schemas/CelebrationOccasion"
              },
              "occasion_date": {
                "$ref": "#/components/schemas/DateOnlyRef"
              },
              "wisher_employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "wisher_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "message": {
                "type": "string"
              },
              "parent_wish_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "occurred_at": {
                "$ref": "#/components/schemas/TimestampRef"
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "CelebrationWishPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CelebrationWish"
                }
              }
            }
          }
        ]
      },
      "AnnouncementAudienceFilter": {
        "type": "object",
        "description": "announcements.audience_filter JSONB shape (db 11 §1.4) — evaluated by the feed service, never a cross-schema join.",
        "additionalProperties": false,
        "properties": {
          "legal_entity_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          "location_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          "department_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UuidRef"
            }
          },
          "grade_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UuidRef"
            }
          }
        }
      },
      "AnnouncementAttachmentInput": {
        "type": "object",
        "required": [
          "file_id"
        ],
        "additionalProperties": false,
        "properties": {
          "file_id": {
            "$ref": "#/components/schemas/UuidRef"
          }
        }
      },
      "AnnouncementCreate": {
        "type": "object",
        "description": "ENG-S10 compose wizard input → `engage.announcements`.",
        "required": [
          "title",
          "body",
          "audience_type",
          "category"
        ],
        "additionalProperties": false,
        "properties": {
          "title": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "body": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "legal_entity_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "null = whole tenant."
          },
          "audience_type": {
            "$ref": "#/components/schemas/AnnouncementAudience"
          },
          "audience_filter": {
            "$ref": "#/components/schemas/AnnouncementAudienceFilter"
          },
          "category": {
            "$ref": "#/components/schemas/AnnouncementCategory"
          },
          "priority": {
            "$ref": "#/components/schemas/AnnouncementPriority"
          },
          "requires_acknowledgement": {
            "type": "boolean",
            "default": false
          },
          "is_pinned": {
            "type": "boolean",
            "default": false
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AnnouncementAttachmentInput"
            }
          },
          "publish_at": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TimestampRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Sets `status='SCHEDULED'`; omit for `DRAFT`."
          },
          "expires_at": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TimestampRef"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "AnnouncementUpdate": {
        "type": "object",
        "description": "ENG-S10 edit input — same shape as create, all fields optional.",
        "additionalProperties": false,
        "properties": {
          "title": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "body": {
            "$ref": "#/components/schemas/LocalizedTextRef"
          },
          "legal_entity_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "audience_type": {
            "$ref": "#/components/schemas/AnnouncementAudience"
          },
          "audience_filter": {
            "$ref": "#/components/schemas/AnnouncementAudienceFilter"
          },
          "category": {
            "$ref": "#/components/schemas/AnnouncementCategory"
          },
          "priority": {
            "$ref": "#/components/schemas/AnnouncementPriority"
          },
          "requires_acknowledgement": {
            "type": "boolean"
          },
          "is_pinned": {
            "type": "boolean"
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AnnouncementAttachmentInput"
            }
          },
          "publish_at": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TimestampRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "expires_at": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TimestampRef"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "AnnouncementReadCreate": {
        "type": "object",
        "required": [
          "event_type",
          "channel"
        ],
        "additionalProperties": false,
        "properties": {
          "event_type": {
            "$ref": "#/components/schemas/AnnouncementReadEvent"
          },
          "channel": {
            "$ref": "#/components/schemas/AnnouncementReadChannel"
          }
        }
      },
      "AnnouncementRead": {
        "description": "engage.announcement_reads — Immutable read/acknowledgement receipt (db 11 §1.4).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "announcement_id",
              "employee_id",
              "event_type",
              "channel",
              "occurred_at"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "announcement_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "event_type": {
                "$ref": "#/components/schemas/AnnouncementReadEvent"
              },
              "channel": {
                "$ref": "#/components/schemas/AnnouncementReadChannel"
              },
              "occurred_at": {
                "$ref": "#/components/schemas/TimestampRef"
              }
            }
          },
          {
            "$ref": "#/components/schemas/AppendOnlyMetaRef"
          }
        ]
      },
      "Announcement": {
        "description": "engage.announcements — a broadcast notice, the employee-facing feed shape (db 11 §1.4).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "announcement_no",
              "title",
              "body",
              "audience_type",
              "category",
              "priority",
              "requires_acknowledgement",
              "is_pinned",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "announcement_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "title": {
                "$ref": "#/components/schemas/LocalizedTextRef"
              },
              "body": {
                "$ref": "#/components/schemas/LocalizedTextRef"
              },
              "audience_type": {
                "$ref": "#/components/schemas/AnnouncementAudience"
              },
              "category": {
                "$ref": "#/components/schemas/AnnouncementCategory"
              },
              "priority": {
                "$ref": "#/components/schemas/AnnouncementPriority"
              },
              "requires_acknowledgement": {
                "type": "boolean"
              },
              "is_pinned": {
                "type": "boolean"
              },
              "status": {
                "$ref": "#/components/schemas/AnnouncementStatus"
              },
              "attachments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FileDownloadRef"
                }
              },
              "published_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expires_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "my_read_status": {
                "type": "object",
                "description": "Derived from the caller's own `announcement_reads` rows — drives the ENG-S08 unread badge / Acknowledge CTA.",
                "properties": {
                  "read_at": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/TimestampRef"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "acknowledged_at": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/TimestampRef"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "AnnouncementPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Announcement"
                }
              }
            }
          }
        ]
      },
      "AnnouncementAdmin": {
        "description": "ENG-S10 admin shape — the announcement plus targeting config and the read/ack rollup.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Announcement"
          },
          {
            "type": "object",
            "properties": {
              "legal_entity_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "audience_filter": {
                "$ref": "#/components/schemas/AnnouncementAudienceFilter"
              },
              "publish_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "published_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "published_by_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "target_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Approximate audience size (rollup denominator)."
              },
              "read_count": {
                "type": "integer",
                "description": "Count of `announcement_reads` where `event_type='READ'`."
              },
              "acknowledged_count": {
                "type": "integer",
                "description": "Count of `announcement_reads` where `event_type='ACKNOWLEDGED'`."
              }
            }
          }
        ]
      },
      "AnnouncementAdminPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AnnouncementAdmin"
                }
              }
            }
          }
        ]
      },
      "PromotionCreate": {
        "type": "object",
        "description": "ENG-S13 propose-promotion input → `engage.promotions`.",
        "required": [
          "employee_id",
          "promotion_type",
          "to_designation_id",
          "effective_date"
        ],
        "additionalProperties": false,
        "properties": {
          "employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "promotion_type": {
            "$ref": "#/components/schemas/PromotionType"
          },
          "to_designation_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "to_grade_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "to_org_unit_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "effective_date": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "source": {
            "$ref": "#/components/schemas/CareerChangeSource"
          },
          "calibration_ref": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Required when `source='CALIBRATION'` (db 11 §1.5 check)."
          },
          "justification": {
            "type": [
              "string",
              "null"
            ]
          },
          "submit": {
            "type": "boolean",
            "default": false,
            "description": "true ⇒ `DRAFT → PENDING_APPROVAL` atomically."
          },
          "salary_revision": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PromotionSalaryRevisionInput"
              },
              {
                "type": "null"
              }
            ],
            "description": "The pay change this promotion carries, written as the linked `engage.salary_revisions` child (`revision_type='PROMOTION_LINKED'`, `promotion_id` set). Omit for a promotion with no pay change. This is the link whose absence made a designation change and a salary change two unrelated edits; on `EFFECTED` it opens the `pay.employee_compensation` row with `revision_reason='PROMOTION'` in the SAME transaction as the placement change.\n"
          }
        }
      },
      "PromotionSalaryRevisionInput": {
        "type": "object",
        "description": "The revised figures only. `current_ctc_amount` is read from the employee's OPEN `pay.employee_compensation` row, never taken from the caller — an increment computed against a number the client supplied is an increment against a number nobody verified — and `currency_code` comes from their legal entity, the same rule `pay.employee_compensation.create` enforces.\n",
        "required": [
          "revised_ctc_amount",
          "revised_basic_amount"
        ],
        "additionalProperties": false,
        "properties": {
          "revised_ctc_amount": {
            "$ref": "#/components/schemas/MoneyRef"
          },
          "revised_basic_amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MoneyRef"
              }
            ],
            "description": "Required, and not in db 11 §1.5's original column list: on effect this opens a `pay.employee_compensation` row, and `employee_compensation_monthly_amounts_present` requires BOTH amounts for a `MONTHLY_SALARY` record. A revision that could not state the revised basic would have to invent one at the moment of writing someone's pay.\n"
          },
          "pay_structure_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Defaults to the structure the open compensation row is already bound to."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PromotionUpdate": {
        "type": "object",
        "description": "ENG-S13 edit-while-DRAFT input.",
        "additionalProperties": false,
        "properties": {
          "to_designation_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "to_grade_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "to_org_unit_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "effective_date": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "justification": {
            "type": [
              "string",
              "null"
            ]
          },
          "submit": {
            "type": "boolean",
            "default": false,
            "description": "true ⇒ `DRAFT → PENDING_APPROVAL` atomically."
          }
        }
      },
      "Promotion": {
        "description": "engage.promotions — a grade/designation change proposal (db 11 §1.5).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "promotion_no",
              "employee_id",
              "promotion_type",
              "to_designation_id",
              "effective_date",
              "source",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "promotion_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "promotion_type": {
                "$ref": "#/components/schemas/PromotionType"
              },
              "from_designation_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "from_designation_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→org.designations, by projection."
              },
              "to_designation_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "to_designation_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→org.designations, by projection."
              },
              "from_grade_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "to_grade_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "from_org_unit_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "to_org_unit_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "effective_date": {
                "$ref": "#/components/schemas/DateOnlyRef"
              },
              "source": {
                "$ref": "#/components/schemas/CareerChangeSource"
              },
              "calibration_ref": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "$ref": "#/components/schemas/PromotionStatus"
              },
              "submitted_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "letter_ref": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "ref→docs.letters (DOC-F03)."
              },
              "effected_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "justification": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "decision_note": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The approver's / canceller's note."
              },
              "from_grade_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→org.grades, by projection."
              },
              "to_grade_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→org.grades, by projection."
              },
              "from_org_unit_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→org.org_units, by projection."
              },
              "to_org_unit_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→org.org_units, by projection."
              },
              "employee_no": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "salary_revision": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/PromotionSalaryRevision"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The linked `engage.salary_revisions` child, or null when the promotion carries no pay change."
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "PromotionSalaryRevision": {
        "type": "object",
        "description": "The linked revision as the ENG-S13 drawer renders it. Money is `numeric(18,2)` on the wire — decimal STRINGS, never floats (db 00 §6).\n",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "revision_no": {
            "$ref": "#/components/schemas/BusinessNoRef"
          },
          "employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "promotion_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "revision_type": {
            "$ref": "#/components/schemas/SalaryRevisionType"
          },
          "current_ctc_amount": {
            "$ref": "#/components/schemas/MoneyRef"
          },
          "revised_ctc_amount": {
            "$ref": "#/components/schemas/MoneyRef"
          },
          "increment_amount": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MoneyRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "increment_pct": {
            "type": [
              "string",
              "null"
            ],
            "description": "Fraction, e.g. `0.120000` = 12%."
          },
          "currency_code": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3
          },
          "effective_date": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "fiscal_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/SalaryRevisionStatus"
          },
          "effected_at": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TimestampRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "compensation_ref": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "ref→pay.employee_compensation — the row this revision opened on effect."
          },
          "version": {
            "type": "integer"
          }
        }
      },
      "PromotionPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Promotion"
                }
              }
            }
          }
        ]
      },
      "SalaryRevisionCreate": {
        "type": "object",
        "description": "ENG-S13 propose-revision input → `engage.salary_revisions`.",
        "required": [
          "employee_id",
          "revision_type",
          "current_ctc_amount",
          "revised_ctc_amount",
          "currency_code",
          "effective_date"
        ],
        "additionalProperties": false,
        "properties": {
          "employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "promotion_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "revision_type": {
            "$ref": "#/components/schemas/SalaryRevisionType"
          },
          "to_pay_structure_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "current_ctc_amount": {
            "type": "string",
            "pattern": "^-?\\d+(\\.\\d{1,2})?$"
          },
          "revised_ctc_amount": {
            "type": "string",
            "pattern": "^-?\\d+(\\.\\d{1,2})?$"
          },
          "increment_pct": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RateRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "currency_code": {
            "$ref": "#/components/schemas/CurrencyCodeRef"
          },
          "effective_date": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "fiscal_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/CareerChangeSource"
          },
          "calibration_ref": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "Required when `source='CALIBRATION'` (db 11 §1.5 check)."
          },
          "submit": {
            "type": "boolean",
            "default": false,
            "description": "true ⇒ `DRAFT → PENDING_APPROVAL` atomically."
          }
        }
      },
      "SalaryRevisionUpdate": {
        "type": "object",
        "description": "ENG-S13 edit-while-DRAFT input.",
        "additionalProperties": false,
        "properties": {
          "to_pay_structure_id": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UuidRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "revised_ctc_amount": {
            "type": "string",
            "pattern": "^-?\\d+(\\.\\d{1,2})?$"
          },
          "increment_pct": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RateRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "effective_date": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "fiscal_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "submit": {
            "type": "boolean",
            "default": false,
            "description": "true ⇒ `DRAFT → PENDING_APPROVAL` atomically."
          }
        }
      },
      "SalaryRevision": {
        "description": "engage.salary_revisions — a pay-revision proposal (db 11 §1.5).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "revision_no",
              "employee_id",
              "revision_type",
              "current_ctc_amount",
              "revised_ctc_amount",
              "currency_code",
              "effective_date",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "revision_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "promotion_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "revision_type": {
                "$ref": "#/components/schemas/SalaryRevisionType"
              },
              "from_pay_structure_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "to_pay_structure_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "current_ctc_amount": {
                "type": "string"
              },
              "revised_ctc_amount": {
                "type": "string"
              },
              "increment_amount": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "increment_pct": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/RateRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "currency_code": {
                "$ref": "#/components/schemas/CurrencyCodeRef"
              },
              "effective_date": {
                "$ref": "#/components/schemas/DateOnlyRef"
              },
              "fiscal_year": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "source": {
                "$ref": "#/components/schemas/CareerChangeSource"
              },
              "calibration_ref": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "$ref": "#/components/schemas/SalaryRevisionStatus"
              },
              "submitted_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "letter_ref": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "ref→docs.letters (DOC-F03)."
              },
              "effected_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "SalaryRevisionPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SalaryRevision"
                }
              }
            }
          }
        ]
      },
      "ResignationCreate": {
        "type": "object",
        "description": "EXT-S01 Step 1 \"Details\" input → `exit.resignations` (`wizard_step='NOTICE'`).",
        "additionalProperties": false,
        "properties": {
          "intended_last_working_day": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "is_notice_waived": {
            "type": "boolean",
            "default": false
          },
          "early_exit_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required when `is_notice_waived` (db 11 §2.1)."
          },
          "reason": {
            "$ref": "#/components/schemas/ResignationReason"
          },
          "reason_detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "alumni_opt_in": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "EXT-S01 Alumni Opt-In. **Persisted since #1543** on `exit.resignations.alumni_opt_in` (migration `0233`) — it was accepted and discarded before that, because `engage.alumni_network` had no migration. Three-valued and deliberately UNDEFAULTED: omitted (or `null`) is stored as NULL and means *never asked*, which is not consent and not a decline. Carried on the `exit.resignation.completed` envelope to `engage.alumni_network.consent_status` on separation `COMPLETED` (ENG-F02, fsd 10 EXT-S01)."
          }
        }
      },
      "ResignationUpdate": {
        "type": "object",
        "description": "EXT-S01 Step 2 \"Review\" input — edits Step-1 fields while `DRAFT`, or advances `wizard_step`.",
        "additionalProperties": false,
        "properties": {
          "intended_last_working_day": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "is_notice_waived": {
            "type": "boolean"
          },
          "early_exit_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "$ref": "#/components/schemas/ResignationReason"
          },
          "reason_detail": {
            "type": [
              "string",
              "null"
            ]
          },
          "alumni_opt_in": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "See `ResignationCreate.alumni_opt_in`. Three-valued; `null` means never recorded."
          },
          "wizard_step": {
            "$ref": "#/components/schemas/ResignationStep"
          }
        }
      },
      "ResignationCreateAdmin": {
        "type": "object",
        "description": "EXT-S05 \"+ Initiate Separation\" (involuntary) input.",
        "required": [
          "employee_id",
          "reason"
        ],
        "additionalProperties": false,
        "properties": {
          "employee_id": {
            "$ref": "#/components/schemas/UuidRef"
          },
          "intended_last_working_day": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "reason": {
            "$ref": "#/components/schemas/ResignationReason"
          },
          "reason_detail": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ResignationWithdrawInput": {
        "type": "object",
        "required": [
          "withdrawal_reason"
        ],
        "additionalProperties": false,
        "properties": {
          "withdrawal_reason": {
            "type": "string"
          }
        }
      },
      "ResignationApproveInput": {
        "type": "object",
        "required": [
          "approved_last_working_day"
        ],
        "additionalProperties": false,
        "properties": {
          "approved_last_working_day": {
            "$ref": "#/components/schemas/DateOnlyRef"
          },
          "decision_note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Recorded on the approval envelope (`xc.approval_inbox`), not a column on this table."
          }
        }
      },
      "Resignation": {
        "description": "exit.resignations — the voluntary-separation record (db 11 §2.1).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "resignation_no",
              "employee_id",
              "wizard_step",
              "is_notice_waived",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "resignation_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "manager_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "wizard_step": {
                "$ref": "#/components/schemas/ResignationStep"
              },
              "resignation_date": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DateOnlyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "intended_last_working_day": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DateOnlyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_last_working_day": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DateOnlyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "notice_period_days": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "notice_served_days": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "is_notice_waived": {
                "type": "boolean"
              },
              "notice_shortfall_days": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "early_exit_reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "reason": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/ResignationReason"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "reason_detail": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "esop_impact": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "A vesting-snapshot read from `pay` (PAY-F05) at Review — `{ vested_units, unvested_units, forfeited_units, exercisable_until, estimated_value, currency, as_of }` (db 11 §2.1). Display snapshot; live truth stays in `pay`."
              },
              "status": {
                "$ref": "#/components/schemas/ResignationStatus"
              },
              "submitted_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "approved_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "withdrawal_reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "alumni_opt_in": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "EXT-S01 Alumni Opt-In as the leaver answered it (migration `0233`, #1543). `null` = never recorded — every resignation filed before the column existed. Read back so `EXT-S02` can show what was consented to."
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ResignationPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Resignation"
                }
              }
            }
          }
        ]
      },
      "NoDuesRemarksInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "remarks": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "NoDuesFlagDuesInput": {
        "type": "object",
        "required": [
          "dues_amount"
        ],
        "additionalProperties": false,
        "properties": {
          "dues_amount": {
            "$ref": "#/components/schemas/MoneyRef"
          },
          "remarks": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "NoDuesForceCompleteInput": {
        "type": "object",
        "required": [
          "remarks"
        ],
        "additionalProperties": false,
        "properties": {
          "remarks": {
            "type": "string"
          }
        }
      },
      "NoDuesLine": {
        "description": "exit.no_dues — a per-department no-dues sign-off line (db 11 §2.2).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "clearance_id",
              "department",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "clearance_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "department": {
                "$ref": "#/components/schemas/ClearanceDepartment"
              },
              "status": {
                "$ref": "#/components/schemas/NoDuesStatus"
              },
              "owner_employee_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "owner_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "dues_amount": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/MoneyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "asset_return_ref": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "ref→assets.asset_returns (AST-F02)."
              },
              "signed_off_by": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "signed_off_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "remarks": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ExitClearance": {
        "description": "exit.exit_clearances — the overall clearance case & F&F gate (db 11 §2.2).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "clearance_no",
              "resignation_id",
              "employee_id",
              "status",
              "total_departments",
              "cleared_departments",
              "ff_gate_released"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "clearance_no": {
                "$ref": "#/components/schemas/BusinessNoRef"
              },
              "resignation_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ref→people.employees, by projection."
              },
              "status": {
                "$ref": "#/components/schemas/ClearanceStatus"
              },
              "last_working_day": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DateOnlyRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "total_departments": {
                "type": "integer"
              },
              "cleared_departments": {
                "type": "integer"
              },
              "ff_gate_released": {
                "type": "boolean",
                "description": "F&F released on full clearance — computed/paid in `pay` (PAY-F07); this is the gate flag only."
              },
              "ff_released_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "initiated_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "completed_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ExitClearanceDetail": {
        "description": "EXT-S03/EXT-S06 clearance detail — the case plus its five department no-dues lines.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ExitClearance"
          },
          {
            "type": "object",
            "properties": {
              "no_dues": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NoDuesLine"
                }
              }
            }
          }
        ]
      },
      "ExitClearancePage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ExitClearance"
                }
              }
            }
          }
        ]
      },
      "ExitFeedbackCreate": {
        "type": "object",
        "description": "EXT-S04 confidential questionnaire input → `exit.exit_feedback` (`status='SUBMITTED'`). One per separation (db 11 §2.3).",
        "additionalProperties": false,
        "properties": {
          "is_anonymous": {
            "type": "boolean",
            "default": false,
            "description": "When true, `employee_id` is not stored (db 11 §2.1 check)."
          },
          "primary_reason": {
            "$ref": "#/components/schemas/ResignationReason"
          },
          "ratings": {
            "type": "object",
            "description": "`{ management, culture, compensation, growth, work_life }`, 1–5 per dimension (db 11 §2.3 JSONB shape).",
            "properties": {
              "management": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5
              },
              "culture": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5
              },
              "compensation": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5
              },
              "growth": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5
              },
              "work_life": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5
              }
            }
          },
          "would_recommend": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "would_rejoin": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "comments": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ExitFeedback": {
        "description": "exit.exit_feedback — confidential exit-interview feedback, one per separation (db 11 §2.3).",
        "allOf": [
          {
            "type": "object",
            "required": [
              "id",
              "resignation_id",
              "is_anonymous",
              "is_confidential",
              "conducted_via",
              "status"
            ],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "resignation_id": {
                "$ref": "#/components/schemas/UuidRef"
              },
              "employee_id": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UuidRef"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "null when `is_anonymous`; otherwise RBAC-restricted to HR consumers (db 11 §2.3 Notes, rev. 2026-07-02)."
              },
              "is_anonymous": {
                "type": "boolean"
              },
              "is_confidential": {
                "type": "boolean"
              },
              "primary_reason": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/ResignationReason"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "ratings": {
                "type": "object",
                "properties": {
                  "management": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "culture": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "compensation": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "growth": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "work_life": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                }
              },
              "would_recommend": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "would_rejoin": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "comments": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "conducted_via": {
                "$ref": "#/components/schemas/FeedbackChannel"
              },
              "status": {
                "$ref": "#/components/schemas/FeedbackStatus"
              },
              "submitted_at": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/TimestampRef"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/AuditMetaRef"
          }
        ]
      },
      "ExitFeedbackPage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CursorPageRef"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ExitFeedback"
                }
              }
            }
          }
        ]
      },
      "Uuid": {
        "type": "string",
        "format": "uuid",
        "description": "UUIDv7 surrogate primary key (db-docs/00 §3). Never the business identifier."
      },
      "DateOnly": {
        "type": "string",
        "format": "date",
        "description": "Calendar-only value (pay-period date, leave date, due date)."
      },
      "Timestamp": {
        "type": "string",
        "format": "date-time",
        "description": "timestamptz, serialized UTC ISO-8601. Presentation timezone is a client concern."
      },
      "Rate": {
        "type": "string",
        "pattern": "^-?\\d+(\\.\\d{1,6})?$",
        "description": "numeric(9,6) fraction as a string, e.g. \"0.120000\" for the 12% EPF rate. Never a float; percentages are stored as fractions."
      },
      "Money": {
        "type": "object",
        "description": "Exact decimal money (db-docs/00 §6). `amount` is a STRING so float never enters the wire.",
        "required": [
          "amount",
          "currency_code"
        ],
        "additionalProperties": false,
        "properties": {
          "amount": {
            "type": "string",
            "pattern": "^-?\\d+(\\.\\d{1,2})?$",
            "description": "numeric(18,2) as a string, e.g. \"45000.00\"."
          },
          "currency_code": {
            "$ref": "#/components/schemas/CurrencyCode"
          }
        }
      },
      "CurrencyCode": {
        "type": "string",
        "enum": [
          "INR",
          "SAR"
        ],
        "description": "ISO-4217. A legal entity operates in a single currency (db-docs/00 §6)."
      },
      "BusinessNo": {
        "type": "string",
        "description": "Tenant-unique, prefixed human reference (`employee_no`, `requisition_no`, `offer_no`, `payslip_no`, `claim_no`, `ticket_no`, `asset_no`, `case_no`). Read-model field; never a path key.\n"
      },
      "LocalizedText": {
        "type": "object",
        "description": "Locale-keyed content map (db-docs/00 §9) for localized/white-label text (designation titles, announcement bodies, template names). Keys are the legal entity's active locale set.\n",
        "properties": {
          "en": {
            "type": "string"
          },
          "ar": {
            "type": "string"
          }
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "FileDownload": {
        "type": "object",
        "description": "Authorized file handle (db-docs/00 §14, xc.files). Bytes never transit the API — the backend mints a time-limited presigned URL after authorization. Clients never see storage keys or hold storage credentials; the presigned URL is never persisted.\n",
        "required": [
          "file_id",
          "file_name",
          "url",
          "expires_at"
        ],
        "properties": {
          "file_id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "file_name": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "content_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "SHA-256",
            "present where tamper-evidence matters (payslips": null,
            "letters": null,
            "e-sign artifacts).": null
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Time-limited presigned URL."
          },
          "expires_at": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "AuditMeta": {
        "type": "object",
        "description": "Standard mutable-entity columns (db-docs/00 §5). Read-only; present on every mutable read-model.",
        "readOnly": true,
        "properties": {
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "created_by": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Uuid"
              },
              {
                "type": "null"
              }
            ],
            "description": "null = system/jobs"
          },
          "updated_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "updated_by": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "deleted_at": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Timestamp"
              },
              {
                "type": "null"
              }
            ],
            "description": "soft-delete marker; live rows are null. Deleted rows are excluded by default scope."
          },
          "version": {
            "type": "integer",
            "description": "Optimistic-lock counter (where present); surfaces as the ETag."
          }
        }
      },
      "AppendOnlyMeta": {
        "type": "object",
        "description": "Standard append-only/immutable columns (db-docs/00 §5/§8). No update/version/delete; corrections are new compensating rows.",
        "readOnly": true,
        "properties": {
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "created_by": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Uuid"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "CursorPage": {
        "type": "object",
        "description": "Generic cursor-pagination envelope. List operations compose it via allOf to type `data`, e.g. `allOf: [ {$ref CursorPage}, { properties: { data: { items: {$ref Employee} } } } ]`.\n",
        "required": [
          "data",
          "page"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {}
          },
          "page": {
            "type": "object",
            "required": [
              "has_more"
            ],
            "properties": {
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "prev_cursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "has_more": {
                "type": "boolean"
              },
              "total_est": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Optional, capped, APPROXIMATE row estimate for grid \"X of Z\" display only — never an exact COUNT(*) on large tables (attend.attendance_records, xc.notifications, audit.*).\n"
              }
            }
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem detail (application/problem+json). The platform-wide error envelope (03 §1).",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "default": "about:blank",
            "description": "Problem-type URI."
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable summary (stable per type)."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code, duplicated for convenience."
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence."
          },
          "instance": {
            "type": "string",
            "description": "URI reference for this specific occurrence."
          },
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "correlation_id": {
            "$ref": "#/components/schemas/Uuid"
          }
        }
      },
      "ValidationProblem": {
        "description": "422 field-level validation failure; extends Problem with a per-field error array. `detail` is ALWAYS present on a 422 (#1251) and is the human summary of `errors[]`: one offending field renders as `\"<field>: <its message>\"` (`withholding_amount: is required for an India entity`), several as `\"N fields were refused: a, b, c.\"`, capped at five names. It is display copy derived from members already in the same body — clients keep branching on `code` and mapping `errors[].pointer` back to a control, never parsing this sentence.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/Problem"
          },
          {
            "type": "object",
            "required": [
              "detail",
              "errors"
            ],
            "properties": {
              "detail": {
                "type": "string",
                "description": "Human summary of `errors[]`, always populated on a 422 so a client never has to fall back to generic copy for the one status that names a fixable field.\n",
                "example": "withholding_amount: is required for an India entity"
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "pointer",
                    "rule"
                  ],
                  "properties": {
                    "pointer": {
                      "type": "string",
                      "description": "JSON Pointer to the offending field, e.g. /claim_amount"
                    },
                    "rule": {
                      "type": "string",
                      "enum": [
                        "required",
                        "format",
                        "length",
                        "range",
                        "cross-field",
                        "async-server",
                        "consent-gated",
                        "uniqueness-business",
                        "not_found"
                      ],
                      "description": "FSD validation taxonomy rule (fsd-docs/00 §8.2). `not_found` is the server-side-lookup arm: a body field that REFERENCES another resource (e.g. `project_id` on a work entry) and did not resolve for this caller. It is reported here, under the field's pointer, and NOT as a 404 — the request addresses its own resource, so the failure belongs on the form field the client can actually fix (#805).\n"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "ErrorCode": {
        "type": "string",
        "description": "Machine-stable error code (paired with the HTTP status; drives client handling, not display copy).",
        "enum": [
          "VALIDATION_FAILED",
          "IDEMPOTENCY_KEY_REUSE",
          "VERSION_CONFLICT",
          "PRECONDITION_REQUIRED",
          "MAKER_EQUALS_CHECKER",
          "STEP_UP_REQUIRED",
          "CONSENT_REQUIRED",
          "TOKEN_DENIED",
          "SCOPE_DENIED",
          "OWNERSHIP_DENIED",
          "STATE_TRANSITION_INVALID",
          "FACE_MISMATCH",
          "FACE_VERIFICATION_REQUIRED",
          "WITHHOLDING_REVIEW_REQUIRED",
          "FEATURE_NOT_IN_PLAN",
          "PLAN_LIMIT_EXCEEDED",
          "TENANT_PAST_DUE",
          "TENANT_SUSPENDED",
          "TENANT_CANCELLED",
          "RATE_LIMITED",
          "NOT_FOUND"
        ]
      }
    },
    "parameters": {
      "PathId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "UUIDv7 surrogate key of the target resource. Business numbers (`employee_no`, `claim_no`, …) are read-model fields, never path keys.",
        "schema": {
          "$ref": "#/components/schemas/Uuid"
        }
      },
      "PageSize": {
        "name": "page[size]",
        "in": "query",
        "required": false,
        "description": "Max items per page. Cursor pagination only (03 §2); offset pagination is rejected (ADR 0015).",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        }
      },
      "PageAfter": {
        "name": "page[after]",
        "in": "query",
        "required": false,
        "description": "Opaque forward keyset cursor (from a prior page's `page.next_cursor`).",
        "schema": {
          "type": "string"
        }
      },
      "PageBefore": {
        "name": "page[before]",
        "in": "query",
        "required": false,
        "description": "Opaque backward keyset cursor (from a prior page's `page.prev_cursor`).",
        "schema": {
          "type": "string"
        }
      },
      "AcceptLanguage": {
        "name": "Accept-Language",
        "in": "header",
        "required": false,
        "description": "Locale for server-rendered/localized text (LocalizedText resolution, letters, notifications). Active locale set comes from the legal entity's compliance pack; KSA tenants default `ar`.\n",
        "schema": {
          "type": "string",
          "enum": [
            "en",
            "ar"
          ],
          "default": "en"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Client-generated unique key. REQUIRED on every mutation (this round tightens ADR 0015's \"platform + retryable mutations\" floor to ALL mutations for uniformity — offline punch/leave sync depends on it). Scoped (tenant, principal, route, key); a replay within the ~24h window returns the stored response with `Idempotency-Replayed: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSE (04 §1).\n",
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 255
        }
      },
      "IfMatch": {
        "name": "If-Match",
        "in": "header",
        "required": true,
        "description": "Optimistic-concurrency precondition for mutating a VERSIONED mutable entity (db-docs/00 §5 applies `version` where concurrent edits are likely). Value is the entity's current ETag (the row `version`). Absent → 428; stale → 412 (04 §2). N/A for append-only entities and for unversioned low-contention entities (their update ops simply omit this parameter).\n",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, expired, or invalid session token (no authenticated principal).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated but denied — permission token not granted, out of scope (self/team/branch), not the owner, tenant suspended, or an MC-2 operation without a fresh step-up challenge. `code` ∈ TOKEN_DENIED | SCOPE_DENIED | OWNERSHIP_DENIED | MAKER_EQUALS_CHECKER | STEP_UP_REQUIRED | CONSENT_REQUIRED | TENANT_SUSPENDED. A plan feature-flag being off is 402 FEATURE_NOT_IN_PLAN, not 403 (see PaymentRequired).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource does not exist OR is masked by RLS (tenant/self/team/branch scope) — the API does not distinguish, so existence is never confirmed across a scope boundary (02 §4 disclosure posture).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Conflict": {
        "description": "Idempotency-key reuse with a different body, an invalid state transition, or a uniqueness/business-rule violation (fsd 00 §8.2). For database-backed uniqueness rules, detail names the exact violated rule; unmapped constraints are not collapsed into a generic 409.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Field-level validation failed. The body carries both `errors[]` (per-field, pointer-addressed) and a `detail` summarising them — never an empty `detail` (#1251).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationProblem"
            },
            "examples": {
              "singleField": {
                "summary": "One refused field — `detail` names it",
                "value": {
                  "type": "about:blank",
                  "title": "Unprocessable Entity",
                  "status": 422,
                  "code": "VALIDATION_FAILED",
                  "detail": "withholding_amount: is required for an India entity",
                  "errors": [
                    {
                      "pointer": "/withholding_amount",
                      "rule": "required",
                      "message": "is required for an India entity"
                    }
                  ]
                }
              },
              "severalFields": {
                "summary": "Several refused fields — `detail` counts and names them",
                "value": {
                  "type": "about:blank",
                  "title": "Unprocessable Entity",
                  "status": 422,
                  "code": "VALIDATION_FAILED",
                  "detail": "2 fields were refused: effective_from, cap_amount.amount.",
                  "errors": [
                    {
                      "pointer": "/effective_from",
                      "rule": "cross-field",
                      "message": "Overlaps an existing version."
                    },
                    {
                      "pointer": "/cap_amount/amount",
                      "rule": "range",
                      "message": "Must be a non-negative decimal string."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "Locked": {
        "description": "Tenant subscription `past_due` (ADR 0009): WRITES are blocked (423), reads still succeed. `code` = TENANT_PAST_DUE. Mutations return this; list/get operations do not.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Per-principal/route rate limit exceeded.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "PreconditionRequired": {
        "description": "If-Match header absent on a mutation of a versioned mutable entity (428).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "PreconditionFailed": {
        "description": "If-Match / ETag mismatch — the row changed since it was read (412, VERSION_CONFLICT).",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "headers": {
      "ETag": {
        "description": "Strong validator of the row `version` (e.g. `\"v7\"`). Use as `If-Match` on the next mutation.",
        "schema": {
          "type": "string"
        }
      },
      "Location": {
        "description": "URI of the created/affected resource.",
        "schema": {
          "type": "string",
          "format": "uri-reference"
        }
      },
      "IdempotencyReplayed": {
        "description": "`true` when a stored idempotent response was replayed rather than freshly computed.",
        "schema": {
          "type": "boolean"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying (on 429 / 503).",
        "schema": {
          "type": "integer"
        }
      }
    }
  }
}