@goliapkg/sentori-react-native 4.0.0 → 5.1.0

package/src/navigation.ts

@@ -1,35 +1,17 @@
-// Phase 35 sub-C: react-navigation auto-instrumentation.
-// Phase 39 sub-B: the open `react.navigation` span is also made the
-// active span for that screen's lifetime, so the screen's
-// `http.client` spans (and any other startSpan() calls) attach to it
-// as children — one trace per screen instead of one per request.
+// react-navigation auto-instrumentation — v1 role: feed the signal
+// ring (`nav` signals) and remember the current screen so warn
+// surfaces can name where they happened. The span/trace/metric
+// machinery this file used to drive is gone with the APM vocabulary.
 //
 // Mount `useTraceNavigation(navigationRef)` next to your
-// `<NavigationContainer ref={navigationRef}>`. Span names are
-// `<from> → <to>` (or just the route name for the first screen) so
-// the trace list reads as a navigation log.
-//
-// react-navigation is an OPTIONAL peer dependency — apps that don't
-// use it never have to install it. The hook doesn't import from
-// @react-navigation/native; consumers pass in the ref they already
-// have, and we read its state via the public `getCurrentRoute()`.
-//
-// Caveat (active-span on RN is a module variable): requests fired
-// from a `setTimeout` / background poll / detached promise after the
-// screen settled may not see the nav span as active. If you want such
-// a request parented to the current screen, pass it explicitly:
-// `startSpan(op, { parent: activeSpan() })`.
+// `<NavigationContainer ref={navigationRef}>`. react-navigation
+// stays an OPTIONAL peer dependency: the hook never imports from
+// @react-navigation/native — consumers pass the ref they already
+// have and we read `getCurrentRoute()`.
 
 import { useEffect, useRef } from 'react';
 
-import { emitMetric, setActiveSpan, startSpan, type SpanHandle } from '@goliapkg/sentori-core';
-
-import {
-  getNativeFrameCounters,
-  resetNativeFrameCounters,
-} from './native';
-import { track } from './track';
-import { captureStep } from './trail';
+import { pushSignal } from '@goliapkg/sentori-core';
 
 /** Minimal contract: anything with `addListener('state', cb)` and
  *  `getCurrentRoute()` works. The real @react-navigation/native
@@ -39,150 +21,60 @@ export type NavigationRefLike = {
   getCurrentRoute: () => { name: string } | undefined;
 };
 
-/** Process-global last-known route — populated by the navigation
- *  span path below, read by the analytics heartbeat so its per-tick
- *  payload includes the screen the user is on right now. Initial null
- *  when no nav has happened yet (app just launched, dev-launcher,
- *  splash). */
+/** Process-global last-known route — surfaces on detected warns
+ *  (`surface.screen`) and rides nav signals. Null before the first
+ *  navigation (splash, dev launcher). */
 let _lastRoute: null | string = null;
 
+export function currentScreen(): string | undefined {
+  return _lastRoute ?? undefined;
+}
+
+/** Kept for compat with earlier integrations. */
 export function getLastRoute(): null | string {
   return _lastRoute;
 }
 
-/**
- * Subscribe to react-navigation state changes and emit a
- * `react.navigation` span per screen (including the initial one),
- * each a fresh trace root. The span is kept active while the screen
- * is current; child spans created in that window attribute up to it.
- *
- *     import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native'
- *     import { useTraceNavigation } from '@goliapkg/sentori-react-native'
- *
- *     function App() {
- *       const navigationRef = useNavigationContainerRef()
- *       useTraceNavigation(navigationRef)
- *       return <NavigationContainer ref={navigationRef}>{...}</NavigationContainer>
- *     }
- *
- * Each span carries `{ nav.from, nav.to }` tags.
- */
 export function useTraceNavigation(navigationRef: NavigationRefLike): void {
-  // Latest route name we've observed.
   const lastRouteRef = useRef<null | string>(null);
-  // Wall-clock ms when the last screen was entered. Drives dwell time
-  // attached to the leaving span + the next captureStep breadcrumb.
-  const lastRouteEnteredAtRef = useRef<null | number>(null);
-  // Span for the screen the user is currently on. Finished when the
-  // next screen is entered (or on unmount).
-  const openSpanRef = useRef<null | SpanHandle>(null);
+  const enteredAtRef = useRef<null | number>(null);
 
   useEffect(() => {
     if (typeof navigationRef.addListener !== 'function') return;
     if (typeof navigationRef.getCurrentRoute !== 'function') return;
 
-    // Each screen gets its own trace root — detach from whatever the
-    // previous screen's span was (we keep it active, so without
-    // `parent: null` the new one would nest under it).
-    const openScreenSpan = (
-      from: null | string,
-      to: string,
-      prevDwellMs: null | number,
-    ) => {
-      const span = startSpan('react.navigation', {
-        name: from ? `${from} → ${to}` : to,
-        parent: null,
-        tags: { 'nav.from': from ?? '', 'nav.to': to },
-      });
-      openSpanRef.current = span;
-      setActiveSpan(span);
+    const noteScreen = (from: null | string, to: string) => {
+      const dwellMs =
+        enteredAtRef.current !== null
+          ? Math.max(0, Date.now() - enteredAtRef.current)
+          : undefined;
       lastRouteRef.current = to;
       _lastRoute = to;
-      lastRouteEnteredAtRef.current = Date.now();
-      // v0.8.0-b — dwell on the previous screen surfaces in the
-      // session trail. The leaving span's `durationMs` already
-      // carries the same number, but the trail is the most-glanced
-      // surface so we duplicate it as breadcrumb data. No bytes wasted:
-      // a breadcrumb without sessionTrail enabled is a no-op.
-      captureStep(`screen:${to}`, {
-        breadcrumb: {
-          data: prevDwellMs !== null ? { dwellMsPrev: prevDwellMs } : undefined,
-          message: from ? `${from} → ${to}` : to,
-          type: 'navigation',
-        },
-      });
-      // v1.1 chunk B — auto-pageview. Pushed into the track ring
-      // alongside the navigation span so the analytics path sees
-      // every screen entry without app code needing to wire its own
-      // pageview calls. `from`/`dwellMsPrev` ride in props so the
-      // Behavior view (chunk D) can reconstruct the user journey
-      // even when only the track stream is queried.
-      track(
-        '$pageview',
-        prevDwellMs !== null
-          ? { from: from ?? null, dwellMsPrev: prevDwellMs }
-          : { from: from ?? null },
+      enteredAtRef.current = Date.now();
+      pushSignal('nav', {
+        from: from ?? undefined,
         to,
-      );
-    };
-
-    const finishOpenSpanWithDwell = (): null | number => {
-      const span = openSpanRef.current;
-      const enteredAt = lastRouteEnteredAtRef.current;
-      if (!span) return null;
-      const dwellMs = enteredAt !== null ? Math.max(0, Date.now() - enteredAt) : null;
-      // v0.9.4 #1 — drain native frame counters at screen-leave.
-      // Empty/null when native module not linked; tags omitted.
-      const fc = getNativeFrameCounters();
-      const finishTags: Record<string, string> = {};
-      if (dwellMs !== null) finishTags['nav.dwell_ms'] = String(dwellMs);
-      if (fc) {
-        finishTags['vital.slow_frames'] = String(fc.slow);
-        finishTags['vital.frozen_frames'] = String(fc.frozen);
-      }
-      span.finish({
-        status: 'ok',
-        tags: Object.keys(finishTags).length > 0 ? finishTags : undefined,
+        dwellMsPrev: dwellMs,
       });
-      // Reset counters for the next screen.
-      resetNativeFrameCounters();
-      return dwellMs;
     };
 
-    // Open a span for the initial screen so its requests are grouped
-    // too (auth / config / first data load are usually the busiest
-    // screen of a session).
     const initial = navigationRef.getCurrentRoute()?.name ?? null;
-    if (initial !== null) openScreenSpan(null, initial, null);
-    else lastRouteRef.current = null;
+    if (initial !== null) noteScreen(null, initial);
 
     const unsubscribe = navigationRef.addListener('state', () => {
       const next = navigationRef.getCurrentRoute()?.name ?? null;
       const prev = lastRouteRef.current;
       if (next === null || next === prev) return;
-      const dwellMs = finishOpenSpanWithDwell();
-      // v2.1 W2 — emit dwell as a runtime metric so the BI panel
-      // can rank screens by how long users sat on them. Tagged
-      // with `from` + `to` so a release-over-release diff can spot
-      // a 2x dwell regression on Onboarding etc. emit is cheap +
-      // bounded by the core ring cap; if `capture.runtimeMetrics:
-      // false` the flush is off but the ring still records up to
-      // the cap before dropping oldest.
-      if (typeof dwellMs === 'number' && dwellMs >= 0) {
-        emitMetric('runtime.route_nav_ms', dwellMs, {
-          from: prev ?? '',
-          to: next ?? '',
-        });
-      }
-      openScreenSpan(prev, next, dwellMs);
+      noteScreen(prev, next);
     });
 
     return () => {
       unsubscribe();
-      finishOpenSpanWithDwell();
-      openSpanRef.current = null;
-      lastRouteEnteredAtRef.current = null;
-      setActiveSpan(null);
+      enteredAtRef.current = null;
     };
   }, [navigationRef]);
 }
+
+export const __resetForTests = (): void => {
+  _lastRoute = null;
+};

package/src/netinfo.ts

@@ -5,11 +5,11 @@
 // standard library), we subscribe at SDK init time and cache the
 // latest network state. `collectDevice()` reads the cache
 // synchronously at capture time. If the peer isn't installed, the
-// cache stays `undefined` and `device.networkType` is omitted —
+// cache stays `undefined` and `device.network` is omitted —
 // no warning, no crash.
 //
 // We collapse NetInfo's enum into the smaller set the protocol
-// allows (see `Device.networkType` in `sdk/core/src/types.ts`):
+// allows (see `Device.network` in `sdk/core/src/types.ts`):
 // `wifi`, `2g/3g/4g/slow-2g`, `offline`, `unknown`. 5G collapses
 // into `4g` because the schema doesn't have a 5g slot yet; the
 // information loss is acceptable for an analytics dimension.
@@ -18,7 +18,7 @@ import type { Device } from '@goliapkg/sentori-core';
 
 import { isNativeModuleLinked } from './native-loader';
 
-type NetworkType = Device['networkType'];
+type NetworkType = Device['network'];
 
 type NetInfoState = {
   details?: { cellularGeneration?: null | string };

package/src/push.ts

@@ -21,9 +21,8 @@
 //      buffered events while the app is foreground. Pauses on
 //      background, resumes on active, per the perf iron rule.
 
-import { addBreadcrumb, logger } from '@goliapkg/sentori-core'
+import { logger, pushSignal } from '@goliapkg/sentori-core'
 
-import { track } from './track.js'
 // AppState is RN-only; we treat it dynamically so the SDK keeps
 // importing cleanly under Bun / web.
 type AppStateModule = {
@@ -318,13 +317,11 @@ function autoCorrelate(
   // Breadcrumb buffer: O(1) in-memory push. Tag both event types
   // ('received' vs 'opened') so a later captureException shows
   // whether the user actually saw the push.
-  addBreadcrumb('push', { body, msgId, opened: eventType === 'opened', provider, title })
+  pushSignal('push', { body: undefined, msgId, opened: eventType === 'opened', provider, title })
 
   // Track event: reuses the existing SDK event pipeline. Two
   // distinct names so dashboards can separate delivery from open.
   const trackName = eventType === 'opened' ? 'sentori.push.opened' : 'sentori.push.received'
-  track(trackName, { msgId, provider })
-
   // Enqueue ack — batched, see drainAckQueue.
   enqueueAck(msgId)
 }

package/src/rage-tap.tsx

@@ -1,42 +1,89 @@
-// v0.9.0 #12 — rage-tap / multi-click detection.
+// rage_tap — the first detected warn scenario (design.md §3,
+// category A: 「我按了没反应/反复按」).
 //
-// Wrap your app root (typically next to ErrorBoundary) with
-// `<sentori.RageTapCapture>{children}</sentori.RageTapCapture>`.
-// We listen to bubble-phase `onTouchEnd` and emit a `ui.multiClick`
-// breadcrumb when the same native target receives ≥ 3 taps within
-// 800 ms. Pure observation — no event capture, no gesture
-// interference; existing Touchables / Pressables / GestureHandler
-// continue to fire normally.
+// Wrap the app root (next to ErrorBoundary) with
+// `<RageTapCapture>{children}</RageTapCapture>`. Bubble-phase
+// `onTouchEnd` only — pure observation, no gesture interference.
+//
+// Mini-spec: ≥3 taps on the same native target within 800 ms ⇒ one
+// `warn` event, scenario `rage_tap`, surface = current screen +
+// target id, plus a signal-ring entry. Per-target cooldown resets
+// after firing so a frustrated 10-tap burst is one event, not four.
 
 import React, { useCallback, useRef } from 'react';
 import { View, type GestureResponderEvent, type ViewProps } from 'react-native';
 
-import { addBreadcrumb } from './breadcrumbs';
+import { pushSignal, snapshotSignals } from '@goliapkg/sentori-core';
+
+import { getConfig } from './config';
+import { currentScreen } from './navigation';
+import { RAGE_THRESHOLD, RAGE_WINDOW_MS, recordTap } from './rage-tap-detector';
 import {
-  RAGE_THRESHOLD,
-  RAGE_WINDOW_MS,
-  recordTap,
-} from './rage-tap-detector';
+  RESPONSE_WINDOW_MS,
+  SLUGGISH_MS,
+  classifyTap,
+  recordDeadTap,
+  recordSluggish,
+} from './responsiveness-detector';
+import { warnDetected } from './verbs';
 
 export function RageTapCapture({
   children,
   ...rest
 }: ViewProps & { children?: React.ReactNode }): React.JSX.Element {
   const recent = useRef<Map<number, number[]>>(new Map());
+  const deadBuckets = useRef<Map<number, number[]>>(new Map());
+  const sluggishWarns = useRef<Map<number, number>>(new Map());
 
   const onTouchEnd = useCallback((e: GestureResponderEvent) => {
-    const target = e.nativeEvent?.target;
-    if (typeof target !== 'number') return;
-    if (recordTap(recent.current, target, Date.now())) {
-      addBreadcrumb({
-        type: 'user',
-        data: {
-          kind: 'ui.multiClick',
-          target: String(target),
-          taps: RAGE_THRESHOLD,
-          windowMs: RAGE_WINDOW_MS,
-        },
-      });
+    try {
+      const target = e.nativeEvent?.target;
+      if (typeof target !== 'number') return;
+      const tapAt = Date.now();
+      pushSignal('tap', { target });
+
+      // Responsiveness verdict lands after the window closes: the
+      // ring tells us whether the app reacted to this tap at all.
+      setTimeout(() => {
+        try {
+          const screen = currentScreen();
+          // Ring snapshots carry event-relative seconds (one decimal);
+          // rebase them onto the epoch for the classifier.
+          const nowMs = Date.now();
+          const times = snapshotSignals(nowMs)
+            .filter((s) => s.kind !== 'tap')
+            .map((s) => nowMs + s.t * 1000);
+          const outcome = classifyTap(tapAt, times);
+          if (outcome === 'dead' && recordDeadTap(deadBuckets.current, target, Date.now())) {
+            warnDetected(
+              'dead_button',
+              { screen, element: String(target) },
+              { windowMs: RESPONSE_WINDOW_MS },
+            );
+          } else if (
+            outcome === 'sluggish' &&
+            recordSluggish(sluggishWarns.current, target, Date.now())
+          ) {
+            warnDetected(
+              'sluggish_button',
+              { screen, element: String(target) },
+              { thresholdMs: SLUGGISH_MS },
+            );
+          }
+        } catch {
+          // detector bug must never surface
+        }
+      }, RESPONSE_WINDOW_MS + 50);
+
+      if (!recordTap(recent.current, target, tapAt)) return;
+      if (getConfig()?.detect.rageTap === false) return;
+      warnDetected(
+        'rage_tap',
+        { screen: currentScreen(), element: String(target) },
+        { taps: RAGE_THRESHOLD, windowMs: RAGE_WINDOW_MS },
+      );
+    } catch {
+      // A detector bug must never reach the host's touch pipeline.
     }
   }, []);
 

package/src/replay-screens.ts

@@ -0,0 +1,95 @@
+// B-type visual replay — a rolling ring of low-bitrate screenshots.
+//
+// OFF by default (privacy + the client-zero-cost rule): enable
+// with `init({ replayScreens: true })`. One frame every 2.5 s at
+// 360 px / q≈0.35 runs 10-20 KB, so the 60 s window a triage
+// actually wants is ~24 frames and a few hundred KB — and those
+// bytes only ever leave the device when an error/warn fires,
+// stapled to that event as a `screens` attachment.
+//
+// Older native builds have no `captureReplayFrame`; the ring then
+// simply stays empty (one warn) — wireframe replay still works.
+
+import { logger } from '@goliapkg/sentori-core';
+
+import { maskedNativeIds } from './mask';
+import { captureNativeReplayFrame } from './native';
+
+type CaptureFn = typeof captureNativeReplayFrame;
+let _capture: CaptureFn = captureNativeReplayFrame;
+
+/** Frame cadence. 2.5 s keeps the main-thread cost of a capture
+ *  (~1-3 ms) far under the 1 % occupancy budget. */
+const TICK_INTERVAL_MS = 2_500;
+/** Long edge of a replay frame, px. Enough to read a screen's
+ *  layout and large text; deliberately not enough to read a
+ *  document over someone's shoulder. */
+const FRAME_LONG_EDGE_PX = 360;
+/** JPEG/WebP quality for replay frames. */
+const FRAME_QUALITY = 0.35;
+
+type ScreenFrame = { t: number; base64: string; mediaType: string };
+
+let _ring: ScreenFrame[] = [];
+let _capacity = 0;
+let _timer: ReturnType<typeof setInterval> | null = null;
+let _capturing = false;
+
+/** Start the ring. `windowSeconds` is how far back the replay
+ *  reaches when an event fires. */
+export const startScreenReplay = (windowSeconds: number): void => {
+  if (_timer !== null || windowSeconds <= 0) return;
+  _capacity = Math.max(1, Math.ceil((windowSeconds * 1000) / TICK_INTERVAL_MS));
+  _timer = setInterval(() => {
+    void tick();
+  }, TICK_INTERVAL_MS);
+  logger.debug('replay-screens', `ring started: ${_capacity} slots / ${windowSeconds}s`);
+};
+
+const tick = async (): Promise<void> => {
+  // Never overlap captures: a slow frame skips a beat instead of
+  // queueing main-thread work.
+  if (_capturing) return;
+  _capturing = true;
+  try {
+    const frame = await _capture(maskedNativeIds(), FRAME_LONG_EDGE_PX, FRAME_QUALITY);
+    if (frame) {
+      _ring.push({ t: Date.now(), ...frame });
+      if (_ring.length > _capacity) _ring.splice(0, _ring.length - _capacity);
+    }
+  } finally {
+    _capturing = false;
+  }
+};
+
+/** Drain the ring into the wire form: NDJSON, one frame per line,
+ *  `t` rewritten to seconds-before-now (negative, so the player
+ *  reads "-42.5s → 0s"). Returns null when empty. The ring is NOT
+ *  cleared — a second error two seconds later should still see
+ *  the minute before it. */
+export const drainScreenReplay = (): null | string => {
+  if (_ring.length === 0) return null;
+  const now = Date.now();
+  return _ring
+    .map((f) =>
+      JSON.stringify({
+        t: Number(((f.t - now) / 1000).toFixed(1)),
+        mediaType: f.mediaType,
+        base64: f.base64,
+      }),
+    )
+    .join('\n');
+};
+
+export const __resetForTests = (): void => {
+  if (_timer !== null) clearInterval(_timer);
+  _timer = null;
+  _ring = [];
+  _capacity = 0;
+  _capturing = false;
+  _capture = captureNativeReplayFrame;
+};
+
+export const __setCaptureForTests = (fn: CaptureFn): void => {
+  _capture = fn;
+};

package/src/replay.ts

@@ -15,9 +15,8 @@
 //
 // Wire schema: docs/replay-encoding-v2.md.
 
-import { logger, startSpan } from '@goliapkg/sentori-core';
+import { logger } from '@goliapkg/sentori-core';
 
-import { getRegisteredMaskQuery } from './mask';
 import { describeWireframeNative } from './native';
 
 declare const __DEV__: boolean | undefined;
@@ -153,18 +152,11 @@ function captureTick(): void {
     logger.debug('replay', 'tick: first invocation');
     _firstTickLogged = true;
   }
-  let tickSpan: ReturnType<typeof startSpan> | null = null;
-  try {
-    tickSpan = startSpan('sentori.replay.tick', { name: 'tick' });
-  } catch {
-    // never fatal
-  }
   try {
     const maskIds = readMaskIds();
     const snapshotJson = _nativeMod?.captureWireframe?.(maskIds);
     if (typeof snapshotJson !== 'string' || snapshotJson.length === 0) {
       handleEmptyTick(snapshotJson);
-      tickSpan?.finish({ status: 'ok' });
       return;
     }
 
@@ -173,7 +165,6 @@ function captureTick(): void {
       snapshot = JSON.parse(snapshotJson) as NativeFrame;
     } catch (e) {
       logger.warn('replay', 'tick: native JSON parse failed', e);
-      tickSpan?.finish({ status: 'error' });
       return;
     }
 
@@ -185,10 +176,7 @@ function captureTick(): void {
     if (typeof __DEV__ !== 'undefined' && __DEV__) {
       diagnosticForTick(snapshot, snapshotJson.length);
     }
-    tickSpan?.finish({ status: 'ok' });
   } catch (e) {
-    if (e instanceof Error) tickSpan?.setTag('error.message', e.message);
-    tickSpan?.finish({ status: 'error' });
     logger.warn('replay', 'tick threw', e);
   }
 }
@@ -326,13 +314,8 @@ function diagnosticForTick(snapshot: NativeFrame, snapshotBytes: number): void {
 }
 
 function readMaskIds(): string[] {
-  const q = getRegisteredMaskQuery();
-  if (!q) return [];
-  try {
-    return q();
-  } catch {
-    return [];
-  }
+  // Masking returns with a v1 privacy pass; nothing masks today.
+  return [];
 }
 
 type ReplayNativeModule = {

package/src/responsiveness-detector.ts

@@ -0,0 +1,66 @@
+// dead_button / sluggish_button — pure detection logic.
+//
+// A tap is judged by what the signal ring records after it: any
+// non-tap signal (navigation, network, a trace point) inside the
+// response window counts as the app reacting.
+//
+//   - responsive: a reaction within SLUGGISH_MS.
+//   - sluggish:   a reaction, but slower than SLUGGISH_MS.
+//   - dead:       no reaction at all inside RESPONSE_WINDOW_MS.
+//
+// One dead tap is usually decoration (backgrounds, labels), so a
+// dead_button warn needs DEAD_THRESHOLD dead taps on the SAME
+// target inside DEAD_WINDOW_MS — a user repeatedly poking one
+// unresponsive control, at a slower cadence than a rage tap.
+// Sluggish warns are per-target cooldown-limited so one slow
+// button files one issue, not one per tap.
+
+export const RESPONSE_WINDOW_MS = 1_500;
+export const SLUGGISH_MS = 1_000;
+export const DEAD_THRESHOLD = 3;
+export const DEAD_WINDOW_MS = 30_000;
+export const SLUGGISH_COOLDOWN_MS = 60_000;
+
+export type TapOutcome = 'dead' | 'responsive' | 'sluggish';
+
+/** Judge one tap by the ring signals that followed it.
+ *  `signalTimes` are the timestamps (ms) of every non-tap signal
+ *  recorded after `tapAt`. */
+export function classifyTap(tapAt: number, signalTimes: number[]): TapOutcome {
+  const first = signalTimes
+    .filter((t) => t > tapAt && t - tapAt <= RESPONSE_WINDOW_MS)
+    .sort((a, b) => a - b)[0];
+  if (first === undefined) return 'dead';
+  return first - tapAt > SLUGGISH_MS ? 'sluggish' : 'responsive';
+}
+
+/** Per-target dead-tap bookkeeping. Returns true when this dead tap
+ *  crosses the warn threshold (and clears the bucket so the next
+ *  warn needs a fresh run of dead taps). */
+export function recordDeadTap(
+  buckets: Map<number, number[]>,
+  target: number,
+  now: number,
+): boolean {
+  const fresh = (buckets.get(target) ?? []).filter((t) => now - t <= DEAD_WINDOW_MS);
+  fresh.push(now);
+  if (fresh.length >= DEAD_THRESHOLD) {
+    buckets.delete(target);
+    return true;
+  }
+  buckets.set(target, fresh);
+  return false;
+}
+
+/** Per-target sluggish cooldown. Returns true when a warn should
+ *  fire (and stamps the cooldown). */
+export function recordSluggish(
+  lastWarnAt: Map<number, number>,
+  target: number,
+  now: number,
+): boolean {
+  const last = lastWarnAt.get(target);
+  if (last !== undefined && now - last < SLUGGISH_COOLDOWN_MS) return false;
+  lastWarnAt.set(target, now);
+  return true;
+}

package/src/scope.ts

@@ -0,0 +1,50 @@
+// Ambient scope: the current user and the context patch, attached
+// to every outgoing event. Two verbs own this state (user() and
+// context()); everything else reads it.
+
+import { hashIdentities, safeFn } from '@goliapkg/sentori-core';
+import type { User } from '@goliapkg/sentori-core';
+
+let _user: User | null = null;
+let _userKey: string | undefined;
+let _context: Record<string, unknown> = {};
+let _hashGeneration = 0;
+
+export const setUser = safeFn('user', function setUser(u: User | null): void {
+  _user = u;
+  _userKey = undefined;
+  const generation = ++_hashGeneration;
+  if (u === null) return;
+  // The wire carries only a salted hash — raw identity never leaves
+  // the device (breadth × depth needs distinctness, not identity).
+  // Hashing is async (WebCrypto); the verb stays synchronous and the
+  // key lands a tick later. Events sent in that gap simply carry no
+  // userKey, which only under-counts breadth briefly.
+  void hashIdentities({ email: u.email, id: u.id })
+    .then((hashes) => {
+      if (generation === _hashGeneration) {
+        _userKey = hashes.id ?? hashes.email;
+      }
+    })
+    .catch(() => {
+      // NEVER rule: no key beats a raw identity on the wire.
+    });
+});
+
+export const patchContext = safeFn('context', function patchContext(
+  patch: Record<string, unknown>,
+): void {
+  _context = { ..._context, ...patch };
+});
+
+export const currentUserKey = (): string | undefined => _userKey;
+
+export const currentContext = (): Record<string, unknown> | undefined =>
+  Object.keys(_context).length > 0 ? { ..._context } : undefined;
+
+export const __resetForTests = (): void => {
+  _user = null;
+  _userKey = undefined;
+  _context = {};
+  _hashGeneration++;
+};