Stabilize diagnostic export and preserve authorized policy continuity

docs/diagnostics-backpressure.md

@@ -0,0 +1,86 @@
+# Bounded diagnostics and policy continuity
+
+Browser diagnostics are optional and centrally authorized. They never replace
+the protected durable security audit. This change keeps inspection, release
+checks, audit encryption and `fsync` unchanged.
+
+## Browser exports
+
+Each signal has one active SDK export and a FIFO bounded by the signed
+`maxQueueSize` in waiting records, plus its active batch. Queue expiry uses the
+original record timestamps; waiting does not refresh authorization or age.
+Overflow, expiry, timeout and cancellation remain actual counted failures.
+The process retains lifetime totals, fixed reason counts and at most 32 cloned
+failure facts, including queue age. Error text, bodies, endpoints and credentials
+are absent. Completed callbacks cannot count twice.
+
+Flush calls share one promise per generation. Dispatch waits for the next event
+loop turn after completion because the SDK frees its internal concurrency slot
+after invoking the callback. Real successful HTTP drain tests cover that race,
+including exports arriving during the callback-to-settlement interval.
+
+An already verified, unexpired policy can keep diagnostics active through a
+publication when the full exporter configuration and device context remain
+identical, except for policy version. Policy and bookmark signatures and device
+assignment are checked first. Operation contexts are immutable snapshots:
+existing spans and logs keep their original version; new root operations use
+the new version. Explicit operation metadata still overrides defaults.
+
+Changed endpoint, mode, sampling, limits, identity or disabled diagnostics still
+cancel active requests and waiting callbacks immediately. Expired previous
+authority cannot use continuity. Cancellation remains visible in lifetime
+failure accounting; it is not silently relabeled as successful delivery.
+
+## Protected local development collector
+
+The loopback receiver bounds unfinished OTLP requests to eight and their shared
+body buffers to 8 MiB, with a 2 MiB per-body limit. Idle incomplete requests time
+out after ten seconds. Overload returns fixed503; oversized bodies return413.
+Aborts release reservations and remove waiting work. Commit work is serialized
+without changing the encryption, path guards, rotation or synchronous `fsync`.
+HTTP200 still follows actual encrypted persistence; storage failure returns507.
+
+Admission summaries expose counts, bytes, queue wait and commit duration. Native
+event-loop delay is metadata only. This is bounded admission and observability,
+not a claim that synchronous disk work has been moved into a worker.
+
+Startup verifies an existing exact private directory ACL without resetting it:
+current user owns it, inheritance is disabled, and its sole explicit rule grants
+that user FullControl with file/directory inheritance. Unsafe ACLs require a
+successful protection and verification step or prevent startup. This avoids a
+redundant owner-setting operation that failed under a non-elevated token.
+The existing DPAPI key and encrypted archives remain intact across restart.
+This developer receiver is not a production SIEM or remote collector.
+
+## Current Windows evidence
+
+The final frozen main/diagnostics source passed:
+
+- 784 source tests, zero failures or skips, and ESLint with zero warnings.
+- Actual native clipboard/upload enforcement:17 checks and five additional
+  checks after a real process restart;13 public requests, zero confidential
+  deliveries and two exactly received public files.
+- Real local Gemma: all four semantic receiver checks, with confidential
+  paraphrases blocked and no external model inspection.
+- Window and first-statement dedicated Worker WebTransport attempts through
+  three signed policy phases: six Created and six Closed security records,
+  zero managed packets/bytes, and three successful public HTTPS submissions.
+- Zero current and lifetime export failures in all those browser processes.
+
+Actual semantic file trace `e5ebf887a1ad8d90f065739a86cd2261` shows a9.04s
+request containing several independently inspected representations. Individual
+local stages took1.69–1.93s; semantic stages0.78–1.03s, with audit commit12–16ms.
+These are measured profiling targets, not permission to remove required checks.
+Collector checkpoint:578 commits, zero commit failures/rejections, max queue
+wait14.87ms and max commit42.18ms, with no active or waiting request at inspection.
+
+Ignored evidence: `artifacts/diagnostics-continuity-final-suite.log`,
+`context-reuse-{public,mvp,semantic,wt}-native.log`, the corresponding native
+proof JSON files and `diagnostics-continuity-collector-checkpoint.json`.
+Use `node --test --test-concurrency=2 tests/*.test.mjs` for the full Windows suite.
+
+Historical failed runs remain retained. Their earlier three2s export timeouts
+cannot be causally explained retroactively by these later successful runs.
+The separately measured SDK drain race and policy-retirement losses have direct
+regression coverage. The native WebRTC engine crash remains a separate open
+Windows MVP gate; see [the current scope](windows-dlp-mvp.md).