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>

docs/archive/V3.4.md

@@ -0,0 +1,124 @@
+# Shade V3.4 — Observability v2 (OpenTelemetry)
+
+**Status:** Implementert (2026-05-02) — `@shade/observability` 0.1.0,
+hekt inn i sdk/transfer/server/files/core. Off by default; flip
+`SHADE_OTEL_ENABLED=1` for å aktivere.
+**Effort:** M (2–4 uker)
+**Forrige:** V3.1
+**Adresserer:** V2.3 §4
+
+---
+
+## Mål
+
+Gi produksjonsteam **distribuerte spor** rundt `TransferEngine`,
+prekey-routes og `@shade/files` — uten å lekke plaintext-adresser, payloads
+eller eksakte chunk-størrelser. Bygger videre på Prometheus-metrics som
+allerede finnes.
+
+---
+
+## Scope
+
+### Inn
+
+- Opt-in OpenTelemetry-instrumentasjon via `@opentelemetry/api`.
+- Spans rundt:
+  - `TransferEngine.upload` / `.download` (med lane-tags, retry-counts).
+  - `ShadeSessionManager.encrypt` / `.decrypt` (per-peer mutex-akkvisisjon,
+    ratchet-step).
+  - `createPrekeyRoutes` (per route, status-koder).
+  - `@shade/files` op-handlers (har allerede `onMetric` — utvides til OTel).
+- PII-policy-doc: hva som **aldri** logges, hva binnes, hva pseudonymiseres.
+- Sample-policy default off; on med `SHADE_OTEL_ENABLED=1`.
+
+### Ut
+
+- Trace-eksport til SaaS-leverandører (det er deploy-konfig, ikke vår kode).
+- Logg-aggregering — `@shade/server` har allerede strukturert JSON.
+
+---
+
+## Design
+
+### Span-attributter
+
+| Attribute | Verdi |
+|-----------|-------|
+| `shade.peer.hash` | `sha256(address).slice(0, 8)` — stabil pseudonym |
+| `shade.bytes.bin` | binnet — `"≤4KB"`, `"4–64KB"`, `"64KB–1MB"`, `"≥1MB"` |
+| `shade.lane.count` | 1 / 4 / 16 |
+| `shade.retry.count` | int |
+| `shade.error.code` | `SHADE_*`-kode |
+
+**Aldri:** `shade.peer.address`, `shade.payload`, `shade.bytes.exact`.
+
+### API
+
+```ts
+import { withTracer } from '@shade/observability';
+
+const shade = await createShade({
+  ...,
+  observability: withTracer(myTracer, { sample: 0.1 }),
+});
+```
+
+`withTracer()` er no-op hvis `tracer` er `undefined` eller
+`SHADE_OTEL_ENABLED` ikke er satt.
+
+---
+
+## Leveranser
+
+### Pakker
+
+- Ny submodul `@shade/observability` (peer-dep `@opentelemetry/api`).
+- Hooks i `@shade/sdk`, `@shade/transfer`, `@shade/server`, `@shade/files`.
+
+### Tester
+
+- Span emitteres med riktige attributter (mock tracer).
+- Sample-rate respekteres.
+- Off-by-default verifisert.
+- Regex-grep mot recorder fanger plaintext-PII.
+
+### Dokumentasjon
+
+- `docs/observability.md` — setup + PII-policy.
+- `docs/DEPLOYMENT.md` — environment-variabler.
+
+---
+
+## Akseptansekriterier
+
+- [x] Default deploy uten OTel: ingen performance-regresjon (`withTracer`
+      returnerer delt `NOOP_HOOK` når `SHADE_OTEL_ENABLED` ikke er satt).
+- [x] Med OTel på: spans for upload/download (`shade.transfer.upload`,
+      `shade.transfer.download`), prekey-routes (`shade.prekey.request`),
+      session encrypt/decrypt (`shade.session.{encrypt,decrypt}`), og
+      `@shade/files` ops (`shade.files.op`).
+- [x] Automatisert grep-test fanger plaintext-PII i spans
+      (`packages/shade-observability/tests/integration-pii.test.ts` +
+      `packages/shade-transfer/tests/observability.test.ts`,
+      `safeAttribute()` blokkerer fra-utvikler-introduksert PII).
+
+---
+
+## Avhengigheter
+
+- V3.1 — basis-docs.
+
+---
+
+## Risiko
+
+- **Performance-overhead.** Mitiger ved aggressiv default-off + sampling.
+- **PII-lekkasje** hvis utviklere legger til egne attributter. Mitiger ved
+  å publisere "safe attribute"-helpers og PII-linter.
+
+---
+
+## Migrasjon
+
+Ingen — opt-in.