@thinkai/tai-api-contract 2.48.0 → 2.50.0-pr.877.6ff333f6

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.48.0
+  version: 2.50.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -60,6 +60,10 @@ tags:
     description: Platform-admin operations restricted to PLATFORM_ADMIN_EMAILS. Callers must present a valid JWT from an email on that allowlist; all other callers receive 403.
   - name: HRIS
     description: HRIS integrations (Personio, ZenHR, …); absence data, sync status, and manual sync (issue #447).
+  - name: PrivacyRequests
+    description: >
+      Data subject access / erasure / portability request intake and privacy-ops management (DSAR, issue #611).
+      Public and authenticated submission; platform-admin queue, export, and fulfillment.
 
 paths:
   /admin/users/{userId}:
@@ -296,6 +300,400 @@ paths:
                 error: Forbidden
                 code: forbidden
 
+  /privacy-requests:
+    post:
+      tags: [PrivacyRequests]
+      summary: Submit a privacy rights request (public)
+      operationId: submitPublicPrivacyRequest
+      security: []
+      description: >
+        Public, unauthenticated intake for data subject access, erasure, portability, rectification,
+        restriction, and objection requests (#611). No bearer token required.
+
+        **Abuse controls:** requests are rate limited per client IP (`429` with `Retry-After` when
+        exceeded). A hidden honeypot field (`companyWebsite`) silently absorbs bot submissions. The
+        response shape is identical whether or not the email matches an existing account, so the
+        endpoint cannot be used to enumerate users. Duplicate open requests for the same email and
+        request type within 24h are rejected with `409`.
+
+        **Identity is not proven** by this route; privacy ops must verify identity before any export
+        or erasure is fulfilled.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreatePrivacyRequestBodyDto"
+      responses:
+        "201":
+          description: Request accepted and queued for privacy ops.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreatePrivacyRequestResultDto"
+        "400":
+          description: Missing or invalid email, unknown request type, or details too long.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: A valid email is required
+                code: invalid_email
+        "409":
+          description: An open request for this email and type already exists.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: An open request for this email already exists
+                code: duplicate_open_request
+        "429":
+          description: Too many submissions from this client; retry later.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Too many requests
+                code: too_many_requests
+
+  /me/privacy-requests:
+    get:
+      tags: [PrivacyRequests, Me]
+      summary: List the caller's privacy requests
+      operationId: listMyPrivacyRequests
+      description: >
+        Returns privacy requests whose subject is the authenticated caller (matched by user id or
+        email), limited to a reference code and status so callers can track progress.
+      responses:
+        "200":
+          description: Caller's privacy requests, newest first.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MyPrivacyRequestListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [PrivacyRequests, Me]
+      summary: Submit a privacy request as the authenticated user
+      operationId: submitMyPrivacyRequest
+      description: >
+        Authenticated intake. The subject is always the caller's own profile; the request is
+        auto-marked identity-verified because the JWT proves identity. Supplying an `email` that
+        does not match the caller is rejected with `400`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMyPrivacyRequestBodyDto"
+      responses:
+        "201":
+          description: Request accepted and queued.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreatePrivacyRequestResultDto"
+        "400":
+          description: Unknown request type, details too long, or email override attempted.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Email cannot be overridden on an authenticated request
+                code: email_override_rejected
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: An open request for this subject and type already exists.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/privacy-requests:
+    post:
+      tags: [PrivacyRequests, Workspace]
+      summary: Submit a privacy request on behalf of a workspace member (B2B controller)
+      operationId: submitWorkspacePrivacyRequest
+      description: >
+        Workspace-admin route for B2B controllers to raise a privacy request on behalf of an
+        employee (`subjectEmail`). The request is bound to the workspace and requires manual
+        identity verification by privacy ops before fulfillment. Non-admin members receive `403`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateWorkspacePrivacyRequestBodyDto"
+      responses:
+        "201":
+          description: Request accepted and queued.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreatePrivacyRequestResultDto"
+        "400":
+          description: Invalid subject email, unknown request type, or details too long.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a workspace admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /admin/privacy-requests:
+    get:
+      tags: [PrivacyRequests, PlatformAdmin]
+      summary: List privacy requests (privacy-ops queue)
+      operationId: adminListPrivacyRequests
+      description: >
+        Platform-admin queue of privacy requests, newest first, with SLA due dates for triage.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - name: status
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/PrivacyRequestStatus"
+          description: Filter by workflow status.
+        - name: requestType
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/PrivacyRequestType"
+          description: Filter by request type.
+        - name: overdue
+          in: query
+          required: false
+          schema:
+            type: boolean
+          description: When true, return only requests past their SLA due date and not yet completed.
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 100
+          description: Maximum number of rows to return (default 100, max 200).
+      responses:
+        "200":
+          description: Privacy request queue.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrivacyRequestListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+
+  /admin/privacy-requests/{requestId}:
+    get:
+      tags: [PrivacyRequests, PlatformAdmin]
+      summary: Get a privacy request with its event timeline
+      operationId: adminGetPrivacyRequest
+      parameters:
+        - $ref: "#/components/parameters/PrivacyRequestId"
+      responses:
+        "200":
+          description: Privacy request detail with audit timeline.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrivacyRequestDetailDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "404":
+          description: Request not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    patch:
+      tags: [PrivacyRequests, PlatformAdmin]
+      summary: Update a privacy request (status, assignee, notes, identity verification)
+      operationId: adminUpdatePrivacyRequest
+      description: >
+        Update workflow fields. Setting `markIdentityVerified: true` records the verifying admin and
+        unlocks export and erasure fulfillment. Transitioning `status` to `completed` requires both
+        `fulfillmentAction` and `fulfillmentRef`.
+      parameters:
+        - $ref: "#/components/parameters/PrivacyRequestId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdatePrivacyRequestBodyDto"
+      responses:
+        "200":
+          description: Updated privacy request detail.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrivacyRequestDetailDto"
+        "400":
+          description: Invalid field value or missing fulfillment metadata for completion.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Completing a request requires a fulfillment action and reference
+                code: fulfillment_metadata_required
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "404":
+          description: Request not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /admin/privacy-requests/{requestId}/export:
+    post:
+      tags: [PrivacyRequests, PlatformAdmin]
+      summary: Generate a DSAR export bundle for a privacy request
+      operationId: adminExportPrivacyRequest
+      description: >
+        Assembles the subject's personal data across workspaces into a single JSON bundle for an
+        access or portability request, per the PII inventory scope. The subject is resolved by user
+        id or email. Blocked until identity is verified (`403 identity_not_verified`). Bundles larger
+        than the size cap return `413 export_too_large`; scope by workspace in that case. The bundle
+        is generated on demand and not persisted server-side.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/PrivacyRequestId"
+      responses:
+        "200":
+          description: DSAR export bundle (also offered as a file download via Content-Disposition).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrivacyRequestExportDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin, or identity has not been verified.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Identity must be verified before export
+                code: identity_not_verified
+        "404":
+          description: Request not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "413":
+          description: Export exceeds the size cap; scope the request by workspace.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Export bundle is too large; scope by workspace
+                code: export_too_large
+
+  /admin/privacy-requests/{requestId}/fulfill/person-erasure:
+    post:
+      tags: [PrivacyRequests, PlatformAdmin]
+      summary: Fulfill an erasure request by erasing workspace person-level data
+      operationId: adminFulfillPrivacyRequestPersonErasure
+      description: >
+        Thin wrapper around workspace person-level insights erasure (#706) for privacy-request
+        fulfillment. Erases or anonymizes the subject's org-chart, AI-tool, dashboard, absence, and
+        readiness data in one workspace. Blocked until identity is verified. Records an audit event
+        on the privacy request with the categories erased.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/PrivacyRequestId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FulfillPersonErasureBodyDto"
+      responses:
+        "200":
+          description: Erasure result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrivacyRequestPersonErasureResultDto"
+        "400":
+          description: Missing workspaceId/personId or invalid options.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin, or identity has not been verified.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Identity must be verified before erasure
+                code: identity_not_verified
+        "404":
+          description: Request not found, or person not found in the workspace org chart.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /me:
     get:
       tags: [Me]
@@ -1172,6 +1570,8 @@ paths:
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
         - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1220,6 +1620,8 @@ paths:
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
         - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1284,6 +1686,8 @@ paths:
             maximum: 10
             default: 3
         - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1349,6 +1753,8 @@ paths:
           schema:
             type: string
         - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1422,6 +1828,8 @@ paths:
             maximum: 10
             default: 3
         - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1737,11 +2145,11 @@ paths:
       summary: AI usage & spend insights — AI-assisted code percentage
       description: >
         Period and weekly AI-assisted code percentage for the Measure **AI-assisted code**
-        card on `/phase-c/c7` and the **AI impact** curve on `/phase-c/c4`. When scoped
-        productivity metrics include `aiAssistedContributionRatioPercent`, values are
-        **measured** from ingest; otherwise the API falls back to token→LOC heuristics and
-        sets `dataQuality` to **estimated**. Clients should not present estimated series as
-        Cursor-measured signal.
+        card on `/phase-c/c7` and the **AI impact** curve on `/phase-c/c4`. When engagement
+        daily rows exist for the scope, values are **measured** from Σ `ai_lines_added` ÷
+        merged-PR lines (`dashboard_metrics`); otherwise the API falls back to token→LOC
+        heuristics and sets `dataQuality` to **estimated**. Clients should not present
+        estimated series as editor-measured signal.
       operationId: getAiUsageSpendAiAssistedCodePercentage
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1788,6 +2196,62 @@ paths:
         "404":
           description: Workspace does not exist or malformed workspaceId
 
+  /workspaces/{workspaceId}/insights/ai-usage-spend/provider-engagement-insights:
+    get:
+      tags: [Workspace]
+      summary: AI usage & spend insights — provider engagement cards
+      description: >
+        Provider-specific engagement insight metrics derived from
+        `tai_workspace_ai_tool_engagement_daily` (accepted AI lines, tab completions,
+        suggestion accept rates, Claude Code sessions, etc.). Metrics are
+        **provider- and data-gated**: structurally absent signals render as N/A, not zero.
+        Claude per-user cards require Enterprise Analytics (`insightsPlan` ≠ team).
+      operationId: getAiUsageSpendProviderEngagementInsights
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
+      responses:
+        "200":
+          description: Provider engagement insight cards
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageSpendProviderEngagementInsightsDto"
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
   /workspaces/{workspaceId}/insights/ai-usage-spend/ai-tool-usage-spend:
     get:
       tags: [Workspace]
@@ -5705,6 +6169,14 @@ components:
         type: string
         format: uuid
       description: Workspace member user id (`tai_users.id`).
+    PrivacyRequestId:
+      name: requestId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Privacy request id (`tai_privacy_requests.id`).
     FixId:
       name: fixId
       in: path
@@ -5716,12 +6188,30 @@ components:
       name: rangeId
       in: query
       description: >
-        Productivity insights time range in weeks (`4w`=4, `8w`=8, `12w`=12, `16w`=16).
-        Legacy `q` is an alias for 12 weeks.
+        Productivity insights time range. Daily windows: `7d`, `30d`, `90d`, `180d`, or custom
+        `cr:YYYY-MM-DD:YYYY-MM-DD`. Weekly legacy: `4w`, `8w`, `q` (12 weeks), `12w`, `16w`.
+        Omit when using explicit `from`/`to` day bounds.
       schema:
         type: string
-        enum: [4w, 8w, q, 12w, 16w]
         default: 4w
+    InsightsProductivityFrom:
+      name: from
+      in: query
+      description: >
+        Inclusive start of a daily window (`YYYY-MM-DD`). When set with `to`, overrides `rangeId`
+        for day-mode responses (max 180 days).
+      schema:
+        type: string
+        format: date
+    InsightsProductivityTo:
+      name: to
+      in: query
+      description: >
+        Inclusive end of a daily window (`YYYY-MM-DD`). When set with `from`, overrides `rangeId`
+        for day-mode responses (max 180 days).
+      schema:
+        type: string
+        format: date
     InsightsDepartmentFilter:
       name: department
       in: query
@@ -6687,6 +7177,32 @@ components:
           type: string
           description: Applied team name filter from the Measure UI.
 
+    ProductivityInsightsGranularity:
+      type: string
+      enum: [day, week]
+      description: >
+        Echo of the resolved time bucket for this response. `day` when the request used an
+        `Nd`/`cr:`/`from`+`to` window; `week` for legacy weekly rangeIds or `year` heatmap mode.
+
+    ProductivityInsightsDailyBucketDto:
+      type: object
+      additionalProperties: false
+      required: [date, mergedPrCount]
+      properties:
+        date:
+          type: string
+          format: date
+          description: UTC calendar day (`YYYY-MM-DD`).
+        mergedPrCount:
+          type: number
+          minimum: 0
+        ciFailuresCount:
+          type: integer
+          minimum: 0
+          description: >
+            GitHub Actions CI build failures on this day from `ciFailureRuns` ledger when CI
+            ingest is enabled.
+
     ProductivityInsightsAggregatedTeamWeekDto:
       type: object
       additionalProperties: false
@@ -6734,7 +7250,7 @@ components:
     ProductivityInsightsAggregatedTeamRowDto:
       type: object
       additionalProperties: false
-      required: [teamId, teamName, headcount, weeks]
+      required: [teamId, teamName, headcount]
       properties:
         teamId:
           type: string
@@ -6748,6 +7264,11 @@ components:
         notInOrgChart:
           type: boolean
           description: True when the team aggregates GitHub logins not mapped in the org chart (`teamId` `__other`).
+        days:
+          type: array
+          description: Present in day-mode responses — daily merged PR and CI failure counts.
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsDailyBucketDto"
         weeks:
           type: array
           items:
@@ -6755,9 +7276,9 @@ components:
 
     ProductivityInsightsRangeId:
       type: string
-      enum: [4w, 8w, q, 12w, 16w]
       description: >
-        Weekly bucket count (`4w`=4, `8w`=8, `12w`=12, `16w`=16). Legacy `q` aliases 12 weeks.
+        Daily windows: `7d`, `30d`, `90d`, `180d`, or custom `cr:YYYY-MM-DD:YYYY-MM-DD`.
+        Weekly legacy: `4w`, `8w`, `q` (12 weeks), `12w`, `16w`.
 
     ProductivityInsightsAggregatedTeamsDto:
       type: object
@@ -6769,6 +7290,16 @@ components:
           format: uuid
         range:
           $ref: "#/components/schemas/ProductivityInsightsRangeId"
+        granularity:
+          $ref: "#/components/schemas/ProductivityInsightsGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -6802,7 +7333,7 @@ components:
     ProductivityInsightsMergedPrContributorRowDto:
       type: object
       additionalProperties: false
-      required: [personId, personName, weeks]
+      required: [personId, personName]
       properties:
         personId:
           type: string
@@ -6820,6 +7351,11 @@ components:
         githubLogin:
           type: string
           description: GitHub login for unattributed contributors (when notInOrgChart is true).
+        days:
+          type: array
+          description: Present in day-mode responses — daily merged PR counts per contributor.
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsDailyBucketDto"
         weeks:
           type: array
           items:
@@ -6828,23 +7364,40 @@ components:
     ProductivityInsightsMergedPrTrendsDto:
       type: object
       additionalProperties: false
-      required: [workspaceId, range, scope, generatedAt, weeks, contributors]
+      required: [workspaceId, range, scope, generatedAt, contributors]
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
           $ref: "#/components/schemas/ProductivityInsightsRangeId"
+        granularity:
+          $ref: "#/components/schemas/ProductivityInsightsGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
           type: string
           format: date-time
+        days:
+          type: array
+          description: >-
+            Portfolio daily merged PR series in day mode (max of contributor sum and org ledger).
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsDailyBucketDto"
         weeks:
           type: array
           description: >-
             Sum of contributor weekly merged PR counts (matches the contributors table).
             Not deduplicated org-wide unique PRs when the same PR appears on multiple rows.
+            Present in week-mode responses.
           items:
             $ref: "#/components/schemas/ProductivityInsightsMergedPrTrendWeekDto"
         contributors:
@@ -6901,7 +7454,7 @@ components:
     ProductivityInsightsTeamDetailDto:
       type: object
       additionalProperties: false
-      required: [teamId, teamName, headcount, weeks, summary]
+      required: [teamId, teamName, headcount, summary]
       properties:
         teamId:
           type: string
@@ -6920,6 +7473,13 @@ components:
           minimum: 2000
           maximum: 2100
           description: Present when the request included `year` — calendar-year heatmap mode.
+        days:
+          type: array
+          description: >-
+            Daily merged PR and CI failure counts for the selected period when `granularity` is
+            `day` (not present in `year` heatmap mode).
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsDailyBucketDto"
         heatmapWeeks:
           type: array
           description: >-
@@ -6953,6 +7513,16 @@ components:
           format: uuid
         range:
           $ref: "#/components/schemas/ProductivityInsightsRangeId"
+        granularity:
+          $ref: "#/components/schemas/ProductivityInsightsGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         year:
           type: integer
           minimum: 2000
@@ -7139,7 +7709,6 @@ components:
         - scope
         - generatedAt
         - contributor
-        - weeks
         - summary
       properties:
         workspaceId:
@@ -7149,6 +7718,16 @@ components:
           type: string
         range:
           $ref: "#/components/schemas/ProductivityInsightsRangeId"
+        granularity:
+          $ref: "#/components/schemas/ProductivityInsightsGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         year:
           type: integer
           minimum: 2000
@@ -7164,6 +7743,13 @@ components:
           description: True when the workspace has opted in to GitHub Actions CI ingest.
         contributor:
           $ref: "#/components/schemas/ProductivityInsightsContributorProfileDto"
+        days:
+          type: array
+          description: >-
+            Daily merged PR and CI failure counts for the selected period when `granularity` is
+            `day` (not present in `year` heatmap mode).
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsDailyBucketDto"
         weeks:
           type: array
           items:
@@ -7212,6 +7798,16 @@ components:
           format: uuid
         range:
           $ref: "#/components/schemas/ProductivityInsightsRangeId"
+        granularity:
+          $ref: "#/components/schemas/ProductivityInsightsGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         entityType:
@@ -7554,6 +8150,66 @@ components:
           items:
             $ref: "#/components/schemas/AiUsageSpendAiAssistedCodeWeekDto"
 
+    ProviderEngagementInsightAvailability:
+      type: string
+      enum: [measured, not_applicable]
+
+    AiUsageSpendProviderEngagementMetricDto:
+      type: object
+      additionalProperties: false
+      required: [id, label, value, displayValue, availability]
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        value:
+          type: number
+          nullable: true
+        displayValue:
+          type: string
+        availability:
+          $ref: "#/components/schemas/ProviderEngagementInsightAvailability"
+        unit:
+          type: string
+        methodologyNote:
+          type: string
+
+    AiUsageSpendProviderEngagementCardDto:
+      type: object
+      additionalProperties: false
+      required: [providerId, providerName, metrics]
+      properties:
+        providerId:
+          type: string
+        providerName:
+          type: string
+        metrics:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendProviderEngagementMetricDto"
+
+    AiUsageSpendProviderEngagementInsightsDto:
+      type: object
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt, providers]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        providers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendProviderEngagementCardDto"
+
     AiUsageSpendAiToolUsageSpendProviderItemDto:
       type: object
       additionalProperties: false
@@ -7977,6 +8633,12 @@ components:
         defaultWorkspaceId:
           type: string
           nullable: true
+        isPlatformAdmin:
+          type: boolean
+          description: >
+            True when the caller's email is on the `PLATFORM_ADMIN_EMAILS` allowlist. Lets the
+            frontend gate platform-admin surfaces (e.g. the privacy-request queue) without
+            duplicating the allowlist client-side.
 
     UpdateMeBodyDto:
       type: object
@@ -8000,6 +8662,341 @@ components:
             Must match the authenticated user's email (case-insensitive). Acts as
             a type-to-confirm guard against accidental deletion.
 
+    PrivacyRequestType:
+      type: string
+      enum: [access, erasure, portability, rectification, restriction, objection]
+      description: Data subject right being exercised (GDPR Arts. 15–21 / UAE PDPL).
+
+    PrivacyRequestStatus:
+      type: string
+      enum: [pending, in_progress, completed, rejected]
+      description: Workflow status of a privacy request.
+
+    PrivacyRequestIntakeChannel:
+      type: string
+      enum: [public, authenticated, workspace_admin]
+      description: How the request was submitted.
+
+    CreatePrivacyRequestBodyDto:
+      type: object
+      required: [email, requestType]
+      properties:
+        email:
+          type: string
+          format: email
+          description: Subject's email address.
+        requestType:
+          $ref: "#/components/schemas/PrivacyRequestType"
+        details:
+          type: string
+          maxLength: 4000
+          description: Optional free-text description of the request (max 4000 chars).
+        workspaceHint:
+          type: string
+          maxLength: 200
+          description: >
+            Optional free-text hint (e.g. company or workspace name) to help privacy ops locate the
+            subject. Never bound to a workspace id on the public channel.
+        companyWebsite:
+          type: string
+          description: >
+            Honeypot field. Must be left empty by real clients; non-empty submissions are silently
+            accepted but not persisted. Rendered hidden in the UI.
+
+    CreateMyPrivacyRequestBodyDto:
+      type: object
+      required: [requestType]
+      properties:
+        requestType:
+          $ref: "#/components/schemas/PrivacyRequestType"
+        details:
+          type: string
+          maxLength: 4000
+        email:
+          type: string
+          format: email
+          description: >
+            Optional. If provided it must match the caller's own email; a differing value is
+            rejected with `400 email_override_rejected`.
+
+    CreateWorkspacePrivacyRequestBodyDto:
+      type: object
+      required: [subjectEmail, requestType]
+      properties:
+        subjectEmail:
+          type: string
+          format: email
+          description: Email of the workspace member the request is raised on behalf of.
+        requestType:
+          $ref: "#/components/schemas/PrivacyRequestType"
+        details:
+          type: string
+          maxLength: 4000
+
+    CreatePrivacyRequestResultDto:
+      type: object
+      required: [referenceCode, requestType, status, slaDueAt]
+      properties:
+        referenceCode:
+          type: string
+          description: Human-friendly tracking code (e.g. `PR-2026-00042`).
+        requestType:
+          $ref: "#/components/schemas/PrivacyRequestType"
+        status:
+          $ref: "#/components/schemas/PrivacyRequestStatus"
+        slaDueAt:
+          type: string
+          format: date-time
+          description: When the request should be resolved by (default 30 days from submission).
+
+    MyPrivacyRequestSummaryDto:
+      type: object
+      required: [referenceCode, requestType, status, createdAt, slaDueAt]
+      properties:
+        referenceCode:
+          type: string
+        requestType:
+          $ref: "#/components/schemas/PrivacyRequestType"
+        status:
+          $ref: "#/components/schemas/PrivacyRequestStatus"
+        createdAt:
+          type: string
+          format: date-time
+        slaDueAt:
+          type: string
+          format: date-time
+        completedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    MyPrivacyRequestListDto:
+      type: object
+      required: [requests]
+      properties:
+        requests:
+          type: array
+          items:
+            $ref: "#/components/schemas/MyPrivacyRequestSummaryDto"
+
+    PrivacyRequestDto:
+      type: object
+      required:
+        [id, referenceCode, requestType, status, intakeChannel, subjectEmail, createdAt, updatedAt, slaDueAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        referenceCode:
+          type: string
+        requestType:
+          $ref: "#/components/schemas/PrivacyRequestType"
+        status:
+          $ref: "#/components/schemas/PrivacyRequestStatus"
+        intakeChannel:
+          $ref: "#/components/schemas/PrivacyRequestIntakeChannel"
+        subjectEmail:
+          type: string
+        subjectUserId:
+          type: string
+          format: uuid
+          nullable: true
+        workspaceId:
+          type: string
+          format: uuid
+          nullable: true
+          description: Set only for workspace-admin (B2B) submissions.
+        subjectWorkspaceHint:
+          type: string
+          nullable: true
+        requestedByUserId:
+          type: string
+          format: uuid
+          nullable: true
+        details:
+          type: string
+          nullable: true
+        internalNotes:
+          type: string
+          nullable: true
+        assignedTo:
+          type: string
+          nullable: true
+        identityVerifiedAt:
+          type: string
+          format: date-time
+          nullable: true
+        verifiedBy:
+          type: string
+          nullable: true
+        fulfillmentAction:
+          type: string
+          nullable: true
+        fulfillmentRef:
+          type: string
+          nullable: true
+        slaDueAt:
+          type: string
+          format: date-time
+        completedAt:
+          type: string
+          format: date-time
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+        overdue:
+          type: boolean
+          description: True when the SLA due date has passed and the request is not completed/rejected.
+
+    PrivacyRequestEventDto:
+      type: object
+      required: [id, eventType, createdAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        eventType:
+          type: string
+          enum:
+            [submitted, identity_verified, status_changed, assigned, export_generated, fulfillment_noted, duplicate_rejected]
+        actorEmail:
+          type: string
+          nullable: true
+        payload:
+          type: object
+          additionalProperties: true
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+
+    PrivacyRequestDetailDto:
+      type: object
+      required: [request, events]
+      properties:
+        request:
+          $ref: "#/components/schemas/PrivacyRequestDto"
+        events:
+          type: array
+          items:
+            $ref: "#/components/schemas/PrivacyRequestEventDto"
+
+    PrivacyRequestListDto:
+      type: object
+      required: [requests]
+      properties:
+        requests:
+          type: array
+          items:
+            $ref: "#/components/schemas/PrivacyRequestDto"
+
+    UpdatePrivacyRequestBodyDto:
+      type: object
+      properties:
+        status:
+          $ref: "#/components/schemas/PrivacyRequestStatus"
+        assignedTo:
+          type: string
+          nullable: true
+        internalNotes:
+          type: string
+          nullable: true
+        markIdentityVerified:
+          type: boolean
+          description: When true, records the caller as the verifier and unlocks export/erasure.
+        fulfillmentAction:
+          type: string
+          description: Short label for how the request was fulfilled (required when completing).
+        fulfillmentRef:
+          type: string
+          description: Reference to the fulfillment artifact (e.g. deletion job id; required when completing).
+
+    FulfillPersonErasureBodyDto:
+      type: object
+      required: [workspaceId, personId]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        personId:
+          type: string
+          description: Org-chart person id (usually the subject's email) within the workspace.
+        orgChart:
+          type: boolean
+        dashboardMetrics:
+          type: boolean
+        aiToolData:
+          type: boolean
+        absences:
+          type: boolean
+        readinessAnonymize:
+          type: boolean
+
+    PrivacyRequestPersonErasureResultDto:
+      type: object
+      required: [deleted]
+      properties:
+        deleted:
+          type: boolean
+        aiToolRowsDeleted:
+          type: integer
+        absencesDeleted:
+          type: integer
+        readinessRunsAnonymized:
+          type: integer
+        auditEntriesAnonymized:
+          type: integer
+
+    PrivacyRequestExportDto:
+      type: object
+      required: [metadata, subject]
+      description: >
+        DSAR export bundle assembled on demand for an access/portability request. `sections` holds
+        the subject's data grouped by source; shapes vary by section, so values are opaque objects.
+      properties:
+        metadata:
+          type: object
+          required: [referenceCode, generatedAt, subjectEmail]
+          properties:
+            referenceCode:
+              type: string
+            generatedAt:
+              type: string
+              format: date-time
+            subjectEmail:
+              type: string
+            subjectUserId:
+              type: string
+              nullable: true
+            workspaceCount:
+              type: integer
+            excluded:
+              type: array
+              items:
+                type: string
+              description: Data categories intentionally excluded from the bundle.
+            readinessRedaction:
+              type: string
+              description: Redaction policy applied to readiness runs (e.g. `requester_runs_only`).
+        subject:
+          type: object
+          additionalProperties: true
+          description: Profile and consent records for the subject.
+        sections:
+          type: object
+          additionalProperties: true
+          description: Per-source personal data (memberships, AI-tool, dashboard, absences, org chart, activity).
+        residualPersonData:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+          description: Workspaces where person-keyed rows exist but the subject has no membership (#269).
+
     WorkspaceSummaryDto:
       type: object
       required: [id, slug, name, status, role]