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-core/src/session.ts

@@ -26,6 +26,16 @@ import {
 import { NoSessionError } from './errors.js';
 import { computeFingerprint, shortFingerprint } from './fingerprint.js';
 import { ShadeEventEmitter, shortHash } from './events.js';
+import {
+  ATTR_ERROR_CODE,
+  ATTR_OP,
+  ATTR_PEER_HASH,
+  ATTR_RESULT,
+  NOOP_HOOK,
+  peerHash,
+  type ObservabilityHook,
+  type Span,
+} from '@shade/observability';
 
 const enc = new TextEncoder();
 const dec = new TextDecoder();
@@ -60,6 +70,7 @@ export class ShadeSessionManager {
   private registrationId: number = 0;
   private currentSignedPreKeyId: number = 0;
   private readonly events?: ShadeEventEmitter;
+  private readonly observability: ObservabilityHook;
   /**
    * Per-address operation chain. Both encrypt and decrypt mutate ratchet
    * state in place (counter, DH key, skipped-keys cache); concurrent
@@ -72,11 +83,46 @@ export class ShadeSessionManager {
   constructor(
     private readonly crypto: CryptoProvider,
     private readonly storage: StorageProvider,
-    options: { events?: ShadeEventEmitter } = {},
+    options: { events?: ShadeEventEmitter; observability?: ObservabilityHook } = {},
   ) {
     if (options.events !== undefined) {
       this.events = options.events;
     }
+    this.observability = options.observability ?? NOOP_HOOK;
+  }
+
+  /**
+   * Wrap a per-peer crypto op in a PII-safe span. The span captures the
+   * mutex-acquire latency separately from the inner crypto work so a
+   * "ratchet contention" pathology shows up clearly in traces.
+   */
+  private async withSpan<T>(
+    op: 'encrypt' | 'decrypt',
+    address: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    const span: Span = this.observability.startSpan(`shade.session.${op}`, {
+      [ATTR_OP]: op,
+      [ATTR_PEER_HASH]: peerHash(address),
+    });
+    const lockStart = nowMs();
+    try {
+      return await this.runUnderPeerLock(address, async () => {
+        span.setAttribute('shade.lock.wait_ms', Math.round(nowMs() - lockStart));
+        const result = await fn();
+        span.setAttribute(ATTR_RESULT, 'ok');
+        span.setStatus('ok');
+        return result;
+      });
+    } catch (err) {
+      span.setAttribute(ATTR_RESULT, 'error');
+      span.setAttribute(ATTR_ERROR_CODE, sessionErrorCodeOf(err));
+      span.recordException(err);
+      span.setStatus('error');
+      throw err;
+    } finally {
+      span.end();
+    }
   }
 
   /**
@@ -396,7 +442,7 @@ export class ShadeSessionManager {
    * Subsequent messages are standard RatchetMessages.
    */
   async encrypt(address: string, plaintext: string): Promise<ShadeEnvelope> {
-    return this.runUnderPeerLock(address, async () => {
+    return this.withSpan('encrypt', address, async () => {
       const session = await this.storage.getSession(address);
       if (!session) throw new NoSessionError(address);
 
@@ -444,7 +490,7 @@ export class ShadeSessionManager {
    * Decrypt a message from a peer. Handles both PreKeyMessage and RatchetMessage.
    */
   async decrypt(address: string, envelope: ShadeEnvelope): Promise<string> {
-    return this.runUnderPeerLock(address, async () => {
+    return this.withSpan('decrypt', address, async () => {
       if (envelope.type === 'prekey') {
         return this.decryptPreKeyMessage(address, envelope.content as PreKeyMessage);
       }
@@ -522,3 +568,18 @@ function arraysEqual(a: Uint8Array, b: Uint8Array): boolean {
   }
   return true;
 }
+
+function nowMs(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+function sessionErrorCodeOf(err: unknown): string {
+  if (err === null || err === undefined) return 'SHADE_UNKNOWN';
+  if (typeof err === 'object') {
+    const code = (err as { code?: unknown }).code;
+    if (typeof code === 'string' && code.length > 0) return code;
+    const name = (err as { name?: unknown }).name;
+    if (typeof name === 'string' && name.length > 0) return name;
+  }
+  return 'SHADE_UNKNOWN';
+}