release(v4.0.0): Shade GA — V3.x consolidation + audit prep

V3.1 → V3.12 consolidated and tagged for the first GA release. Wire
format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers
byte-for-byte. The version bump is semantic: audit-cycle complete,
opt-in surface fully exposed, threat model refreshed for every new
surface.

Highlights:
- All 24 @shade/* packages bumped to 4.0.0 in lockstep.
- CHANGELOG 4.0.0 section is the canonical manifest of what landed.
- THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12
  Web-Worker boundary) + residual-risks table refreshed.
- OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox,
  bridge, observer, /metrics, /healthz, /ready.
- MIGRATION 0.3.x → 4.0 documented + smoke-tested against
  shade migrate-storage on a real SQLite DB.
- docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer.
- scripts/soak.ts harness for the GA-stable 2-week soak window.
- All V*.md plans archived under docs/archive/ with Status: Done.
- Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen
  non-realtime stack.

Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green.
Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports
  version 4.0.0 on /health.

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

packages/shade-transport-bridge/src/fallback.ts

@@ -0,0 +1,78 @@
+/**
+ * FallbackBridgeTransport — composes a chain of bridges in priority order.
+ *
+ * On `connect`, tries each bridge in turn. The first one that completes
+ * `connect` without throwing wins; later bridges are dropped on the floor.
+ * If every bridge throws, the composed call re-throws the last error so the
+ * caller sees a real failure rather than silent degradation.
+ *
+ * Fallback is sticky: once a transport is selected, it stays selected for
+ * the lifetime of the instance. To re-evaluate the chain (e.g. after a
+ * proxy goes down), instantiate a new `FallbackBridgeTransport`.
+ */
+
+import type { BridgeConnectOptions, BridgeTransport } from './types.js';
+import { BridgeError } from './errors.js';
+
+export class FallbackBridgeTransport implements BridgeTransport {
+  readonly kind = 'fallback';
+  private active: BridgeTransport | null = null;
+  private connectStarted = false;
+  private disposed = false;
+  private attemptedKinds: string[] = [];
+
+  constructor(private readonly chain: BridgeTransport[]) {
+    if (chain.length === 0) {
+      throw new BridgeError('FallbackBridgeTransport requires a non-empty chain');
+    }
+  }
+
+  /** Stable identifier of the picked transport, e.g. "ws" / "sse" / "long-poll". */
+  get activeKind(): string | null {
+    return this.active?.kind ?? null;
+  }
+
+  /** Read-only list of bridges that were attempted (in order) before success. */
+  get attempts(): readonly string[] {
+    return this.attemptedKinds;
+  }
+
+  async connect(opts: BridgeConnectOptions): Promise<void> {
+    if (this.connectStarted) throw new BridgeError('FallbackBridgeTransport.connect already called');
+    this.connectStarted = true;
+    let lastErr: Error | null = null;
+    for (const bridge of this.chain) {
+      this.attemptedKinds.push(bridge.kind);
+      try {
+        await bridge.connect(opts);
+        if (this.disposed) {
+          // disconnect was called concurrently — clean up the just-connected
+          // bridge before returning.
+          await bridge.disconnect().catch(() => {});
+          return;
+        }
+        this.active = bridge;
+        return;
+      } catch (err) {
+        lastErr = err as Error;
+        // Best-effort cleanup: the bridge may have started reconnect timers
+        // even though `connect` rejected.
+        try {
+          await bridge.disconnect();
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    throw lastErr ?? new BridgeError('all bridges failed to connect');
+  }
+
+  async disconnect(): Promise<void> {
+    this.disposed = true;
+    if (this.active) {
+      const cur = this.active;
+      this.active = null;
+      await cur.disconnect();
+    }
+  }
+}