Improve conversation arc snapshots & instrumentation

Make the conversation-arc event snapshot frozen and read-only (return ReadonlyArray) to preserve referential stability for useSyncExternalStore consumers. Cache an EMPTY_FROZEN_SNAPSHOT and freeze snapshots on refresh to prevent accidental mutation. Update types and the useConversationArc result to expose a frozen history.

Integrate useSyncExternalStore in useChartSuggestions to track the arc "enabled" flag, add cross-instance deduping by peeking the store's most recent suggestion-shown event, and ensure signatures reset when recording is disabled so re-enables re-emit the current ranking.

In useChartInterrogation, truncate long queries/answers before recording (configurable constants) and clamp latency to >= 0 to avoid negative deltas from clock skews. Add related comments and documentation for event fields.

Add tests covering dedup across mount cycles and re-emission after disable→enable, and remove an unused import from the docs page.

Overall intent: make the arc buffer stable and safe to share across hooks, avoid accidental mutations and buffer bloat, and reduce duplicate or spurious recorded events.

Author: emeeks

docs/src/pages/features/ConversationArcPage.js

@@ -7,7 +7,6 @@ import {
   disableConversationArc,
   enableConversationArc,
   executivePersona,
-  getConversationArcStore,
   recordAudienceChange,
   useChartSuggestions,
   useConversationArc,

src/components/ai/conversationArc.ts

@@ -109,7 +109,12 @@ export interface InterrogationAskedEvent extends ConversationArcEventBase {
   type: "interrogation-asked"
   /** Chart the question was directed at, if known. */
   component?: string
-  /** Free-form question text, truncated to a reasonable length by the caller. */
+  /**
+   * Question text. The `useChartInterrogation` instrumentation
+   * truncates to ~500 chars before recording so the ring buffer
+   * stays bounded; callers stamping their own events should do the
+   * same.
+   */
   query: string
   /** Optional payload size hint (e.g. summary token count) for diagnostics. */
   contextSize?: number
@@ -119,11 +124,21 @@ export interface InterrogationAnsweredEvent extends ConversationArcEventBase {
   type: "interrogation-answered"
   /** Chart the answer was directed at, if known. */
   component?: string
-  /** Free-form answer text, truncated by the caller. */
+  /**
+   * Answer text. The `useChartInterrogation` instrumentation
+   * truncates to ~2000 chars before recording so multi-kilobyte LLM
+   * responses don't bloat the ring buffer. Callers stamping their
+   * own events should follow the same convention.
+   */
   answer?: string
   /** Number of annotations the response attached, if known. */
   annotationCount?: number
-  /** Round-trip latency in ms from ask to answer, when the caller knows it. */
+  /**
+   * Round-trip latency in ms from ask to answer, clamped to ≥ 0.
+   * The instrumentation measures via `performance.now()` when
+   * available; the `Date.now()` fallback can produce negative
+   * deltas under clock changes, hence the clamp.
+   */
   latencyMs?: number
   /** Set when the response was an error rather than a successful answer. */
   error?: boolean
@@ -174,8 +189,13 @@ export interface ConversationArcStore {
   record(input: ConversationArcEventInput): ConversationArcEvent | null
   /** Returns the current buffer (newest last) and clears it. */
   flush(): ConversationArcEvent[]
-  /** Returns a snapshot of the current buffer without clearing. */
-  getEvents(): ConversationArcEvent[]
+  /**
+   * Returns a frozen, referentially-stable snapshot of the current
+   * buffer. Stable across consecutive calls until the next mutation,
+   * so it can drive `useSyncExternalStore`. Read-only — callers that
+   * need a mutable copy should `.slice()` the result.
+   */
+  getEvents(): ReadonlyArray<ConversationArcEvent>
   /**
    * Subscribe to new events. Returns an unsubscribe function.
    *
@@ -209,16 +229,24 @@ const listeners = new Set<ConversationArcListener>()
 
 // `useSyncExternalStore` requires `getSnapshot()` to return a stable
 // reference until something actually changes. The in-memory buffer is
-// mutated in place on `record()`, so we cache an immutable snapshot
-// next to the buffer and invalidate it on every push / clear / reset.
-// Returning a `slice()` from the public `getEvents()` API still gives
-// callers an array they can mutate without disturbing the buffer.
-let cachedSnapshot: ConversationArcEvent[] = []
+// mutated in place on `record()`, so we cache a frozen snapshot next
+// to the buffer and invalidate it on every push / clear / reset.
+//
+// The snapshot is FROZEN (Object.freeze) because it's shared across
+// every consumer: mutating it would corrupt subsequent snapshots and
+// break `useSyncExternalStore`'s referential-stability contract.
+// Callers that need a mutable copy can `.slice()` the result.
+const EMPTY_FROZEN_SNAPSHOT: ReadonlyArray<ConversationArcEvent> = Object.freeze(
+  []
+) as ReadonlyArray<ConversationArcEvent>
+let cachedSnapshot: ReadonlyArray<ConversationArcEvent> = EMPTY_FROZEN_SNAPSHOT
 let snapshotDirty = false
 
-function refreshSnapshotIfNeeded(): ConversationArcEvent[] {
+function refreshSnapshotIfNeeded(): ReadonlyArray<ConversationArcEvent> {
   if (!snapshotDirty) return cachedSnapshot
-  cachedSnapshot = store ? store.buffer.slice() : []
+  cachedSnapshot = store
+    ? (Object.freeze(store.buffer.slice()) as ReadonlyArray<ConversationArcEvent>)
+    : EMPTY_FROZEN_SNAPSHOT
   snapshotDirty = false
   return cachedSnapshot
 }
@@ -445,7 +473,7 @@ const facade: ConversationArcStore = {
   },
   reset() {
     listeners.clear()
-    cachedSnapshot = []
+    cachedSnapshot = EMPTY_FROZEN_SNAPSHOT
     snapshotDirty = false
     if (!store) {
       // Still fire the change notification so a hook subscribed

src/components/ai/useChartSuggestions.test.tsx

@@ -79,4 +79,40 @@ describe("useChartSuggestions — conversation-arc instrumentation", () => {
     expect((events[0] as { intent?: string }).intent).toBe("trend")
     expect((events[1] as { intent?: string }).intent).toBe("compare-categories")
   })
+
+  it("deduplicates against the store's most recent event across mount cycles", () => {
+    // Simulates the StrictMode mount → unmount → remount pattern: a
+    // per-instance ref resets across the cycle, so cross-instance
+    // dedup is what catches the duplicate.
+    enableConversationArc()
+    const seen: Array<{ type: string }> = []
+    getConversationArcStore().subscribe((e) => seen.push(e))
+
+    const { unmount } = renderHook(() =>
+      useChartSuggestions(TREND_DATA, { intent: "trend" })
+    )
+    unmount()
+    renderHook(() => useChartSuggestions(TREND_DATA, { intent: "trend" }))
+
+    const events = seen.filter((e) => e.type === "suggestion-shown")
+    expect(events).toHaveLength(1)
+  })
+
+  it("re-emits after disable → enable when suggestions are unchanged", () => {
+    // A consumer that enables the arc store mid-session should still
+    // see the current ranking. The disable path drops the signature
+    // so the first re-enable emits.
+    const seen: Array<{ type: string }> = []
+    getConversationArcStore().subscribe((e) => seen.push(e))
+
+    const { rerender } = renderHook(() =>
+      useChartSuggestions(TREND_DATA, { intent: "trend" })
+    )
+    // Hook ran while store was disabled — nothing recorded.
+    expect(seen.filter((e) => e.type === "suggestion-shown")).toHaveLength(0)
+
+    enableConversationArc()
+    rerender()
+    expect(seen.filter((e) => e.type === "suggestion-shown")).toHaveLength(1)
+  })
 })

src/components/ai/useChartSuggestions.ts

@@ -1,10 +1,22 @@
 "use client"
-import { useEffect, useMemo, useRef } from "react"
+import { useEffect, useMemo, useRef, useSyncExternalStore } from "react"
 import type { Datum } from "../charts/shared/datumTypes"
 import { profileData, type ProfileDataOptions } from "./profileData"
 import { suggestCharts, type SuggestChartsOptions } from "./suggestCharts"
 import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes"
-import { getConversationArcStore } from "./conversationArc"
+import {
+  getConversationArcStore,
+  subscribeToConversationArcChange,
+} from "./conversationArc"
+
+// Snapshot fn for the change subscription — `useSyncExternalStore`
+// compares with `Object.is`, so same-value mutations (every record()
+// while enabled, etc.) don't re-render the consumer. Only actual
+// enable/disable flips do. Lives outside the hook so the function
+// reference stays stable.
+const subscribeArc = (onChange: () => void) => subscribeToConversationArcChange(onChange)
+const getArcEnabled = () => getConversationArcStore().enabled
+const getArcEnabledOnServer = () => false
 
 export interface UseChartSuggestionsOptions extends SuggestChartsOptions, ProfileDataOptions {}
 
@@ -60,27 +72,64 @@ export function useChartSuggestions(
   // until a consumer calls `enableConversationArc()` — at which point
   // every recomputation of `useChartSuggestions` lands in the buffer.
   //
-  // Dedup by the (component-list, intent, audience-target) signature
-  // so React's strict-mode double-invocation doesn't double-stamp,
-  // and a stable suggestions list across renders doesn't either.
+  // Dedup happens in two layers:
+  //   1. A per-instance signature ref catches stable-suggestions
+  //      re-renders within one mounted hook.
+  //   2. A peek at the store's most recent `suggestion-shown` event
+  //      catches React StrictMode's mount → unmount → remount cycle
+  //      (where the per-instance ref resets) plus cross-instance
+  //      duplicates from a parent re-mounting children.
+  // The signature also resets when recording is disabled, so a
+  // mid-session enable correctly emits the current suggestions —
+  // tracked via `useSyncExternalStore` so the effect re-runs when
+  // the enabled flag flips.
+  const arcEnabled = useSyncExternalStore(subscribeArc, getArcEnabled, getArcEnabledOnServer)
   const lastSignatureRef = useRef<string | null>(null)
   useEffect(() => {
     if (suggestions.length === 0) {
       lastSignatureRef.current = null
       return
     }
+    if (!arcEnabled) {
+      // Drop the signature so the next enable cycle re-emits the
+      // current ranking. Otherwise a consumer that enables after
+      // the suggester has already run sees no `suggestion-shown` at
+      // all.
+      lastSignatureRef.current = null
+      return
+    }
+    const store = getConversationArcStore()
+
     const audienceTarget = audience?.name ?? (audience ? "custom" : undefined)
     const signature = `${intent ?? ""}|${audienceTarget ?? ""}|${suggestions.map((s) => s.component).join(",")}`
     if (signature === lastSignatureRef.current) return
+
+    // Cross-instance dedup: if the most recent buffered
+    // suggestion-shown event matches this signature, skip. Catches
+    // StrictMode remounts and parent re-mounts that would otherwise
+    // double-stamp the same ranking.
+    const recent = store.getEvents()
+    for (let i = recent.length - 1; i >= 0; i--) {
+      const e = recent[i]
+      if (e.type !== "suggestion-shown") continue
+      const recentIntent = Array.isArray(e.intent) ? e.intent.join(",") : (e.intent ?? "")
+      const recentSignature = `${recentIntent}|${e.audience ?? ""}|${e.components.join(",")}`
+      if (recentSignature === signature) {
+        lastSignatureRef.current = signature
+        return
+      }
+      break // only check the most recent one
+    }
+
     lastSignatureRef.current = signature
-    getConversationArcStore().record({
+    store.record({
       type: "suggestion-shown",
       intent,
       components: suggestions.map((s) => s.component),
       topScore: suggestions[0]?.score,
       audience: audienceTarget,
     })
-  }, [suggestions, intent, audience])
+  }, [suggestions, intent, audience, arcEnabled])
 
   return { suggestions, profile }
 }

src/components/ai/useConversationArc.ts

@@ -141,7 +141,8 @@ export interface UseConversationArcOptions extends EnableConversationArcOptions
  */
 export interface UseConversationArcResult {
   /** Live event buffer, refreshed on every recorded event. */
-  history: ConversationArcEvent[]
+  /** Frozen snapshot of the live event buffer. Read-only; `.slice()` for a mutable copy. */
+  history: ReadonlyArray<ConversationArcEvent>
   /** Reduced summary of the current buffer. Recomputed on each event. */
   summary: ConversationArcSummary
   /** `true` while the store is actively recording. */

src/components/store/useChartInterrogation.ts

@@ -1,6 +1,20 @@
 "use client"
 import { useCallback, useMemo, useRef, useState } from "react"
 import { getConversationArcStore } from "../ai/conversationArc"
+
+// Truncate long strings before they land in the arc ring buffer.
+// LLM responses can be kilobytes; multiply by 1000 events of capacity
+// and the buffer grows fast. Clamping the recorded payload keeps the
+// buffer reasonable while still leaving enough context for replay
+// fixtures and analytics readouts. Slightly under the visible cap so
+// the ellipsis doesn't replace meaningful tail content.
+const MAX_ARC_QUERY_LENGTH = 500
+const MAX_ARC_ANSWER_LENGTH = 2000
+function truncateForArc(text: string | undefined, max: number): string | undefined {
+  if (text == null) return text
+  if (text.length <= max) return text
+  return text.slice(0, max - 1) + "…"
+}
 import type { Datum } from "../charts/shared/datumTypes"
 import { summarizeData, type DataSummary } from "../data/DataSummarizer"
 import { profileData } from "../ai/profileData"
@@ -224,7 +238,7 @@ export function useChartInterrogation(
     getConversationArcStore().record({
       type: "interrogation-asked",
       component: componentNameRef.current,
-      query: trimmed,
+      query: truncateForArc(trimmed, MAX_ARC_QUERY_LENGTH)!,
     })
     try {
       const result = await onQueryRef.current(trimmed, {
@@ -242,9 +256,11 @@ export function useChartInterrogation(
       getConversationArcStore().record({
         type: "interrogation-answered",
         component: componentNameRef.current,
-        answer: result.answer,
+        answer: truncateForArc(result.answer, MAX_ARC_ANSWER_LENGTH),
         annotationCount: result.annotations?.length,
-        latencyMs: Math.round(answeredAt - askedAt),
+        // Clamp to ≥0 in case the Date.now() fallback was used and
+        // the system clock moved backwards between ask and answer.
+        latencyMs: Math.max(0, Math.round(answeredAt - askedAt)),
       })
     } catch (err) {
       const e = err instanceof Error ? err : new Error(String(err))
@@ -258,7 +274,7 @@ export function useChartInterrogation(
         type: "interrogation-answered",
         component: componentNameRef.current,
         error: true,
-        latencyMs: Math.round(answeredAt - askedAt),
+        latencyMs: Math.max(0, Math.round(answeredAt - askedAt)),
       })
     } finally {
       setLoading(false)