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>

src/lib/storage/migrate.ts

@@ -32,14 +32,31 @@ export interface StorageKeyTable {
 }
 
 /**
- * Phase 6a ships an empty list — `berth_pdf_versions` and `brochure_versions`
- * land in Phase 6b. Add new entries here when new file-bearing tables are
- * introduced. The migration script reads each named table via raw SQL so it
- * does not need to import every domain's Drizzle schema.
+ * Tables that hold blob references the migration script must walk.
+ *
+ * Column naming is intentionally inconsistent across the schema for historical
+ * reasons:
+ *   - `files.storage_path`             (oldest table, named before §4.7a rename)
+ *   - `berth_pdf_versions.storage_key` (Phase 6b — followed the new convention)
+ *   - `brochure_versions.storage_key`  (Phase 6b)
+ *   - `gdpr_exports.storage_key`       (worker-uploaded export bundle)
+ *
+ * None of these tables carry a per-row content-type column today
+ * (`files.mime_type` exists but isn't the same semantics — it's the
+ * original-upload mime, not the stored object's Content-Type header). The
+ * migration falls back to `application/octet-stream` when
+ * `contentTypeColumn` is omitted; the byte stream is what matters for the
+ * sha256-verified round-trip and the original Content-Type is already
+ * persisted on the source object's S3 metadata.
+ *
+ * The `report_snapshots` table called out in the audit does not exist yet.
+ * Add it here when it lands.
  */
 export const TABLES_WITH_STORAGE_KEYS: StorageKeyTable[] = [
-  // { table: 'berth_pdf_versions', keyColumn: 'storage_key', pkColumn: 'id', contentTypeColumn: 'content_type' },
-  // { table: 'brochure_versions',  keyColumn: 'storage_key', pkColumn: 'id', contentTypeColumn: 'content_type' },
+  { table: 'files', keyColumn: 'storage_path', pkColumn: 'id' },
+  { table: 'berth_pdf_versions', keyColumn: 'storage_key', pkColumn: 'id' },
+  { table: 'brochure_versions', keyColumn: 'storage_key', pkColumn: 'id' },
+  { table: 'gdpr_exports', keyColumn: 'storage_key', pkColumn: 'id' },
 ];
 
 const ADVISORY_LOCK_KEY = 0xc7000a01;

src/lib/storage/s3.ts

@@ -30,6 +30,32 @@ interface S3BackendConfig {
   forcePathStyle?: boolean;
 }
 
+/**
+ * Socket timeout wrapper. The `minio` JS client does not propagate
+ * `fetchWithTimeout` semantics into `putObject` / `getObject` / `statObject`
+ * (its underlying `node:http(s)` agent has no default request-timeout), so a
+ * TCP-blackhole between the worker and the storage host can stall a job
+ * indefinitely. We race every call against a deadline and fail loud — the
+ * caller's retry/error path is far better than a stuck queue worker.
+ *
+ * The MinIO client doesn't accept an AbortSignal on these methods, so the
+ * underlying request keeps running in the background after timeout. That's
+ * acceptable here: the alternative is keeping the worker hung forever; the
+ * underlying socket is closed by Node's keep-alive timeouts on the next
+ * idle cycle.
+ */
+const STORAGE_DEFAULT_TIMEOUT_MS = 30_000;
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: NodeJS.Timeout | null = null;
+  const timeout = new Promise<T>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`S3 ${label} timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+
 interface ResolvedConfig {
   endpoint: string;
   port: number;
@@ -114,10 +140,18 @@ export class S3Backend implements StorageBackend {
     // is missing — we'll create it. Otherwise we throw so the boot fails
     // fast and the deployment-time misconfig is loud.
     try {
-      const exists = await client.bucketExists(resolved.bucket);
+      const exists = await withTimeout(
+        client.bucketExists(resolved.bucket),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        'bucketExists',
+      );
       if (!exists) {
         if (process.env.MINIO_AUTO_CREATE_BUCKET === 'true') {
-          await client.makeBucket(resolved.bucket, resolved.region);
+          await withTimeout(
+            client.makeBucket(resolved.bucket, resolved.region),
+            STORAGE_DEFAULT_TIMEOUT_MS,
+            'makeBucket',
+          );
           logger.info(
             { bucket: resolved.bucket, endpoint: resolved.endpoint },
             'S3 bucket auto-created (MINIO_AUTO_CREATE_BUCKET=true)',
@@ -153,16 +187,24 @@ export class S3Backend implements StorageBackend {
     const buffer = Buffer.isBuffer(body) ? body : await streamToBuffer(body);
     const sha256 = opts.sha256 ?? createHash('sha256').update(buffer).digest('hex');
 
-    await this.client.putObject(this.bucket, key, buffer, buffer.length, {
-      'Content-Type': opts.contentType,
-    });
+    await withTimeout(
+      this.client.putObject(this.bucket, key, buffer, buffer.length, {
+        'Content-Type': opts.contentType,
+      }),
+      STORAGE_DEFAULT_TIMEOUT_MS,
+      `putObject(${key})`,
+    );
 
     return { key, sizeBytes: buffer.length, sha256 };
   }
 
   async get(key: string): Promise<NodeJS.ReadableStream> {
     try {
-      return await this.client.getObject(this.bucket, key);
+      return await withTimeout(
+        this.client.getObject(this.bucket, key),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        `getObject(${key})`,
+      );
     } catch (err) {
       const code = (err as { code?: string } | null)?.code;
       if (code === 'NoSuchKey' || code === 'NotFound') {
@@ -174,7 +216,11 @@ export class S3Backend implements StorageBackend {
 
   async head(key: string): Promise<{ sizeBytes: number; contentType: string } | null> {
     try {
-      const stat = await this.client.statObject(this.bucket, key);
+      const stat = await withTimeout(
+        this.client.statObject(this.bucket, key),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        `statObject(${key})`,
+      );
       const meta = (stat.metaData ?? {}) as Record<string, string>;
       const contentType =
         meta['content-type'] ?? meta['Content-Type'] ?? 'application/octet-stream';
@@ -188,7 +234,11 @@ export class S3Backend implements StorageBackend {
 
   async delete(key: string): Promise<void> {
     try {
-      await this.client.removeObject(this.bucket, key);
+      await withTimeout(
+        this.client.removeObject(this.bucket, key),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        `removeObject(${key})`,
+      );
     } catch (err) {
       const code = (err as { code?: string } | null)?.code;
       if (code === 'NotFound' || code === 'NoSuchKey') return;
@@ -232,14 +282,26 @@ export class S3Backend implements StorageBackend {
     const sentinelKey = `_health/${Date.now()}.txt`;
     const payload = Buffer.from('ok', 'utf8');
     try {
-      await this.client.putObject(this.bucket, sentinelKey, payload, payload.length, {
-        'Content-Type': 'text/plain',
-      });
-      const stat = await this.client.statObject(this.bucket, sentinelKey);
+      await withTimeout(
+        this.client.putObject(this.bucket, sentinelKey, payload, payload.length, {
+          'Content-Type': 'text/plain',
+        }),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        `healthCheck:put(${sentinelKey})`,
+      );
+      const stat = await withTimeout(
+        this.client.statObject(this.bucket, sentinelKey),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        `healthCheck:stat(${sentinelKey})`,
+      );
       if (stat.size !== payload.length) {
         return { ok: false, error: 'sentinel size mismatch' };
       }
-      await this.client.removeObject(this.bucket, sentinelKey);
+      await withTimeout(
+        this.client.removeObject(this.bucket, sentinelKey),
+        STORAGE_DEFAULT_TIMEOUT_MS,
+        `healthCheck:remove(${sentinelKey})`,
+      );
       return { ok: true };
     } catch (err) {
       return { ok: false, error: (err as Error).message };