fix(integration): webhook v2 events, storage migrate, test theatre

- F1: DOCUMENT_DECLINED handler (v2 Decline vs Reject) — routes to same
  handler as DOCUMENT_REJECTED until product refines downstream UX
- Add RECIPIENT_VIEWED / RECIPIENT_SIGNED v2-alias cases with telemetry
  logging so we see when v2 deployments emit them
- D1: populate TABLES_WITH_STORAGE_KEYS (files, berth_pdf_versions,
  brochure_versions, gdpr_exports) — was an empty list, migrated 0 files
- MinIO putObject/getObject/statObject/removeObject socket timeout wrapper
  to prevent worker hangs on TCP blackhole (30s deadline)
- E1: convert test.skip on smoke-setup infra failure to throw new Error
  so green-skipped silence becomes a real test failure (Playwright
  doesn't expose vitest's expect.fail)
- Regression tests: folderId='' → null transform, applyEntityRestoredSuffix
  no-op (never-archived), syncEntityFolderName collision loop past (2)

Note: matching .env.example documentation (D2 — bare DOCUMENSO_API_URL,
DOCUMENSO_API_VERSION, MINIO_AUTO_CREATE_BUCKET, DOCUMENSO_TEMPLATE_ID_EOI,
recipient role id vars) prepared but not committed — pre-commit hook
blocks .env*. Apply manually via the separate .env workflow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/unit/document-folders-validators.test.ts

@@ -5,6 +5,7 @@ import {
   moveFolderSchema,
   moveDocumentToFolderSchema,
 } from '@/lib/validators/document-folders';
+import { listDocumentsSchema } from '@/lib/validators/documents';
 
 describe('document-folder validators', () => {
   it('accepts a valid create payload', () => {
@@ -37,4 +38,49 @@ describe('document-folder validators', () => {
     expect(moveDocumentToFolderSchema.safeParse({ folderId: null }).success).toBe(true);
     expect(moveDocumentToFolderSchema.safeParse({ folderId: 'abc' }).success).toBe(true);
   });
+
+  // ─── folderId='' → null transform (regression) ─────────────────────────────
+  //
+  // The frontend's URL-query builder emits `?folderId=` (empty string) when
+  // the user picks "All documents" — without the transform, Zod would parse
+  // this as the literal string "" and the SQL layer would try to JOIN on an
+  // empty folder id, returning zero rows instead of the expected unscoped
+  // result. The transform lives on `listDocumentsSchema` (and
+  // `listFilesSchema`); we exercise the documents one here.
+  describe("listDocumentsSchema folderId='' transform", () => {
+    const BASE = { page: 1, limit: 20, sort: 'createdAt', order: 'desc', includeArchived: 'false' };
+
+    it("coerces folderId='' to null so the empty-string query param means 'unscoped'", () => {
+      const result = listDocumentsSchema.safeParse({ ...BASE, folderId: '' });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.folderId).toBeNull();
+      }
+    });
+
+    it('leaves a non-empty folderId untouched', () => {
+      const id = crypto.randomUUID();
+      const result = listDocumentsSchema.safeParse({ ...BASE, folderId: id });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.folderId).toBe(id);
+      }
+    });
+
+    it('accepts an explicit folderId=null (no transform needed)', () => {
+      const result = listDocumentsSchema.safeParse({ ...BASE, folderId: null });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.folderId).toBeNull();
+      }
+    });
+
+    it('treats an absent folderId as undefined (not the same as null)', () => {
+      const result = listDocumentsSchema.safeParse(BASE);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.folderId).toBeUndefined();
+      }
+    });
+  });
 });