@cat-factory/app 0.283.0 → 0.285.0

package/app/stores/notifications.spec.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useNotificationsStore } from '~/stores/notifications'
+import type { Notification } from '~/types/domain'
+
+/**
+ * The live-write map is what stops a lagging refresh clobbering a card that arrived while its
+ * snapshot was in flight. `hydrate` forgets whatever a snapshot has reconciled, which is what
+ * bounds it, so the case that needed a second bound is a long stream period with NO refresh in it.
+ */
+function card(id: string): Notification {
+  return {
+    id,
+    workspaceId: 'ws1',
+    blockId: 'blk1',
+    kind: 'review_wait',
+    status: 'open',
+    title: id,
+    body: '',
+    createdAt: 1,
+  } as unknown as Notification
+}
+
+describe('notifications live-write map', () => {
+  let store: ReturnType<typeof useNotificationsStore>
+  beforeEach(() => {
+    store = useNotificationsStore()
+  })
+
+  it('keeps the newest in-flight writes and forgets the oldest past the bound', () => {
+    for (let i = 0; i < 250; i++) store.upsert(card(`n${i}`))
+    // A refresh whose snapshot predates every one of those writes: what it re-inserts is exactly
+    // what the map still remembers.
+    store.hydrate([], 0)
+    const kept = store.open.map((n) => n.id)
+    expect(kept).toHaveLength(200)
+    expect(kept).toContain('n249')
+    expect(kept).not.toContain('n0')
+  })
+
+  // The bound evicts by the map's INSERTION order, which is only write order because a rewritten
+  // key is re-inserted. A bare `set` keeps a key in its original slot, so the entries rewritten
+  // most (a card whose run keeps advancing, exactly the ones still in flight) would sit at the
+  // head and be evicted FIRST, losing the protection while settled entries survived.
+  it('evicts by write order, so a rewritten card outlives older untouched ones', () => {
+    store.upsert(card('rewritten'))
+    for (let i = 0; i < 199; i++) store.upsert(card(`n${i}`))
+    // Rewriting it makes it the NEWEST write, and the next card is what pushes the map over.
+    store.upsert(card('rewritten'))
+    store.upsert(card('newest'))
+
+    store.hydrate([], 0)
+    const kept = store.open.map((n) => n.id)
+    expect(kept).toContain('rewritten')
+    expect(kept).toContain('newest')
+    // The oldest write that was never touched again is the one that goes.
+    expect(kept).not.toContain('n0')
+  })
+
+  it('still protects a write the in-flight refresh could not have seen', () => {
+    const baseline = store.hydrateBaseline()
+    store.upsert(card('live'))
+    store.hydrate([], baseline)
+    expect(store.open.map((n) => n.id)).toEqual(['live'])
+  })
+})

package/app/stores/notifications.ts

@@ -43,6 +43,31 @@ export const useNotificationsStore = defineStore('notifications', () => {
   /** Last live write per id: the notification to keep, or `null` once it was resolved. */
   const liveWrites = new Map<string, { seq: number; value: Notification | null }>()
 
+  /**
+   * How many in-flight live writes {@link liveWrites} may hold.
+   *
+   * {@link hydrate} forgets every write a snapshot has already reconciled, which is what keeps the
+   * map bounded by what is genuinely in flight. A long stream period that carries only TARGETED
+   * events triggers no hydrate at all, so the map grew one entry per notification for the session.
+   * The bound is on the OLDEST write, and it is safe to drop them: an entry only ever protects a
+   * write from a refresh whose snapshot predates it, and a refresh that far behind resolved long
+   * ago.
+   *
+   * Insertion order is sequence order only because {@link upsert} RE-INSERTS a key it already
+   * holds. A bare `set` on an existing key keeps that key's original slot, so a notification
+   * rewritten many times (exactly the ones still in flight) would sit at the head of the map and
+   * be the FIRST evicted, losing its clobber protection while older, settled entries survived.
+   */
+  const MAX_LIVE_WRITES = 200
+
+  function trimLiveWrites() {
+    while (liveWrites.size > MAX_LIVE_WRITES) {
+      const oldest = liveWrites.keys().next()
+      if (oldest.done) return
+      liveWrites.delete(oldest.value)
+    }
+  }
+
   /**
    * Baseline for {@link hydrate}: capture this BEFORE a refresh's snapshot fetch and pass it
    * back in, so a notification written live while the fetch was in flight survives the hydrate.
@@ -73,7 +98,11 @@ export const useNotificationsStore = defineStore('notifications', () => {
    */
   function upsert(notification: Notification) {
     const isOpen = notification.status === 'open'
+    // Delete before setting, so the map's insertion order stays WRITE order and the trim above
+    // evicts the genuinely oldest entry rather than the most recently rewritten one.
+    liveWrites.delete(notification.id)
     liveWrites.set(notification.id, { seq: ++liveSeq, value: isOpen ? notification : null })
+    trimLiveWrites()
     if (!isOpen) {
       remove(notification.id)
       return

package/app/stores/observability/agentContext.ts

@@ -0,0 +1,128 @@
+import { ref } from 'vue'
+import type { AgentContextSnapshot, AgentSearchQuery } from '~/types/execution'
+import { useSingleFlight } from '~/composables/useSingleFlight'
+
+/** What the two reads need from the store: the workspace binding, nothing else. */
+export interface AgentContextSinkDeps {
+  /** Whether a workspace is bound; a load is a no-op before one is. */
+  ready: () => boolean
+  fetchContext: (executionId: string) => Promise<{ snapshots: AgentContextSnapshot[] }>
+  fetchSearchQueries: (executionId: string) => Promise<{ searchQueries: AgentSearchQuery[] }>
+}
+
+/** Add or remove a key from a reactive `Set` ref, replacing it so the reactivity fires. */
+function withFlag(set: ReturnType<typeof ref<Set<string>>>, key: string, on: boolean) {
+  const next = new Set(set.value)
+  if (on) next.add(key)
+  else next.delete(key)
+  set.value = next
+}
+
+/**
+ * The observability store's AGENT-CONTEXT and SEARCH-QUERY sinks, extracted as one cohesive pair:
+ * both are per-dispatch records the drill-down panel loads on open, neither is pushed live, and
+ * both are dropped together on a board switch. A size-only split mirroring
+ * `createToolCallSinkState`, which sits beside it for the same reason.
+ *
+ * The two differ in ONE way, deliberately: a failed context load is RECORDED, because a swallowed
+ * error there renders as the "no context stored" empty state, which is a claim about the run
+ * rather than a blank tab. A search-query load has no such claim to make.
+ */
+export function createAgentContextSinkState(deps: AgentContextSinkDeps) {
+  /** One in-flight read per (sink, run): a panel's two openers routinely fire in the same tick. */
+  const loads = useSingleFlight<string, void>()
+
+  /** Per-execution-id provided-context snapshot list (newest first). */
+  const contextByExecution = ref<Record<string, AgentContextSnapshot[]>>({})
+  /** Execution ids whose context is currently loading. */
+  const contextLoading = ref<Set<string>>(new Set())
+  /**
+   * Last context-load error message per execution id, or null. Distinguishes a genuine fetch
+   * failure from a run with no captured context: without this, a swallowed error rendered as
+   * the "no context stored" empty state, indistinguishable from success-with-nothing.
+   */
+  const contextErrors = ref<Record<string, string | null>>({})
+  /** Per-execution-id performed-search-query list (newest first). */
+  const searchQueriesByExecution = ref<Record<string, AgentSearchQuery[]>>({})
+  /** Execution ids whose search queries are currently loading. */
+  const searchQueriesLoading = ref<Set<string>>(new Set())
+
+  function contextFor(executionId: string): AgentContextSnapshot[] {
+    return contextByExecution.value[executionId] ?? []
+  }
+  function isContextLoading(executionId: string): boolean {
+    return contextLoading.value.has(executionId)
+  }
+
+  /** Load (or refresh) the per-dispatch provided-context snapshots for a run. */
+  function loadContext(executionId: string): Promise<void> {
+    return loads.run(`context:${executionId}`, () => fetchContext(executionId))
+  }
+
+  async function fetchContext(executionId: string) {
+    if (!deps.ready()) return
+    withFlag(contextLoading, executionId, true)
+    contextErrors.value = { ...contextErrors.value, [executionId]: null }
+    try {
+      const { snapshots } = await deps.fetchContext(executionId)
+      contextByExecution.value = { ...contextByExecution.value, [executionId]: snapshots }
+    } catch (err) {
+      // Record the error so the panel can offer a retry instead of masquerading the failure as
+      // the "no context stored" empty state.
+      contextErrors.value = {
+        ...contextErrors.value,
+        [executionId]: err instanceof Error ? err.message : 'Failed to load context',
+      }
+    } finally {
+      withFlag(contextLoading, executionId, false)
+    }
+  }
+
+  function searchQueriesFor(executionId: string): AgentSearchQuery[] {
+    return searchQueriesByExecution.value[executionId] ?? []
+  }
+  function isSearchQueriesLoading(executionId: string): boolean {
+    return searchQueriesLoading.value.has(executionId)
+  }
+
+  /** Load (or refresh) the performed web-search queries for a run. */
+  function loadSearchQueries(executionId: string): Promise<void> {
+    return loads.run(`searchQueries:${executionId}`, () => fetchSearchQueries(executionId))
+  }
+
+  async function fetchSearchQueries(executionId: string) {
+    if (!deps.ready()) return
+    withFlag(searchQueriesLoading, executionId, true)
+    try {
+      const { searchQueries } = await deps.fetchSearchQueries(executionId)
+      searchQueriesByExecution.value = {
+        ...searchQueriesByExecution.value,
+        [executionId]: searchQueries,
+      }
+    } catch {
+      // Best-effort: the panel shows an empty state; nothing is persisted client-side.
+    } finally {
+      withFlag(searchQueriesLoading, executionId, false)
+    }
+  }
+
+  /** Drop both sinks. Called on a board switch from the observability store's own `reset`. */
+  function resetAgentContext() {
+    contextByExecution.value = {}
+    contextErrors.value = {}
+    searchQueriesByExecution.value = {}
+  }
+
+  return {
+    contextByExecution,
+    contextErrors,
+    contextFor,
+    isContextLoading,
+    loadContext,
+    searchQueriesByExecution,
+    searchQueriesFor,
+    isSearchQueriesLoading,
+    loadSearchQueries,
+    resetAgentContext,
+  }
+}

package/app/stores/observability/toolCalls.ts

@@ -1,5 +1,6 @@
 import { ref } from 'vue'
 import type { RunToolCallFailures, RunToolCallTrajectory } from '~/types/execution'
+import { useSingleFlight } from '~/composables/useSingleFlight'
 
 // The observability store's TOOL-CALL sink, extracted whole because it is one concern with two
 // reads and its own coherence rule between them.
@@ -48,6 +49,12 @@ function withFlag(set: ReturnType<typeof ref<Set<string>>>, key: string, on: boo
 }
 
 export function createToolCallSinkState(deps: ToolCallSinkDeps) {
+  /**
+   * One in-flight read per (sink, run). Both loads below fire on the panel OPENING, and the panel
+   * has two openers that routinely land in the same tick, so each answered twice.
+   */
+  const loads = useSingleFlight<string, void>()
+
   /**
    * Per-execution-id trajectory PREFIX (oldest first, the order the agent worked in) with the
    * flag saying whether the run made more calls than it holds.
@@ -98,7 +105,11 @@ export function createToolCallSinkState(deps: ToolCallSinkDeps) {
   }
 
   /** Load (or refresh) the tool-call trajectory for a run. */
-  async function loadToolCalls(executionId: string) {
+  function loadToolCalls(executionId: string): Promise<void> {
+    return loads.run(`trajectory:${executionId}`, () => fetchToolCalls(executionId))
+  }
+
+  async function fetchToolCalls(executionId: string) {
     if (!deps.ready()) return
     withFlag(toolCallsLoading, executionId, true)
     toolCallErrors.value = { ...toolCallErrors.value, [executionId]: null }
@@ -133,7 +144,11 @@ export function createToolCallSinkState(deps: ToolCallSinkDeps) {
    * fresh error would let the panel keep asserting a failure count the backend just refused to
    * confirm.
    */
-  async function loadToolCallFailures(executionId: string) {
+  function loadToolCallFailures(executionId: string): Promise<void> {
+    return loads.run(`failures:${executionId}`, () => fetchToolCallFailures(executionId))
+  }
+
+  async function fetchToolCallFailures(executionId: string) {
     if (!deps.ready()) return
     withFlag(toolCallFailuresLoading, executionId, true)
     toolCallFailureErrors.value = { ...toolCallFailureErrors.value, [executionId]: null }
@@ -155,7 +170,20 @@ export function createToolCallSinkState(deps: ToolCallSinkDeps) {
     }
   }
 
+  /**
+   * Drop every per-run cache. Called on a board SWITCH from the observability store's own
+   * `reset`: an execution id belongs to the board that owns it, and nothing here is evicted
+   * otherwise.
+   */
+  function resetToolCalls() {
+    toolCallsByExecution.value = {}
+    toolCallErrors.value = {}
+    toolCallFailuresByExecution.value = {}
+    toolCallFailureErrors.value = {}
+  }
+
   return {
+    resetToolCalls,
     toolCallsByExecution,
     toolCallErrors,
     toolCallsFor,

package/app/stores/observability.spec.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useObservabilityStore } from '~/stores/observability'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { LlmCallActivity } from '~/types/execution'
+
+/**
+ * The two bounds on a store that would otherwise be a per-session accumulator: live events fold
+ * only into runs whose panel was OPENED, and a board switch drops every run. Both are about
+ * growth, so both are asserted on what SURVIVES rather than on any one row.
+ *
+ * There is deliberately NO third bound capping one run's list. That is asserted too, below: the
+ * rows a cap would evict are the ones the panel exists to show, so a long watched run keeps all
+ * of them.
+ */
+
+/** A live `llmCall` event carrying only what `appendCall` materialises a row from. */
+function activity(id: string, executionId = 'exec1'): LlmCallActivity {
+  return {
+    id,
+    executionId,
+    blockId: 'blk1',
+    agentKind: 'coder',
+    model: 'm',
+    ok: true,
+    phase: 'agent',
+    finishReason: 'stop',
+  } as unknown as LlmCallActivity
+}
+
+describe('observability store growth bounds', () => {
+  beforeEach(() => {
+    useWorkspaceStore().workspaceId = 'ws1'
+    vi.stubGlobal('useApi', () => ({
+      getLlmMetrics: () => Promise.resolve({ calls: [] }),
+    }))
+  })
+
+  it('folds live calls only into runs whose panel has been opened', async () => {
+    const store = useObservabilityStore()
+    store.appendCall(activity('never-opened'))
+    expect(store.callsFor('exec1')).toEqual([])
+
+    await store.load('exec1')
+    store.appendCall(activity('c1'))
+    expect(store.callsFor('exec1').map((c) => c.id)).toEqual(['c1'])
+  })
+
+  // A per-run cap was tried here and removed: whatever it evicted, the panel could no longer
+  // show, and no eviction rule can tell an operator which call they are now missing. The long
+  // watched run is exactly the one worth reading, so it keeps every row.
+  it('never evicts a row from an opened run, however long it runs', async () => {
+    const store = useObservabilityStore()
+    const burst = 1200
+    await store.load('exec1')
+    for (let i = 0; i < burst; i++) store.appendCall(activity(`c${i}`))
+
+    const held = store.callsFor('exec1')
+    expect(held).toHaveLength(burst)
+    // Newest-first, and the oldest call is still there to scroll back to.
+    expect(held[0]!.id).toBe(`c${burst - 1}`)
+    expect(held.at(-1)!.id).toBe('c0')
+  })
+
+  it('keeps every row a persisted read answered with when a live call lands on top', async () => {
+    const persisted = Array.from({ length: 300 }, (_, i) => ({
+      ...activity(`p${i}`),
+      turnIndex: null,
+      promptText: '',
+      promptPrefixCount: 0,
+      promptHash: '',
+      responseText: '',
+      reasoningText: '',
+    }))
+    vi.stubGlobal('useApi', () => ({
+      getLlmMetrics: () => Promise.resolve({ calls: persisted }),
+    }))
+    const store = useObservabilityStore()
+    await store.load('exec1')
+    expect(store.callsFor('exec1')).toHaveLength(300)
+
+    store.appendCall(activity('live'))
+    expect(store.callsFor('exec1')).toHaveLength(301)
+    expect(store.callsFor('exec1')[0]!.id).toBe('live')
+  })
+
+  it('evicts every per-run cache on a board switch', async () => {
+    const store = useObservabilityStore()
+    await store.load('exec1')
+    store.appendCall(activity('c1'))
+    expect(store.callsFor('exec1')).toHaveLength(1)
+
+    store.reset()
+    // Back to "never opened": the run is gone, so a stray live event for it folds nowhere.
+    store.appendCall(activity('c2'))
+    expect(store.callsFor('exec1')).toEqual([])
+    expect(store.callsByExecution).toEqual({})
+  })
+})

package/app/stores/observability.ts

@@ -1,13 +1,10 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
-import type {
-  AgentContextSnapshot,
-  AgentSearchQuery,
-  LlmCallActivity,
-  LlmCallMetric,
-} from '~/types/execution'
+import type { LlmCallActivity, LlmCallMetric } from '~/types/execution'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { createToolCallSinkState } from '~/stores/observability/toolCalls'
+import { createAgentContextSinkState } from '~/stores/observability/agentContext'
+import { useSingleFlight } from '~/composables/useSingleFlight'
 
 /**
  * LLM observability state: the full per-call model activity for a run (prompts,
@@ -23,6 +20,13 @@ export const useObservabilityStore = defineStore('observability', () => {
   const api = useApi()
   const workspace = useWorkspaceStore()
 
+  /**
+   * One in-flight read per run for the call log below. Its load is triggered by a panel OPENING,
+   * and two openers in one tick is the normal case (the window and its shell, a deep link plus the
+   * click behind it), so it fired twice for one answer. The extracted sinks hold their own.
+   */
+  const loads = useSingleFlight<string, void>()
+
   /**
    * The TOOL-CALL sink, extracted whole: two reads at two different bounds, plus the rule that
    * keeps them apart (see `observability/toolCalls.ts`). The store owns the workspace binding and
@@ -34,22 +38,28 @@ export const useObservabilityStore = defineStore('observability', () => {
     fetchFailures: (executionId) => api.getToolCallFailures(workspace.requireId(), executionId),
   })
 
-  /** Per-execution-id call list (newest first). */
-  const callsByExecution = ref<Record<string, LlmCallMetric[]>>({})
-  /** Per-execution-id provided-context snapshot list (newest first). */
-  const contextByExecution = ref<Record<string, AgentContextSnapshot[]>>({})
-  /** Execution ids whose context is currently loading. */
-  const contextLoading = ref<Set<string>>(new Set())
   /**
-   * Last context-load error message per execution id, or null. Distinguishes a genuine fetch
-   * failure from a run with no captured context: without this, a swallowed error rendered as
-   * the "no context stored" empty state — indistinguishable from success-with-nothing.
+   * The AGENT-CONTEXT and SEARCH-QUERY sinks, extracted as one pair for the same reason as the
+   * tool-call one beside it: both are per-dispatch records the panel loads on open and neither is
+   * pushed live (see `observability/agentContext.ts`).
    */
-  const contextErrors = ref<Record<string, string | null>>({})
-  /** Per-execution-id performed-search-query list (newest first). */
-  const searchQueriesByExecution = ref<Record<string, AgentSearchQuery[]>>({})
-  /** Execution ids whose search queries are currently loading. */
-  const searchQueriesLoading = ref<Set<string>>(new Set())
+  const agentContext = createAgentContextSinkState({
+    ready: () => !!workspace.workspaceId,
+    fetchContext: (executionId) => api.getAgentContext(workspace.requireId(), executionId),
+    fetchSearchQueries: (executionId) => api.getSearchQueries(workspace.requireId(), executionId),
+  })
+
+  /**
+   * Per-execution-id call list (newest first).
+   *
+   * DELIBERATELY UNCAPPED. A per-run cap was tried and removed: the rows it evicted are the ones
+   * this panel exists to show, and no eviction rule can tell an operator which call they now
+   * cannot read. What bounds this store instead costs nothing: {@link appendCall} folds live
+   * events only into runs whose panel has been OPENED, and {@link reset} drops every run on a
+   * board switch. What is left growing is one open run's own log while someone watches it, which
+   * is a list they asked for and are reading.
+   */
+  const callsByExecution = ref<Record<string, LlmCallMetric[]>>({})
   /** Execution ids currently loading. */
   const loading = ref<Set<string>>(new Set())
   /** Execution ids currently exporting. */
@@ -75,7 +85,11 @@ export const useObservabilityStore = defineStore('observability', () => {
   }
 
   /** Load (or refresh) the per-call detail for a run. */
-  async function load(executionId: string) {
+  function load(executionId: string): Promise<void> {
+    return loads.run(`calls:${executionId}`, () => fetchCalls(executionId))
+  }
+
+  async function fetchCalls(executionId: string) {
     if (!workspace.workspaceId) return
     withFlag(loading, executionId, true)
     errors.value = { ...errors.value, [executionId]: null }
@@ -141,58 +155,23 @@ export const useObservabilityStore = defineStore('observability', () => {
       responseText: '',
       reasoningText: '',
     }
-    callsByExecution.value = { ...callsByExecution.value, [executionId]: [row, ...existing] }
-  }
-
-  function contextFor(executionId: string): AgentContextSnapshot[] {
-    return contextByExecution.value[executionId] ?? []
-  }
-  function isContextLoading(executionId: string): boolean {
-    return contextLoading.value.has(executionId)
-  }
-
-  /** Load (or refresh) the per-dispatch provided-context snapshots for a run. */
-  async function loadContext(executionId: string) {
-    if (!workspace.workspaceId) return
-    withFlag(contextLoading, executionId, true)
-    contextErrors.value = { ...contextErrors.value, [executionId]: null }
-    try {
-      const { snapshots } = await api.getAgentContext(workspace.requireId(), executionId)
-      contextByExecution.value = { ...contextByExecution.value, [executionId]: snapshots }
-    } catch (err) {
-      // Record the error so the panel can offer a retry instead of masquerading the failure as
-      // the "no context stored" empty state.
-      contextErrors.value = {
-        ...contextErrors.value,
-        [executionId]: err instanceof Error ? err.message : 'Failed to load context',
-      }
-    } finally {
-      withFlag(contextLoading, executionId, false)
+    callsByExecution.value = {
+      ...callsByExecution.value,
+      [executionId]: [row, ...existing],
     }
   }
 
-  function searchQueriesFor(executionId: string): AgentSearchQuery[] {
-    return searchQueriesByExecution.value[executionId] ?? []
-  }
-  function isSearchQueriesLoading(executionId: string): boolean {
-    return searchQueriesLoading.value.has(executionId)
-  }
-
-  /** Load (or refresh) the performed web-search queries for a run. */
-  async function loadSearchQueries(executionId: string) {
-    if (!workspace.workspaceId) return
-    withFlag(searchQueriesLoading, executionId, true)
-    try {
-      const { searchQueries } = await api.getSearchQueries(workspace.requireId(), executionId)
-      searchQueriesByExecution.value = {
-        ...searchQueriesByExecution.value,
-        [executionId]: searchQueries,
-      }
-    } catch {
-      // Best-effort: the panel shows an empty state; nothing is persisted client-side.
-    } finally {
-      withFlag(searchQueriesLoading, executionId, false)
-    }
+  /**
+   * Drop every per-run cache. Called on a board SWITCH: an execution id is scoped to the board
+   * that owns it, nothing here is part of the snapshot, and no id was ever evicted otherwise, so
+   * without this the session accumulates every run of every board it visits. Each panel re-loads
+   * on open, which is how these were populated in the first place.
+   */
+  function reset() {
+    callsByExecution.value = {}
+    errors.value = {}
+    agentContext.resetAgentContext()
+    toolCalls.resetToolCalls()
   }
 
   /**
@@ -220,21 +199,14 @@ export const useObservabilityStore = defineStore('observability', () => {
   return {
     callsByExecution,
     callsFor,
+    reset,
     isLoading,
     isExporting,
     errors,
     load,
     appendCall,
     downloadExport,
-    contextByExecution,
-    contextErrors,
-    contextFor,
-    isContextLoading,
-    loadContext,
-    searchQueriesByExecution,
-    searchQueriesFor,
-    isSearchQueriesLoading,
-    loadSearchQueries,
+    ...agentContext,
     ...toolCalls,
   }
 })

package/app/stores/requirements/settlement.ts

@@ -0,0 +1,55 @@
+import type { RequirementReview } from '~/types/requirements'
+
+/**
+ * What a requirements review's findings ADD UP TO: how many still need a human, how many the human
+ * answered, and the three dispositions the window's action rail derives from that pair.
+ *
+ * Pure functions of one review, so they live beside the store rather than inside it. They also
+ * share ONE pass over the findings, memoised on the review OBJECT: they compose (`canIncorporate`
+ * asks `allSettled`, which asks `openCount`, and then asks `answeredCount`), so a card rendering a
+ * review's state filtered its item list up to five times. Keying on identity is safe and
+ * self-invalidating because the store REPLACES the review object on every write, so a tallied
+ * object can never change under the cache; a `WeakMap` also lets a superseded review be collected
+ * along with its tally.
+ */
+const tallies = new WeakMap<RequirementReview, { open: number; answered: number }>()
+
+function tally(review: RequirementReview): { open: number; answered: number } {
+  let counts = tallies.get(review)
+  if (!counts) {
+    counts = { open: 0, answered: 0 }
+    for (const item of review.items) {
+      if (item.status === 'open') counts.open++
+      else if (item.status === 'answered' || item.status === 'resolved') counts.answered++
+    }
+    tallies.set(review, counts)
+  }
+  return counts
+}
+
+/** Findings still needing a human (status `open`). */
+export function openCount(review: RequirementReview): number {
+  return tally(review).open
+}
+
+/** Findings the human answered (a reply recorded), which the companion folds in. */
+export function answeredCount(review: RequirementReview): number {
+  return tally(review).answered
+}
+
+/** Every finding is settled (answered or dismissed), none still open. */
+export function allSettled(review: RequirementReview): boolean {
+  return tally(review).open === 0
+}
+
+/** Incorporation is possible: all findings settled AND at least one was answered. */
+export function canIncorporate(review: RequirementReview): boolean {
+  const { open, answered } = tally(review)
+  return open === 0 && answered > 0
+}
+
+/** Proceed (skip the companion) is possible: all findings settled but none answered. */
+export function canProceed(review: RequirementReview): boolean {
+  const { open, answered } = tally(review)
+  return open === 0 && answered === 0
+}