Capture guarded human gestures and verify agent administration

docs/interaction-evidence.md

@@ -2,20 +2,25 @@
 
 Administrators separately enable `evidence.enabled`, `captureDownloads` and
 `captureInteractions` through reviewed signed policy. All are off by default.
-Interaction capture currently covers confirmed guarded copy/cut/paste and
-completed agent clicks. It is not a recording of every physical user click.
+Interaction capture covers confirmed guarded copy/cut/paste, completed agent
+clicks and trusted clicks/gesture-associated form events on the active main-frame
+page. Human events are marked `observed`, including prevented events; this never
+claims transmission or completion of a page's asynchronous effect.
 
 Ordinary clipboard audit distinguishes authorization before the effect from
 completion after the effect. Protected completion metadata contains website
 origin, opaque session ID, action, structural target tag/role, bounded viewport
 coordinates and optional byte count. Paths, queries, fragments, field values,
 document text, selectors, labels and content hashes are excluded. Sensitive
-fields do not produce this capture.
+fields do not produce this capture. Sensitive forms are excluded as a whole,
+including password/file/hidden controls and bounded credential/card markers.
+Form observation also requires a recent trusted click or Enter gesture and active
+user activation; `requestSubmit()` alone does not establish a human gesture.
 
 Agent completion capture is a separate audit phase from RPC completion; two
 events do not mean two clicks. The native fixture verifies one click effect.
 The server binds evidence to the accepted device event, action, source, session
-and completed outcome. New writes reject raw interaction content. Existing
+and the correct observed/completed outcome. New writes reject raw interaction content. Existing
 encrypted legacy evidence remains readable through restricted audited access.
 
 The source event and typed protected payload are persisted in one DPAPI-protected
@@ -27,10 +32,22 @@ ordinary audit and separately allowed download evidence. Existing retained
 records still follow retention, legal-hold and purpose-bound analyst access.
 
 Debug traces measure capture, challenge, encryption, send and acknowledgement,
-with correlated server decrypt/store phases. These timing spans carry no raw
+with correlated server decrypt/store phases. Queue delivery resumes each record's
+own trace parent rather than inheriting a different event's flusher context.
+Observer install/drain/dispose phases have separate bounded debug spans.
+These timing spans carry no raw
 interaction contents. Evidence retention is independent of diagnostics.
 
-Remaining coverage includes general physical interaction observation, controlled
-content capture, all browser convenience clipboard paths and a proven scoped
+The private isolated-world observer has no page-visible bridge. It expires after
+1.5 seconds without a privileged drain, caps its queue at 16, allows a burst of
+20 and replenishes at 10 events per second. Main validates every drained record
+and rejects changed documents, activation, policy, ownership and overlays. A
+visual reinspection of the same document does not invalidate captured metadata.
+Rate/queue losses emit a durable bounded-capture warning and a diagnostic count;
+capture is not a complete forensic replay. Subframes, shadow internals, all
+keyboard actions and asynchronous effect reconstruction remain outside coverage.
+
+Remaining coverage includes controlled content capture,
+all browser convenience clipboard paths and a proven scoped
 credential-submission exception. Do not assume this feature is full page replay
 or blanket password-field authorization.