@cat-factory/app 0.277.1 → 0.277.2

package/app/stores/workspace.spec.ts

@@ -45,12 +45,17 @@ beforeEach(() => {
 
 // Regression for the live-push CLOBBER race: `board`-type stream events (and the on-connect
 // resync) each trigger a full-snapshot `refresh()`, and `hydrate` REPLACES the block list. Two
-// refreshes can be in flight at once (events >300ms apart, or a resync + a board event), and if a
-// slower/staler fetch resolves AFTER a newer one, its hydrate used to clobber the newer state —
-// dropping a just-spawned block whose only live delivery was the coarse board event, so its card
-// never reappeared (no further event to restore it). This surfaced as an intermittent e2e timeout
-// where a spawned task/document card never rendered. `refresh()` now stamps each call so only the
-// latest-issued one commits; this test pins that a stale out-of-order refresh can't win.
+// refreshes used to be in flight at once (events >300ms apart, or a resync + a board event), and a
+// slower/staler fetch resolving AFTER a newer one clobbered the newer state, dropping a
+// just-spawned block whose only live delivery was the coarse board event, so its card never
+// reappeared (no further event to restore it). That surfaced as an intermittent e2e timeout where a
+// spawned task/document card never rendered.
+//
+// `refresh()` now goes through the funnel, which SERIALIZES: a call arriving during a fetch waits
+// for a follow-up fetch issued after it rather than racing beside it. So the out-of-order clobber
+// is structurally unreachable rather than detected and discarded, and what this test pins is the
+// property that replaced the sequence stamp: overlapping refreshes never interleave, and the board
+// ends on the LAST snapshot fetched. `refreshFunnel.spec.ts` covers the coalescing rules directly.
 
 /** Minimal block — only the fields the board store's index getters read. */
 function block(id: string, over: Partial<Block> = {}): Block {
@@ -102,20 +107,19 @@ function snapshot(
 }
 
 describe('workspace store refresh ordering', () => {
-  it('a stale refresh resolving out of order does not clobber a newer one', async () => {
+  it('serializes overlapping refreshes so the board ends on the last snapshot fetched', async () => {
     const frame = block('f1')
     const spawned = block('spawned', { level: 'task', parentId: 'f1' })
-    let resolveStale!: (s: WorkspaceSnapshot) => void
-    let resolveFresh!: (s: WorkspaceSnapshot) => void
+    let resolveFirst!: (s: WorkspaceSnapshot) => void
 
     const getWorkspace = vi
       .fn()
       // 1) switchTo establishes the active board (no spawned block yet).
       .mockResolvedValueOnce(snapshot('ws1', [frame]))
-      // 2) the EARLIER-issued refresh (stale: still no spawned block) — resolved LAST below.
-      .mockReturnValueOnce(new Promise<WorkspaceSnapshot>((r) => (resolveStale = r)))
-      // 3) the LATER-issued refresh (fresh: the spawned block landed) — resolved FIRST below.
-      .mockReturnValueOnce(new Promise<WorkspaceSnapshot>((r) => (resolveFresh = r)))
+      // 2) the first refresh's fetch: still no spawned block, and held open below.
+      .mockReturnValueOnce(new Promise<WorkspaceSnapshot>((r) => (resolveFirst = r)))
+      // 3) the follow-up fetch, ISSUED ONLY AFTER (2) settles, which is why it sees the spawn.
+      .mockResolvedValueOnce(snapshot('ws1', [frame, spawned]))
     vi.stubGlobal('useApi', () => ({ getWorkspace }))
 
     const ws = useWorkspaceStore()
@@ -123,21 +127,23 @@ describe('workspace store refresh ordering', () => {
     await ws.switchTo('ws1')
     expect(board.getBlock('spawned')).toBeUndefined()
 
-    // Two overlapping refreshes: the later-issued one carries the fresher snapshot, but the
-    // earlier-issued (stale) one resolves last — the exact out-of-order clobber the guard blocks.
-    const stalePass = ws.refresh()
-    const freshPass = ws.refresh()
-    resolveFresh(snapshot('ws1', [frame, spawned]))
-    resolveStale(snapshot('ws1', [frame]))
-    await Promise.all([stalePass, freshPass])
+    // A second refresh arriving mid-fetch does NOT start a racing fetch: one is outstanding.
+    const first = ws.refresh()
+    const second = ws.refresh()
+    expect(getWorkspace).toHaveBeenCalledTimes(2)
 
-    // The fresh snapshot won and the stale one was discarded: the spawned card survives.
+    resolveFirst(snapshot('ws1', [frame]))
+    await Promise.all([first, second])
+
+    // The follow-up ran after the first settled and its snapshot is what the board holds, so a
+    // caller that refreshed after spawning the block sees it.
+    expect(getWorkspace).toHaveBeenCalledTimes(3)
     expect(board.getBlock('spawned')).toBeDefined()
   })
 
-  // Regression for the SECOND clobber axis: a refresh vs an interleaved live `upsert`. The
-  // `refreshSeq` guard above only orders refreshes against each OTHER — it does nothing when a
-  // single refresh's (slow) fetch overlaps a targeted live event. A run's status transitions
+  // Regression for the SECOND clobber axis: a refresh vs an interleaved live `upsert`. Serializing
+  // refreshes orders them against each OTHER and does nothing when a single refresh's (slow) fetch
+  // overlaps a targeted live event. A run's status transitions
   // (…→ in_progress → pr_ready/done) arrive as `execution`-event `board.upsert`s; a refresh whose
   // snapshot was FETCHED while the block was still `in_progress` must not, on resolving later,
   // replace that block back to the stale status. This was the reliable-under-CI-latency e2e

package/app/stores/workspace.ts

@@ -14,6 +14,7 @@ import type { LiveWriteBaselines } from '~/stores/workspace/hydrate'
 import { applySnapshotToStores, resetPerBoardCaches } from '~/stores/workspace/hydrate'
 import { createWorkspaceCommands } from '~/stores/workspace/commands'
 import { createInfraSetupState } from '~/stores/workspace/infraSetup'
+import { createRefreshFunnel } from '~/stores/workspace/refreshFunnel'
 import { markBoot } from '~/utils/bootMarks'
 import { retryWhileBackendUnreachable } from '~/utils/backendReady'
 
@@ -198,34 +199,22 @@ export const useWorkspaceStore = defineStore(
       resolveActiveBoard,
     })
 
-    // Monotonic guard for {@link refresh}: `board`-type stream events (and the on-connect resync)
-    // each fire a full-snapshot refresh, and {@link hydrate} REPLACES the block list. Without
-    // ordering, two in-flight fetches can resolve out of order, so a slower/staler snapshot's
-    // hydrate clobbers a newer one — dropping a just-spawned block whose ONLY live delivery was
-    // the coarse `board` event (there is no per-block push), so its card never reappears (no
-    // further event to restore it). Stamping each call lets only the latest-issued refresh commit.
-    let refreshSeq = 0
-
-    /** Re-fetch the snapshot and re-hydrate (after mutations and on stream (re)connect). */
-    async function refresh() {
-      const targetId = workspaceId.value
-      if (!targetId) return
-      const seq = ++refreshSeq
-      // Capture the live-write baselines BEFORE the fetch: anything a live event writes while
-      // this (potentially slow) snapshot is in flight is newer than the snapshot, so `hydrate`
-      // must NOT clobber it back. The `refreshSeq` guard below only orders refreshes against each
-      // OTHER — this guards a refresh against an interleaved live write (a run's terminal status
-      // landing mid-fetch, or the inbox card it raises), the coherence hazard under CI latency.
-      const baselines: LiveWriteBaselines = {
+    // The one door every full-snapshot refresh goes through: it coalesces the ~35 direct
+    // post-mutation call sites and the stream's coarse-event resync into at most one in-flight
+    // fetch plus one queued follow-up, and exposes the coverage mark the stream's debounce uses to
+    // drop a resync a mutation's own refresh already served. Ordering (a stale snapshot's hydrate
+    // clobbering a newer one, which would drop a just-spawned block whose ONLY live delivery was
+    // the coarse `board` event) falls out of there being one fetch at a time. Rules and the
+    // reasoning: `stores/workspace/refreshFunnel.ts`.
+    const { refresh, refreshMark, hydratedSince } = createRefreshFunnel({
+      currentWorkspaceId: () => workspaceId.value,
+      fetchSnapshot: (id, signal) => api.getWorkspace(id, signal),
+      captureBaselines: (): LiveWriteBaselines => ({
         board: useBoardStore().hydrateBaseline(),
         notifications: useNotificationsStore().hydrateBaseline(),
-      }
-      const snapshot = await api.getWorkspace(targetId)
-      // A newer refresh was issued (or the active board switched) while this fetch was in flight —
-      // discard this older/staler result so it can't clobber the newer hydrate.
-      if (seq !== refreshSeq || workspaceId.value !== targetId) return
-      hydrate(snapshot, baselines)
-    }
+      }),
+      apply: hydrate,
+    })
 
     /** The active workspace id, or throw if the app isn't bootstrapped yet. */
     function requireId(): string {
@@ -262,6 +251,8 @@ export const useWorkspaceStore = defineStore(
       rename,
       remove,
       refresh,
+      refreshMark,
+      hydratedSince,
       requireId,
       resumeSpend,
     }

package/app/utils/laneIdentity.spec.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest'
+import { createLaneMemo } from '~/utils/laneIdentity'
+import type { LaneGroup, LaneTaskEntry, RenderedLane } from '~/utils/laneSort'
+import type { Block } from '~/types/domain'
+
+const taskA = { id: 'a', title: 'A' } as unknown as Block
+const taskB = { id: 'b', title: 'B' } as unknown as Block
+
+function entry(task: Block, over: Partial<LaneTaskEntry> = {}): LaneTaskEntry {
+  return {
+    task,
+    reason: 'running',
+    order: 0,
+    activityAt: null,
+    waitingSince: null,
+    moduleName: null,
+    initiativeName: null,
+    epicName: null,
+    ...over,
+  } as LaneTaskEntry
+}
+
+function group(id: string | null, entries: LaneTaskEntry[]): LaneGroup {
+  return { id, label: id, entries }
+}
+
+function lanes(...groups: LaneGroup[][]): RenderedLane[] {
+  const names = ['not_started', 'in_progress', 'needs_you', 'done'] as const
+  return groups.map((g, i) => ({
+    lane: names[i]!,
+    groups: g,
+    total: g.reduce((n, x) => n + x.entries.length, 0),
+  }))
+}
+
+describe('lane structural sharing', () => {
+  it('returns the previous array when nothing changed', () => {
+    const share = createLaneMemo()
+    const first = share(lanes([group('g1', [entry(taskA)])]))
+    const second = share(lanes([group('g1', [entry(taskA)])]))
+    expect(second).toBe(first)
+    expect(second[0]).toBe(first[0])
+    expect(second[0]!.groups[0]).toBe(first[0]!.groups[0])
+    expect(second[0]!.groups[0]!.entries[0]).toBe(first[0]!.groups[0]!.entries[0])
+  })
+
+  it('keeps the untouched lane identical while replacing the one that changed', () => {
+    const share = createLaneMemo()
+    const first = share(lanes([group('g1', [entry(taskA)])], [group('g2', [entry(taskB)])]))
+    const second = share(
+      lanes([group('g1', [entry(taskA)])], [group('g2', [entry(taskB, { activityAt: 5 })])]),
+    )
+    expect(second).not.toBe(first)
+    expect(second[0]).toBe(first[0])
+    expect(second[1]).not.toBe(first[1])
+  })
+
+  // Half of the reference rule: a REPLACED block (what every `board.upsert` does) is a new object,
+  // so reuse cannot hand a renderer the pre-write one.
+  it('does not reuse an entry whose task object was replaced', () => {
+    const share = createLaneMemo()
+    const first = share(lanes([group('g1', [entry(taskA)])]))
+    const renamed = { id: 'a', title: 'A renamed' } as unknown as Block
+    const second = share(lanes([group('g1', [entry(renamed)])]))
+    expect(second).not.toBe(first)
+    expect(second[0]!.groups[0]!.entries[0]!.task).toBe(renamed)
+  })
+
+  /**
+   * The other half, and the case the comparison deliberately does NOT try to detect:
+   * `stores/board/placement.ts` patches a block IN PLACE for its optimistic writes, so both entries
+   * hold the same object and no comparison over it could see the difference. Reuse is still
+   * observationally identical, because the object a renderer reads through IS the patched one (and
+   * `board.blocks` is deeply reactive, so the patch invalidates whatever read it). What must not be
+   * reused is an entry whose DERIVED fields moved with the patch, which is the assertion below.
+   */
+  it('reuses an entry whose task was patched in place, but not its derived fields', () => {
+    const share = createLaneMemo()
+    const task = { id: 'a', title: 'A', moduleName: null } as unknown as Block
+    const first = share(lanes([group('g1', [entry(task)])]))
+    Object.assign(task, { title: 'A patched', moduleName: 'billing' })
+    // Same derived fields: the entry is reused, and it carries the patched object.
+    const unchanged = share(lanes([group('g1', [entry(task)])]))
+    expect(unchanged).toBe(first)
+    expect(unchanged[0]!.groups[0]!.entries[0]!.task.title).toBe('A patched')
+    // The assembly re-derived `moduleName` from the patch: that is a fresh entry.
+    const rederived = share(lanes([group('g1', [entry(task, { moduleName: 'billing' })])]))
+    expect(rederived).not.toBe(first)
+    expect(rederived[0]!.groups[0]!.entries[0]!.moduleName).toBe('billing')
+  })
+
+  it('treats reordering, additions and removals as changes', () => {
+    const share = createLaneMemo()
+    const first = share(lanes([group('g1', [entry(taskA), entry(taskB)])]))
+    expect(share(lanes([group('g1', [entry(taskB), entry(taskA)])]))).not.toBe(first)
+
+    const share2 = createLaneMemo()
+    const base = share2(lanes([group('g1', [entry(taskA)])]))
+    expect(share2(lanes([group('g1', [entry(taskA), entry(taskB)])]))).not.toBe(base)
+  })
+
+  it('reuses an unchanged group while the sibling group in the same lane changes', () => {
+    const share = createLaneMemo()
+    const first = share(lanes([group('g1', [entry(taskA)]), group('g2', [entry(taskB)])]))
+    const second = share(
+      lanes([group('g1', [entry(taskA)]), group('g2', [entry(taskB, { order: 3 })])]),
+    )
+    expect(second[0]!.groups[0]).toBe(first[0]!.groups[0])
+    expect(second[0]!.groups[1]).not.toBe(first[0]!.groups[1])
+  })
+
+  it('does not reuse a lane whose total changed even when its rendered groups match', () => {
+    const share = createLaneMemo()
+    const first = share(lanes([group('g1', [entry(taskA)])]))
+    const capped = lanes([group('g1', [entry(taskA)])])
+    capped[0] = { ...capped[0]!, total: 99 }
+    expect(share(capped)).not.toBe(first)
+  })
+})

package/app/utils/laneIdentity.ts

@@ -0,0 +1,102 @@
+import type { LaneGroup, LaneTaskEntry, RenderedLane } from '~/utils/laneSort'
+
+// ---------------------------------------------------------------------------
+// Structural sharing for the swimlane output.
+//
+// WHY. The lane assembly (`useFrameLanes`) is a chain of computeds over the board blocks, both
+// pending-gate indexes, the coarse agent-run summary and the open notifications. Any ONE execution
+// event invalidates the whole chain for EVERY mounted frame, and the chain rebuilds every entry,
+// every group and every lane as fresh objects. Vue then sees new identities all the way down, so
+// `TaskLane` / `LaneGroup` re-render and every card diff re-runs, even for the (common) case where
+// the event changed one run's progress and moved nothing.
+//
+// WHAT THIS DOES. Compare the freshly built value against the previous one field by field and hand
+// BACK the previous object wherever nothing changed, so `===` holds for the parts that did not
+// move. Reuse cascades: unchanged entries let a group be reused, unchanged groups let a lane be
+// reused, unchanged lanes let the whole array be reused.
+//
+// THE CORRECTNESS RULE. Reuse is only sound when the reused object is observationally identical to
+// the fresh one, so the comparison must cover every DERIVED field: a value this assembly computed
+// (`moduleName`, `initiativeName`, `epicName`, the activity/wait stamps) exists only on the entry,
+// so a reused entry carrying a stale one is a lie nothing else can correct. That is why
+// {@link sameEntry} destructures rather than looping over keys, and why a field added to
+// `LaneTaskEntry` must be added to it in the same change.
+//
+// `task` is compared by REFERENCE, and that is NOT because the board store always replaces the
+// object: `stores/board/placement.ts` patches a block IN PLACE for its optimistic drag, reparent and
+// field edits, so the previous entry and the fresh one hold the very same object. Reference equality
+// is still the right comparison, for a different reason on each side. A REPLACED block (every
+// `board.upsert`, i.e. every server-sourced write) is a new reference, so it is caught here. A block
+// patched IN PLACE is one object that both entries share, so a renderer reading through the reused
+// entry reads the new value, and `board.blocks` is deeply reactive, so the mutation itself
+// invalidates whatever read it. What the mutation cannot reach is a value DERIVED off it, which is
+// exactly what the field comparison above covers.
+// ---------------------------------------------------------------------------
+
+function sameEntry(a: LaneTaskEntry, b: LaneTaskEntry): boolean {
+  return (
+    a.task === b.task &&
+    a.reason === b.reason &&
+    a.order === b.order &&
+    a.activityAt === b.activityAt &&
+    a.waitingSince === b.waitingSince &&
+    a.moduleName === b.moduleName &&
+    a.initiativeName === b.initiativeName &&
+    a.epicName === b.epicName
+  )
+}
+
+/** Element-wise reuse: the previous array when every member matched, else the fresh one. */
+function shareList<T>(
+  previous: readonly T[] | undefined,
+  next: T[],
+  same: (a: T, b: T) => boolean,
+  reuse?: (previous: T, next: T) => T,
+): T[] {
+  if (!previous || previous.length !== next.length) return next
+  let changed = false
+  const shared = next.map((item, i) => {
+    const prior = previous[i]!
+    if (same(prior, item)) return prior
+    const merged = reuse ? reuse(prior, item) : item
+    if (merged !== prior) changed = true
+    return merged
+  })
+  return changed ? shared : (previous as T[])
+}
+
+function sameGroup(a: LaneGroup, b: LaneGroup): boolean {
+  return a.id === b.id && a.label === b.label && a.entries === b.entries
+}
+
+function reuseGroup(previous: LaneGroup, next: LaneGroup): LaneGroup {
+  if (previous.id !== next.id || previous.label !== next.label) return next
+  const entries = shareList(previous.entries, next.entries, sameEntry)
+  return entries === previous.entries ? previous : { ...next, entries }
+}
+
+function sameLane(a: RenderedLane, b: RenderedLane): boolean {
+  return a.lane === b.lane && a.total === b.total && a.groups === b.groups
+}
+
+function reuseLane(previous: RenderedLane, next: RenderedLane): RenderedLane {
+  if (previous.lane !== next.lane || previous.total !== next.total) return next
+  const groups = shareList(previous.groups, next.groups, sameGroup, reuseGroup)
+  return groups === previous.groups ? previous : { ...next, groups }
+}
+
+/**
+ * A per-frame memo that hands back the previously rendered lanes wherever the freshly assembled
+ * ones are identical.
+ *
+ * Holds ONE generation, not a cache: the previous result is the only thing a recompute can share
+ * with, so there is nothing to evict and nothing to bound. Created per `useFrameLanes` instance, so
+ * it lives and dies with the frame that owns it.
+ */
+export function createLaneMemo(): (next: RenderedLane[]) => RenderedLane[] {
+  let previous: RenderedLane[] | undefined
+  return (next) => {
+    previous = shareList(previous, next, sameLane, reuseLane)
+    return previous
+  }
+}

package/app/utils/laneSort.ts

@@ -179,8 +179,26 @@ const NEEDS_YOU_TIER: Partial<Record<LaneReason, number>> = {
 
 type Comparator = (a: LaneTaskEntry, b: LaneTaskEntry) => number
 
+/**
+ * One collator for every text comparison in this module, built lazily and reused.
+ *
+ * `String.prototype.localeCompare` constructs a fresh collator per CALL, and these comparators run
+ * O(n log n) times per lane per frame on every board event: the `task_type` comparator alone made
+ * two of those calls per comparison. Constructing the collator once turns the dominant cost of a
+ * text sort back into the comparison itself.
+ *
+ * Built with NO options, so it is the same collation `a.localeCompare(b)` performed: this is a
+ * caching change, and a lane whose order shifted under it would be a behaviour change nobody asked
+ * for wearing a performance change's clothes.
+ */
+let collator: Intl.Collator | undefined
+function compareText(a: string, b: string): number {
+  collator ??= new Intl.Collator()
+  return collator.compare(a, b)
+}
+
 const EXPLICIT_COMPARATORS: Record<Exclude<LaneSortKey, 'smart'>, Comparator> = {
-  title: (a, b) => a.task.title.localeCompare(b.task.title),
+  title: (a, b) => compareText(a.task.title, b.task.title),
   oldest_activity: (a, b) => nullsLast(a.activityAt, b.activityAt, ascending),
   newest_activity: (a, b) => nullsLast(a.activityAt, b.activityAt, descending),
   longest_wait: (a, b) => nullsLast(a.waitingSince, b.waitingSince, ascending),
@@ -188,8 +206,8 @@ const EXPLICIT_COMPARATORS: Record<Exclude<LaneSortKey, 'smart'>, Comparator> =
   impact_desc: (a, b) =>
     nullsLast(a.task.estimate?.impact ?? null, b.task.estimate?.impact ?? null, descending),
   task_type: (a, b) =>
-    (a.task.taskType ?? '').localeCompare(b.task.taskType ?? '') ||
-    a.task.title.localeCompare(b.task.title),
+    compareText(a.task.taskType ?? '', b.task.taskType ?? '') ||
+    compareText(a.task.title, b.task.title),
 }
 
 /**
@@ -242,6 +260,20 @@ export interface LaneGroup {
   readonly entries: LaneTaskEntry[]
 }
 
+/**
+ * One rendered lane: its identity, its groups, and the count its header states.
+ *
+ * Lives beside the shapes it composes rather than in `composables/useFrameLanes`, which assembles
+ * it: `utils/laneIdentity.ts` compares these, and a util reaching into a composable for its central
+ * type points the dependency the wrong way round.
+ */
+export interface RenderedLane {
+  readonly lane: TaskLane
+  readonly groups: LaneGroup[]
+  /** Every task classified into this lane, BEFORE the Done lane's caps. */
+  readonly total: number
+}
+
 /**
  * The value a task is grouped under, or null for the catch-all group.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.277.1",
+  "version": "0.277.2",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",