feat(core-api): add verification pipeline with vertex attire adapter

2026-02-24 13:29:24 -05:00
parent f2912a1c32
commit 4a1d5f89e4
12 changed files with 997 additions and 13 deletions
--- a/docs/MILESTONES/M4/planning/m4-api-catalog.md
+++ b/docs/MILESTONES/M4/planning/m4-api-catalog.md
@@ -128,7 +128,83 @@ This catalog defines the currently implemented core backend contract for M4.
 - `MODEL_FAILED`
 - `RATE_LIMITED`

-## 3.4 Health
+## 3.4 Create verification job
+1. Method and route: `POST /core/verifications`
+2. Auth: required
+3. Request:
+```json
+{
+  "type": "attire",
+  "subjectType": "worker",
+  "subjectId": "worker_123",
+  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/file.pdf",
+  "rules": {}
+}
+```
+4. Behavior:
+- validates `fileUri` ownership
+- requires file existence when `UPLOAD_MOCK=false` and `VERIFICATION_REQUIRE_FILE_EXISTS=true`
+- enqueues async verification
+5. Success `202`:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "PENDING",
+  "type": "attire",
+  "requestId": "uuid"
+}
+```
+6. Errors:
+- `UNAUTHENTICATED`
+- `VALIDATION_ERROR`
+- `FORBIDDEN`
+- `NOT_FOUND`
+
+## 3.5 Get verification status
+1. Method and route: `GET /core/verifications/{verificationId}`
+2. Auth: required
+3. Success `200`:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "NEEDS_REVIEW",
+  "type": "attire",
+  "requestId": "uuid"
+}
+```
+4. Errors:
+- `UNAUTHENTICATED`
+- `FORBIDDEN`
+- `NOT_FOUND`
+
+## 3.6 Review verification
+1. Method and route: `POST /core/verifications/{verificationId}/review`
+2. Auth: required
+3. Request:
+```json
+{
+  "decision": "APPROVED",
+  "note": "Manual review passed",
+  "reasonCode": "MANUAL_REVIEW"
+}
+```
+4. Success `200`: status becomes `APPROVED` or `REJECTED`.
+5. Errors:
+- `UNAUTHENTICATED`
+- `VALIDATION_ERROR`
+- `FORBIDDEN`
+- `NOT_FOUND`
+
+## 3.7 Retry verification
+1. Method and route: `POST /core/verifications/{verificationId}/retry`
+2. Auth: required
+3. Success `202`: status resets to `PENDING`.
+4. Errors:
+- `UNAUTHENTICATED`
+- `FORBIDDEN`
+- `NOT_FOUND`
+
+## 3.8 Health
 1. Method and route: `GET /health`
 2. Success `200`:
 ```json
@@ -150,3 +226,7 @@ This catalog defines the currently implemented core backend contract for M4.
 5. Max signed URL expiry: `900` seconds.
 6. LLM timeout: `20000` ms.
 7. LLM rate limit: `20` requests/minute/user.
+8. Verification access mode default: `authenticated`.
+9. Verification file existence check default: enabled (`VERIFICATION_REQUIRE_FILE_EXISTS=true`).
+10. Verification attire provider default in dev: `vertex` with model `gemini-2.0-flash-lite-001`.
+11. Verification government/certification providers: external adapters via configured provider URL/token.
--- a/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md
+++ b/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md
@@ -118,6 +118,82 @@ Authorization: Bearer <firebase-id-token>
 }
 ```

+## 4.4 Create verification job
+1. Route: `POST /core/verifications`
+2. Auth: required
+3. Purpose: enqueue an async verification job for an uploaded file.
+4. Request body:
+```json
+{
+  "type": "attire",
+  "subjectType": "worker",
+  "subjectId": "<worker-id>",
+  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/file.pdf",
+  "rules": {
+    "dressCode": "black shoes"
+  }
+}
+```
+5. Success `202` example:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "PENDING",
+  "type": "attire",
+  "requestId": "uuid"
+}
+```
+6. Current machine processing behavior in dev:
+- `attire`: live vision check using Vertex Gemini Flash Lite model.
+- `government_id`: third-party adapter path (falls back to `NEEDS_REVIEW` if provider is not configured).
+- `certification`: third-party adapter path (falls back to `NEEDS_REVIEW` if provider is not configured).
+
+## 4.5 Get verification status
+1. Route: `GET /core/verifications/{verificationId}`
+2. Auth: required
+3. Purpose: polling status from frontend.
+4. Success `200` example:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "NEEDS_REVIEW",
+  "type": "attire",
+  "review": null,
+  "requestId": "uuid"
+}
+```
+
+## 4.6 Review verification
+1. Route: `POST /core/verifications/{verificationId}/review`
+2. Auth: required
+3. Purpose: final human decision for the verification.
+4. Request body:
+```json
+{
+  "decision": "APPROVED",
+  "note": "Manual review passed",
+  "reasonCode": "MANUAL_REVIEW"
+}
+```
+5. Success `200` example:
+```json
+{
+  "verificationId": "ver_123",
+  "status": "APPROVED",
+  "review": {
+    "decision": "APPROVED",
+    "reviewedBy": "<uid>"
+  },
+  "requestId": "uuid"
+}
+```
+
+## 4.7 Retry verification
+1. Route: `POST /core/verifications/{verificationId}/retry`
+2. Auth: required
+3. Purpose: requeue verification to run again.
+4. Success `202` example: status resets to `PENDING`.
+
 ## 5) Frontend fetch examples (web)

 ## 5.1 Signed URL request
@@ -163,5 +239,7 @@ const data = await res.json();
 2. Aliases exist only for migration compatibility.
 3. `requestId` in responses should be logged client-side for debugging.
 4. For 429 on model route, retry with exponential backoff and respect `Retry-After`.
-5. Verification workflows (`attire`, `government_id`, `certification`) are defined in:
+5. Verification routes are now available in dev under `/core/verifications*`.
+6. Current verification processing is async and returns machine statuses first (`PENDING`, `PROCESSING`, `NEEDS_REVIEW`, etc.).
+7. Full verification design and policy details:
   `docs/MILESTONES/M4/planning/m4-verification-architecture-contract.md`.
--- a/docs/MILESTONES/M4/planning/m4-verification-architecture-contract.md
+++ b/docs/MILESTONES/M4/planning/m4-verification-architecture-contract.md
@@ -1,9 +1,20 @@
 # M4 Verification Architecture Contract (Attire, Government ID, Certification)

-Status: Proposed (next implementation slice)  
+Status: Partially implemented in dev (core endpoints + async in-memory processor)  
 Date: 2026-02-24  
 Owner: Technical Lead

+## Implementation status today (dev)
+1. Implemented routes:
+- `POST /core/verifications`
+- `GET /core/verifications/{verificationId}`
+- `POST /core/verifications/{verificationId}/review`
+- `POST /core/verifications/{verificationId}/retry`
+2. Current processor is in-memory and non-persistent (for fast frontend integration in dev).
+3. Next hardening step is persistent job storage and worker execution before staging.
+4. Attire uses a live Vertex vision model path with `gemini-2.0-flash-lite-001` by default.
+5. Government ID and certification use third-party adapter contracts (provider URL/token envs) and fall back to `NEEDS_REVIEW` when providers are not configured.
+
 ## 1) Goal
 Define a single backend verification pipeline for:
 1. `attire`
@@ -196,6 +207,19 @@ Rules:
 4. Log request and decision IDs for every transition.
 5. For government ID, keep provider response reference and verification timestamp.

+## 11) Provider configuration (environment variables)
+1. Attire model:
+- `VERIFICATION_ATTIRE_PROVIDER=vertex`
+- `VERIFICATION_ATTIRE_MODEL=gemini-2.0-flash-lite-001`
+2. Government ID provider:
+- `VERIFICATION_GOV_ID_PROVIDER_URL`
+- `VERIFICATION_GOV_ID_PROVIDER_TOKEN` (Secret Manager recommended)
+3. Certification provider:
+- `VERIFICATION_CERT_PROVIDER_URL`
+- `VERIFICATION_CERT_PROVIDER_TOKEN` (Secret Manager recommended)
+4. Provider timeout:
+- `VERIFICATION_PROVIDER_TIMEOUT_MS` (default `8000`)
+
 ## 9) Frontend integration pattern
 1. Upload file via existing `POST /core/upload-file`.
 2. Create verification job with returned `fileUri`.