docs: align flow docs with code reality + create 35 implementation issue files

Flow docs updated (11 files):
- Delivery Confirmation: reversed actor roles (buyer generates, seller verifies),
  fixed endpoint paths (/delivery-code/generate, /delivery-code/verify)
- Passkey (WebAuthn): removed stub/simulated-key claims; real @simplewebauthn/server
  attestation is implemented; refresh tokens are persisted
- Dispute: corrected resolve schema (action enum), removed non-existent statuses,
  documented security gaps (no role guards on status/resolve/assign), route shadowing,
  all socket events are TODO stubs
- Seller Offer: corrected all endpoint paths, removed 'active' status, documented
  withdraw dead code, missing seller history page, select-offer notification gap
- Notification: corrected mark-all-read method+path, fixed GET /:id broken lookup,
  added unread-count-update socket event
- Authentication: corrected rate limiter (counts all attempts), axios 403 not handled,
  deleteAccount wrong endpoint bug, changePassword no UI
- Password Reset: corrected 6-digit code (not 8), documented no-complexity gap on
  reset-with-code vs token reset
- Payment Flow DePay: /create→/save, removed phantom sub-routes, SIM_ bypass risk,
  PaymentProvider type gap, getProviderIntentEndpoint routing bug
- Payment Flow SHKeeper: removed phantom polling endpoint, fixed release/refund paths
- Purchase Request: added pending_payment/active statuses, fixed sellers/attachments
  endpoints, corrected socket events, PUT→PATCH bug
- Escrow: documented dispute resolve does not touch escrow, route shadowing, confirm-delivery auth gap

Issues created (35 files in Issues/):
- 9 security issues (critical) including: dispute privilege escalation ×4,
  unauthenticated payment/scanner endpoints ×2, SIM_ production bypass,
  confirm-delivery ownership gap
- 26 additional major/critical bugs covering broken endpoints, missing features,
  data integrity gaps, and frontend-backend mismatches

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

04 - Flows/Purchase Request Flow.md

@@ -5,6 +5,9 @@ related_models: ["[[PurchaseRequest]]", "[[Category]]", "[[Address]]", "[[Seller
 related_apis: ["POST /api/marketplace/purchase-requests", "GET /api/marketplace/purchase-requests", "PATCH /api/marketplace/purchase-requests/:id"]
 ---
 
+> [!warning] Audit — 2026-05-29
+> This document was corrected against the live codebase. Key changes: status enum updated (added `pending_payment`, `active`; removed undocumented `finalized`/`archived`); urgency values expanded to include `urgent`; sellers endpoint corrected; attachment upload endpoint corrected; `request-cancelled` socket event removed (non-existent); `new-purchase-request` fan-out target corrected to shared `sellers` room; socket room join/leave events documented; description minimum corrected to 5 chars; PUT vs PATCH mismatch flagged as known bug; two frontend actions hitting non-existent backend endpoints flagged as not implemented.
+
 # Purchase Request Flow
 
 A **buyer** drafts and publishes a purchase request describing what they want to source. Once published, the request becomes visible to sellers (either all sellers or a curated subset), kicking off [[Seller Offer Flow]].
@@ -31,7 +34,10 @@ Status progression is enforced by `STATUS_PROGRESSION_ORDER` in `PurchaseRequest
 ```mermaid
 stateDiagram-v2
     [*] --> pending: createPurchaseRequest()
-    pending --> received_offers: first SellerOffer saved\nSellerOfferService.createOffer
+    pending --> active: request activated
+    pending --> pending_payment: payment initiated
+    pending_payment --> active: payment confirmed
+    active --> received_offers: first SellerOffer saved\nSellerOfferService.createOffer
     received_offers --> in_negotiation: buyer/seller chat\n(counter-offer, see [[Negotiation Flow]])
     in_negotiation --> received_offers: counter rejected
     received_offers --> payment: Request Network payment confirmed\n(selected offer)
@@ -41,26 +47,27 @@ stateDiagram-v2
     delivery --> delivered: buyer enters delivery code
     delivered --> confirming: optional auto-release timer
     confirming --> completed: escrow released to seller
-    completed --> finalized: ratings exchanged
-    finalized --> archived: 30 days idle
     pending --> cancelled: buyer cancels (any pre-payment status)
+    active --> cancelled
     received_offers --> cancelled
     in_negotiation --> cancelled
     cancelled --> [*]
-    archived --> [*]
+    completed --> [*]
 ```
 
-Terminal statuses: `completed`, `finalized`, `archived`, `cancelled` (`PurchaseRequestService.ts:28`).
+Terminal statuses: `completed`, `cancelled` (`PurchaseRequestService.ts:28`).
+
+> [!note] Statuses `finalized` and `archived` do NOT exist in the frontend `IPurchaseRequest` type and are not live statuses. They are not part of the active state machine.
 
 ## Step-by-step narrative
 
 ### Multi-step wizard
 
 1. Buyer clicks "New request" in the dashboard sidebar and lands at `/dashboard/request/new`.
-2. **Step 1 — Basic info** (`steps/request-basic-info-step.tsx`): title (5–200 chars), description (20–2000 chars), category selection (dropdown populated from `GET /api/marketplace/categories`).
+2. **Step 1 — Basic info** (`steps/request-basic-info-step.tsx`): title (5–200 chars), description (5–2000 chars, **minimum is 5 characters** per frontend Zod schema — not 20), category selection (dropdown populated from `GET /api/marketplace/categories`).
 3. **Step 2 — Details** (`steps/request-details-step.tsx`): optional product link, size, color, quantity, free-form specifications (key/value pairs), AI-assisted description generation (calls `POST /api/ai/generate-description` if the user clicks the magic-wand button — see `backend/src/services/ai/`).
-4. **Step 3 — Budget** (`steps/request-budget-step.tsx`): min/max in chosen currency (default USDT), urgency (low/medium/high), preferred sellers (typeahead bound to `GET /api/users/sellers`; `"all"` means public).
-5. **Step 4 — Review** (`steps/request-review-step.tsx`): summary; user can attach a saved address (`GET /api/addresses`) or enter a one-off `deliveryInfo.address`. Upload optional attachments via `POST /api/files/upload` — returns URLs persisted into `attachments[]`.
+4. **Step 3 — Budget** (`steps/request-budget-step.tsx`): min/max in chosen currency (default USDT), urgency (`low | medium | high | urgent`), preferred sellers (typeahead bound to `GET /api/marketplace/sellers`; `"all"` means public).
+5. **Step 4 — Review** (`steps/request-review-step.tsx`): summary; user can attach a saved address (`GET /api/addresses`) or enter a one-off `deliveryInfo.address`. Upload optional attachments via `POST /api/marketplace/purchase-requests/:id/attachments` — returns URLs persisted into `attachments[]`.
 6. **Draft vs. publish** — The wizard always POSTs on submit; drafts are not first-class today (the local wizard state is the "draft"). The persisted record is immediately `status: "pending"` and visible to sellers.
 
 ### Submission
@@ -73,9 +80,9 @@ Terminal statuses: `completed`, `finalized`, `archived`, `cancelled` (`PurchaseR
    - Builds and saves the `PurchaseRequest` document with `status: "pending"`.
 9. **Notify the buyer**: `notificationService.notifyPurchaseRequestCreated()` fires asynchronously (no `await`) — an info notification appears in the buyer's bell-icon dropdown.
 10. **Fan-out to sellers** (`notifyAllSellersAboutNewRequest`, `:190-249`):
-    - If `isPublic`: `User.find({ role: "seller", status: "active" })`.
-    - Otherwise: only the curated `preferredSellerIds`.
-    - Iterates with **50 ms stagger** between notifications to avoid overwhelming Mongo/Socket.IO.
+    - If `isPublic`: emits `new-purchase-request` to the shared **`sellers` room** (all connected sellers receive it in a single emit — no per-seller iteration for the socket event itself).
+    - For per-seller in-app notifications (bell icon): `User.find({ role: "seller", status: "active" })` OR only the curated `preferredSellerIds`.
+    - Iterates with **50 ms stagger** between notification writes to avoid overwhelming Mongo.
     - For each seller: `notificationService.createNotification(...)` writes a `Notification` doc AND emits via Socket.IO (`actionUrl: /dashboard/seller/marketplace/request/{id}`).
 11. **Real-time fan-out** is also performed when sellers eventually act on the request (offers, payments) via `emitPurchaseRequestUpdate(requestId, eventType, data)` (`PurchaseRequestService.ts:53-71`) and `emitOfferUpdate` in [[Seller Offer Flow]].
 
@@ -112,7 +119,7 @@ sequenceDiagram
         BE-->>FE: { description }
     end
     opt attachments
-        FE->>BE: POST /api/files/upload
+        FE->>BE: POST /api/marketplace/purchase-requests/:id/attachments
         BE-->>FE: { url }
     end
     B->>FE: Click "Publish"
@@ -123,7 +130,8 @@ sequenceDiagram
     BE->>DB: PurchaseRequest.create({status: "pending"})
     DB-->>BE: savedRequest
     BE->>N: notifyPurchaseRequestCreated(buyer, requestId)
-    par fan-out to sellers (staggered 50ms)
+    par fan-out to sellers (staggered 50ms for DB writes)
+        BE->>IO: emit 'new-purchase-request' to 'sellers' room (public requests)
         BE->>DB: User.find({role:"seller", status:"active"}) (or preferred)
         BE->>N: createNotification(seller_i, ...)
         N->>IO: emit user-{seller_i} 'new-notification'
@@ -131,7 +139,7 @@ sequenceDiagram
     end
     BE-->>FE: 201 { request }
     FE-->>B: Redirect /dashboard/buyer/requests/{id}
-    IO-->>S1: 'new-notification' (sellers receive in real time)
+    IO-->>S1: 'new-purchase-request' (sellers room) + 'new-notification' (per-user)
 ```
 
 ## API calls
@@ -140,15 +148,23 @@ sequenceDiagram
 |---|---|---|
 | `POST` | `/api/marketplace/purchase-requests` | Create the request |
 | `GET` | `/api/marketplace/categories` | Step 1 dropdown |
-| `GET` | `/api/users/sellers` | Step 3 preferred-sellers typeahead |
+| `GET` | `/api/marketplace/sellers` | Step 3 preferred-sellers typeahead |
 | `GET` | `/api/addresses` | Step 4 saved addresses |
-| `POST` | `/api/files/upload` | Attachments |
+| `POST` | `/api/marketplace/purchase-requests/:id/attachments` | Attachments upload |
 | `POST` | `/api/ai/generate-description` | Optional AI-assisted description |
 | `GET` | `/api/marketplace/purchase-requests` | Listing (buyer's own and seller's filtered view) |
 | `GET` | `/api/marketplace/purchase-requests/:id` | Detail page (joins payment data) |
 | `PATCH` | `/api/marketplace/purchase-requests/:id` | Generic update (status, attachments, etc.) |
 | `DELETE` | `/api/marketplace/purchase-requests/:id` | Cancel (only before payment) |
 
+> [!bug] ⚠️ KNOWN BUG — PUT vs PATCH mismatch
+> The frontend `updatePurchaseRequest` action sends `PUT /api/marketplace/purchase-requests/:id`, but the backend only registers a `PATCH` handler for that route. The `PUT` call will receive a `404` or `405` response. The backend handler must be updated to also accept `PUT`, or the frontend action must be changed to use `PATCH`.
+
+> [!warning] ⚠️ NOT IMPLEMENTED — Frontend actions with no backend endpoints
+> The following frontend actions target backend routes that do not exist:
+> - `searchPurchaseRequests` → `GET /marketplace/purchase-requests/search` — this endpoint does not exist. Use query parameters on the standard list endpoint (`GET /api/marketplace/purchase-requests?q=...`) instead.
+> - `getMarketplaceStats` → `GET /marketplace/purchase-requests/stats` — this endpoint does not exist. No stats aggregation route is registered.
+
 ## Database writes
 
 - **`purchaserequests` collection**: full insert. Subsequent status transitions and `selectedOfferId` updates happen in [[Seller Offer Flow]], [[PRD - Request Network In-House Checkout]], and [[Delivery Confirmation Flow]].
@@ -157,16 +173,26 @@ sequenceDiagram
 
 ## Socket events emitted
 
+- **`new-purchase-request`** → `sellers` room for public purchase requests (shared room, single broadcast; emitted by `notifyAllSellersAboutNewRequest`).
 - **`new-notification`** → `user-{sellerId}` for each notified seller (via `NotificationService.emitRealTimeNotification`).
-- **`purchase-request-update`** → `request-{id}` on status changes (`emitPurchaseRequestUpdate`, `PurchaseRequestService.ts:53-71`).
+- **`purchase-request-update`** → `request-{id}` on status changes (`emitPurchaseRequestUpdate`, `PurchaseRequestService.ts:53-71`). Cancellation emits this event with `eventType: 'status-changed'` — there is **no** separate `request-cancelled` event.
 - **`seller-offer-update`** → `seller-{id}` when an offer is created against this request (see [[Seller Offer Flow]]).
-- **`request-cancelled`** → `user-{buyerId}` and `user-{sellerId}` when the buyer cancels (`PurchaseRequestService.ts:671-693`).
+
+### Socket room join/leave events
+
+| Event | Direction | Emitted by |
+|---|---|---|
+| `join-request-room` | client → server | Buyer detail page on mount (subscribes to `request-{id}`) |
+| `join-seller-room` | client → server | `useSellerMarketplaceSocket` on mount |
+| `leave-seller-room` | client → server | `useSellerMarketplaceSocket` on unmount |
+| `join-buyer-room` | client → server | Buyer socket hook on mount |
+| `leave-buyer-room` | client → server | Buyer socket hook on unmount |
 
 ## Side effects
 
 - One Mongo write per notification (potentially N+1 for a large seller base — mitigated by the 50 ms stagger). For mass markets this should be batched.
 - The buyer is auto-subscribed to the `request-{id}` Socket.IO room on the detail page mount (frontend emits `join-request-room`).
-- If `urgency === "high"`, the notification message uses the high-priority template — visible in [[Notification Flow]].
+- If `urgency === "high"` or `urgency === "urgent"`, the notification message uses the high-priority template — visible in [[Notification Flow]].
 
 ## Error / edge cases
 
@@ -180,7 +206,7 @@ sequenceDiagram
 - **Seller calls GET listing without `sellerId` query** → logs `"No sellerId provided - returning ALL requests!"` (`:348`) and returns the full set. Frontend always supplies `sellerId` for seller dashboards; missing it is a bug worth catching.
 
 > [!tip] Status progression is forward-only
-> Once `status` reaches `payment`, you cannot put it back to `received_offers` even via PATCH. The only escape hatches are the terminal statuses (`cancelled`, `archived`, etc.) and admin tools.
+> Once `status` reaches `payment`, you cannot put it back to `received_offers` even via PATCH. The only escape hatches are the terminal statuses (`cancelled`) and admin tools.
 
 ## Linked flows