Merged in feature/batch-status (pull request #215)

Implement and test the batch status feature

* working

serviceAPIs/queryAPI.yaml

@@ -1680,6 +1680,9 @@ paths:
       summary: List users
       description: >-
         Lists users from AWS Cognito with pagination, filtering, and sorting support.
+        Note: The roles field is not populated in this response. To retrieve roles for
+        a specific user, call GET /admin/users/{email} which returns the full user
+        details including Permit.io roles.
       security:
         - jwtAuth: []
       parameters:
@@ -2942,8 +2945,65 @@ components:
           nullable: true
           description: When the batch upload completed processing
 
+    BatchDocumentOutcome:
+      type: object
+      description: Per-file outcome from batch extraction and pipeline processing
+      required: [filename, outcome]
+      properties:
+        filename:
+          type: string
+          maxLength: 4096
+          description: Original filename from the ZIP archive
+        outcome:
+          type: string
+          enum:
+            [
+              submitted,
+              duplicate,
+              failed_open,
+              failed_read,
+              failed_s3_upload,
+              failed_upload,
+              invalid_type,
+              init_complete,
+              init_duplicate,
+              sync_complete,
+              sync_skipped,
+              clean_passed,
+              clean_failed,
+            ]
+          description: Current processing status
+        error_detail:
+          type: string
+          maxLength: 2048
+          nullable: true
+          description: Human-readable error message for failure outcomes
+        document_id:
+          type: string
+          format: uuid
+          maxLength: 36
+          nullable: true
+          description: Assigned document ID (null for files that never became documents)
+        clean_fail_reason:
+          type: string
+          maxLength: 2048
+          nullable: true
+          description: >
+            Specific clean validation failure reason when outcome is clean_failed.
+            Null otherwise.
+        created_at:
+          type: string
+          format: date-time
+          maxLength: 50
+          description: When the file was first extracted from the ZIP
+        updated_at:
+          type: string
+          format: date-time
+          maxLength: 50
+          description: When the outcome was last updated by a pipeline stage
+
     BatchUploadDetails:
-      description: Detailed information about a batch upload including failed filenames
+      description: Detailed information about a batch upload including failed filenames and per-file outcomes
       allOf:
         - $ref: "#/components/schemas/BatchUploadSummary"
         - type: object
@@ -2957,6 +3017,12 @@ components:
                 pattern: "^.+$"
               description: List of filenames that failed processing
               example: ["doc3.pdf", "doc17.pdf"]
+            document_outcomes:
+              type: array
+              maxItems: 10000
+              items:
+                $ref: "#/components/schemas/BatchDocumentOutcome"
+              description: Per-file outcome tracking for all files in the batch
 
     BatchUploadList:
       type: object
@@ -3653,7 +3719,9 @@ components:
             type: string
             maxLength: 100
             pattern: "^.+$"
-          description: Roles assigned in Permit.io
+          description: >-
+            Roles assigned in Permit.io. Only populated by GET /admin/users/{email}.
+            Not populated by GET /admin/users (list endpoint) for performance reasons.
           example: ["admin", "viewer"]
         created_at:
           type: string