@cat-factory/app 0.115.1 → 0.115.3

package/app/composables/useStepTimer.ts

@@ -1,6 +1,63 @@
 import { ref, computed, onMounted, onUnmounted } from 'vue'
 import type { PipelineStep } from '~/types/execution'
 
+/**
+ * Whether a step is actively executing: it has started, hasn't finished, isn't
+ * parked on a human (`pausedAt`), and the run itself hasn't failed. A step in any
+ * of those states is not ticking — no spinner, no counting-up clock.
+ */
+export function stepIsRunning(step: PipelineStep | null, runFailed: boolean): boolean {
+  return !!step?.startedAt && !step?.finishedAt && step?.pausedAt == null && !runFailed
+}
+
+/**
+ * Elapsed/total execution time in ms for a step at wall-clock `nowMs`, or null until
+ * the step has started. The clock freezes once the step stops working: at its finish,
+ * else at the run's failure time once the run has failed, else at the moment it parked
+ * on a human (`pausedAt`). Otherwise it is live, counting up to `nowMs`.
+ */
+export function stepDurationMs(
+  step: PipelineStep | null,
+  nowMs: number,
+  runFailed: boolean,
+  failureAt: number | null | undefined,
+): number | null {
+  if (step?.startedAt == null) return null
+  const end =
+    step.finishedAt ?? (runFailed ? (failureAt ?? step.startedAt) : (step.pausedAt ?? nowMs))
+  return Math.max(0, end - step.startedAt)
+}
+
+/** Human-friendly elapsed label for a step at `nowMs`, or null until it has started. */
+export function stepDurationLabel(
+  step: PipelineStep | null,
+  nowMs: number,
+  runFailed: boolean,
+  failureAt: number | null | undefined,
+): string | null {
+  const ms = stepDurationMs(step, nowMs, runFailed, failureAt)
+  return ms == null ? null : formatDuration(ms)
+}
+
+/**
+ * A shared 1s wall-clock tick for surfaces that render many steps' live durations
+ * at once (the pipeline timeline, the inspector run list). One interval drives every
+ * step's elapsed label instead of a per-step timer. Stays `0` until mounted so the
+ * first paint never reads a stale time.
+ */
+export function useNowTick(intervalMs = 1000) {
+  const now = ref(0)
+  let timer: ReturnType<typeof setInterval> | undefined
+  onMounted(() => {
+    now.value = Date.now()
+    timer = setInterval(() => (now.value = Date.now()), intervalMs)
+  })
+  onUnmounted(() => {
+    if (timer) clearInterval(timer)
+  })
+  return now
+}
+
 /**
  * Live elapsed-time clock for a single pipeline step. A 1s tick drives the
  * counting-up duration while the step is actively running; the clock freezes at
@@ -12,37 +69,16 @@ export function useStepTimer(opts: {
   runFailed: () => boolean
   failureAt: () => number | null | undefined
 }) {
-  // A 1s tick so a still-running step's elapsed time counts up live while open.
-  const nowTick = ref(0)
-  let timer: ReturnType<typeof setInterval> | undefined
-  onMounted(() => {
-    nowTick.value = Date.now()
-    timer = setInterval(() => (nowTick.value = Date.now()), 1000)
-  })
-  onUnmounted(() => {
-    if (timer) clearInterval(timer)
-  })
+  const nowTick = useNowTick()
 
   // A step that is finished, failed, or parked on a human is not actively
-  // executing — no ticking clock or spinner. `pausedAt` is the "waiting on input"
-  // freeze.
-  const isRunning = computed(() => {
-    const s = opts.step()
-    return !!s?.startedAt && !s?.finishedAt && s?.pausedAt == null && !opts.runFailed()
-  })
+  // executing — no ticking clock or spinner. `pausedAt` is the "waiting on input" freeze.
+  const isRunning = computed(() => stepIsRunning(opts.step(), opts.runFailed()))
 
   /** Elapsed/total execution time in ms — null until the step has started. */
-  const durationMs = computed(() => {
-    const s = opts.step()
-    if (s?.startedAt == null) return null
-    // Freeze the clock once the step stops working: at its finish, else at the
-    // failure time once the run has failed, else at the moment it parked on a
-    // human (`pausedAt`). Otherwise it is live, so count up to the current tick.
-    const end =
-      s.finishedAt ??
-      (opts.runFailed() ? (opts.failureAt() ?? s.startedAt) : (s.pausedAt ?? nowTick.value))
-    return Math.max(0, end - s.startedAt)
-  })
+  const durationMs = computed(() =>
+    stepDurationMs(opts.step(), nowTick.value, opts.runFailed(), opts.failureAt()),
+  )
 
   const durationLabel = computed(() =>
     durationMs.value == null ? null : formatDuration(durationMs.value),
@@ -51,7 +87,7 @@ export function useStepTimer(opts: {
   return { isRunning, durationMs, durationLabel }
 }
 
-function formatDuration(ms: number): string {
+export function formatDuration(ms: number): string {
   const totalSec = Math.round(ms / 1000)
   if (totalSec < 60) return `${totalSec}s`
   const m = Math.floor(totalSec / 60)

package/app/stores/consensus.spec.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useConsensusStore } from '~/stores/consensus'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { ConsensusSession } from '~/types/consensus'
+
+/** Minimal session factory — only the fields the store reconciles/reads. */
+function session(over: Partial<ConsensusSession> = {}): ConsensusSession {
+  return {
+    id: 's1',
+    blockId: 'blk1',
+    executionId: null,
+    stepIndex: 0,
+    agentKind: 'architect',
+    strategy: 'panel',
+    status: 'complete',
+    participants: [],
+    rounds: [],
+    synthesis: null,
+    createdAt: 1,
+    updatedAt: 1,
+    ...over,
+  } as ConsensusSession
+}
+
+describe('consensus store — load vs live-push reconcile', () => {
+  beforeEach(() => {
+    useWorkspaceStore().workspaceId = 'ws1'
+  })
+
+  it('load stores the fetched session', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getConsensusSession: () => Promise.resolve({ session: session() }),
+    }))
+    const store = useConsensusStore()
+    await store.load('blk1')
+    expect(store.sessionFor('blk1')?.id).toBe('s1')
+  })
+
+  it('a stale load never regresses a fresher live-pushed session', async () => {
+    // A live `consensus` push delivers the newest transcript; a `load` that started earlier
+    // resolves later with a staler snapshot. It must NOT overwrite the fresher one.
+    let resolveFetch!: (r: { session: ConsensusSession | null }) => void
+    const pending = new Promise<{ session: ConsensusSession | null }>((res) => {
+      resolveFetch = res
+    })
+    vi.stubGlobal('useApi', () => ({ getConsensusSession: () => pending }))
+    const store = useConsensusStore()
+
+    const load = store.load('blk1')
+    store.upsert(session({ updatedAt: 10, synthesis: 'fresh' }))
+    resolveFetch({ session: session({ updatedAt: 2, synthesis: 'stale' }) })
+    await load
+
+    expect(store.sessionFor('blk1')?.synthesis).toBe('fresh')
+  })
+
+  it('a load returning "none" never clobbers an existing live session', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getConsensusSession: () => Promise.resolve({ session: null }),
+    }))
+    const store = useConsensusStore()
+    store.upsert(session({ synthesis: 'live' }))
+    await store.load('blk1')
+    expect(store.sessionFor('blk1')?.synthesis).toBe('live')
+  })
+
+  it('a load returning "none" records the fetched-empty state when nothing is cached', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getConsensusSession: () => Promise.resolve({ session: null }),
+    }))
+    const store = useConsensusStore()
+    await store.load('blk1')
+    expect('blk1' in store.sessions).toBe(true)
+    expect(store.sessionFor('blk1')).toBeNull()
+  })
+})

package/app/stores/consensus.ts

@@ -46,7 +46,17 @@ export const useConsensusStore = defineStore('consensus', () => {
     loading.value = new Set(loading.value).add(blockId)
     try {
       const { session } = await api.getConsensusSession(wsId, blockId)
-      sessions.value = { ...sessions.value, [blockId]: session }
+      // Reconcile rather than blind-replace: a `load` resolving AFTER a fresher live
+      // `consensus` push (or after a newer concurrent load) must not regress the transcript —
+      // the out-of-order-overwrite hazard the CLAUDE.md live-push rules warn about. Keep
+      // whichever session is newer by `updatedAt` (any id), and never overwrite an existing
+      // (possibly live-pushed) session with a raced "none".
+      const existing = sessions.value[blockId]
+      if (session) {
+        if (!existing || session.updatedAt >= existing.updatedAt) store(session)
+      } else if (existing === undefined) {
+        sessions.value = { ...sessions.value, [blockId]: null }
+      }
     } catch {
       // Consensus off / no session — leave the cache as-is; the window shows its empty state.
     } finally {

package/app/stores/docInterview.spec.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useDocInterviewStore } from '~/stores/docInterview'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { DocInterviewSession } from '~/types/domain'
+
+/** Minimal session factory — only the fields the store reconciles/reads. */
+function session(over: Partial<DocInterviewSession> = {}): DocInterviewSession {
+  return {
+    id: 'd1',
+    blockId: 'blk1',
+    status: 'awaiting_answers',
+    round: 1,
+    maxRounds: 3,
+    qa: [],
+    brief: null,
+    model: null,
+    createdAt: 1,
+    updatedAt: 1,
+    ...over,
+  } as DocInterviewSession
+}
+
+// docInterview already routes its `load` through `upsert`'s newest-wins (`updatedAt`) guard —
+// these specs pin that so a future refactor can't reintroduce a blind-replace clobber.
+describe('docInterview store — load vs live-push reconcile', () => {
+  beforeEach(() => {
+    useWorkspaceStore().workspaceId = 'ws1'
+  })
+
+  it('load stores the fetched session', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getDocInterview: () => Promise.resolve(session()),
+    }))
+    const store = useDocInterviewStore()
+    await store.load('blk1')
+    expect(store.forBlock('blk1')?.id).toBe('d1')
+  })
+
+  it('a stale load never regresses a fresher live-pushed session', async () => {
+    let resolveFetch!: (r: DocInterviewSession | null) => void
+    const pending = new Promise<DocInterviewSession | null>((res) => {
+      resolveFetch = res
+    })
+    vi.stubGlobal('useApi', () => ({ getDocInterview: () => pending }))
+    const store = useDocInterviewStore()
+
+    const load = store.load('blk1')
+    store.upsert(session({ updatedAt: 10, round: 2 }))
+    resolveFetch(session({ updatedAt: 2, round: 1 }))
+    await load
+
+    expect(store.forBlock('blk1')?.round).toBe(2)
+  })
+
+  it('a load returning "none" leaves the cache untouched', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getDocInterview: () => Promise.resolve(null),
+    }))
+    const store = useDocInterviewStore()
+    store.upsert(session({ round: 2 }))
+    await store.load('blk1')
+    expect(store.forBlock('blk1')?.round).toBe(2)
+  })
+})

package/app/stores/kaizen.spec.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useKaizenStore } from '~/stores/kaizen'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { KaizenGrading } from '~/types/domain'
+
+/** Minimal grading factory — only the fields the store reconciles/reads. */
+function grading(over: Partial<KaizenGrading> = {}): KaizenGrading {
+  return {
+    id: 'g1',
+    executionId: 'exec1',
+    blockId: 'blk1',
+    stepIndex: 0,
+    agentKind: 'coder',
+    model: 'm',
+    promptVersion: 1,
+    comboKey: 'coder|m|1',
+    status: 'complete',
+    grade: 5,
+    summary: '',
+    recommendations: [],
+    graderModel: null,
+    error: null,
+    createdAt: 1,
+    updatedAt: 1,
+    ...over,
+  } as KaizenGrading
+}
+
+describe('kaizen store — live-push clobber guards', () => {
+  beforeEach(() => {
+    useWorkspaceStore().workspaceId = 'ws1'
+  })
+
+  it('loadForExecution stores the fetched gradings', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getKaizenForExecution: () => Promise.resolve({ gradings: [grading()] }),
+    }))
+    const store = useKaizenStore()
+    await store.loadForExecution('exec1')
+    expect(store.byExecution.exec1).toHaveLength(1)
+  })
+
+  it('a slower stale loadForExecution never clobbers a newer one (monotonic guard)', async () => {
+    // Two loads race for the same execution: the FIRST-issued resolves LAST with a stale list.
+    // Without the ticket guard its REPLACE would overwrite the fresher second result.
+    const deferred: Array<(r: { gradings: KaizenGrading[] }) => void> = []
+    vi.stubGlobal('useApi', () => ({
+      getKaizenForExecution: () =>
+        new Promise<{ gradings: KaizenGrading[] }>((res) => deferred.push(res)),
+    }))
+    const store = useKaizenStore()
+    const first = store.loadForExecution('exec1') // issued #1 (stale)
+    const second = store.loadForExecution('exec1') // issued #2 (fresh)
+
+    deferred[1]!({ gradings: [grading({ id: 'fresh' })] })
+    deferred[0]!({ gradings: [grading({ id: 'stale' })] })
+    await Promise.all([first, second])
+
+    expect(store.byExecution.exec1).toHaveLength(1)
+    expect(store.byExecution.exec1![0]!.id).toBe('fresh')
+  })
+
+  it('a grading pushed live mid-load survives the load (merge, not blind-replace)', async () => {
+    // A load is in flight (server response predates the newest grading); a live `upsert` lands
+    // its grading; then the load resolves. A blind replace would drop the live-only grading.
+    let resolveFetch!: (r: { gradings: KaizenGrading[] }) => void
+    const pending = new Promise<{ gradings: KaizenGrading[] }>((res) => {
+      resolveFetch = res
+    })
+    vi.stubGlobal('useApi', () => ({ getKaizenForExecution: () => pending }))
+    const store = useKaizenStore()
+
+    const load = store.loadForExecution('exec1')
+    // A live stream event arrives while the fetch is in flight.
+    store.upsert(grading({ id: 'live', stepIndex: 1 }))
+    // The load's (staler) response comes back with only the earlier grading.
+    resolveFetch({ gradings: [grading({ id: 'g1', stepIndex: 0 })] })
+    await load
+
+    const ids = store.byExecution.exec1!.map((g) => g.id).sort()
+    expect(ids).toEqual(['g1', 'live'])
+  })
+
+  it('a shared-id load keeps whichever updatedAt is newer', async () => {
+    // Stub before the store is created — it captures `useApi()` at instantiation.
+    vi.stubGlobal('useApi', () => ({
+      getKaizenForExecution: () =>
+        Promise.resolve({ gradings: [grading({ id: 'g1', updatedAt: 2, summary: 'stale' })] }),
+    }))
+    const store = useKaizenStore()
+    // Seed a fresher live grading, then a load returns a staler copy of the SAME id.
+    store.upsert(grading({ id: 'g1', updatedAt: 5, summary: 'live' }))
+    await store.loadForExecution('exec1')
+    expect(store.byExecution.exec1![0]!.summary).toBe('live')
+  })
+
+  it('loadOverview preserves a live-pushed grading in history (merge, newest-first)', async () => {
+    vi.stubGlobal('useApi', () => ({
+      getKaizenOverview: () =>
+        Promise.resolve({
+          gradings: [grading({ id: 'old', createdAt: 1, updatedAt: 1 })],
+          verified: [],
+        }),
+    }))
+    const store = useKaizenStore()
+    // A grading arrives live before the overview list is fetched.
+    store.upsert(grading({ id: 'live', createdAt: 9, updatedAt: 9 }))
+    await store.loadOverview()
+
+    const ids = store.history.map((g) => g.id)
+    expect(ids).toContain('live')
+    expect(ids).toContain('old')
+    // The live (newest) grading stays at the front of the newest-first list.
+    expect(ids[0]).toBe('live')
+  })
+
+  it('a slower stale loadOverview never clobbers a newer one', async () => {
+    const deferred: Array<(r: { gradings: KaizenGrading[]; verified: [] }) => void> = []
+    vi.stubGlobal('useApi', () => ({
+      getKaizenOverview: () =>
+        new Promise<{ gradings: KaizenGrading[]; verified: [] }>((res) => deferred.push(res)),
+    }))
+    const store = useKaizenStore()
+    const first = store.loadOverview() // stale
+    const second = store.loadOverview() // fresh
+
+    deferred[1]!({ gradings: [grading({ id: 'fresh' })], verified: [] })
+    deferred[0]!({ gradings: [grading({ id: 'stale' })], verified: [] })
+    await Promise.all([first, second])
+
+    expect(store.history).toHaveLength(1)
+    expect(store.history[0]!.id).toBe('fresh')
+  })
+})

package/app/stores/kaizen.ts

@@ -23,6 +23,36 @@ export const useKaizenStore = defineStore('kaizen', () => {
   /** 503 ⇒ the Kaizen feature isn't configured on this deployment. */
   const available = ref<boolean | null>(null)
 
+  // Monotonic load-ordering guard. Both loads REPLACE state that also arrives live over the
+  // stream (`upsert`), so a slower/staler fetch resolving AFTER a newer one — or after a live
+  // push — would clobber the fresher gradings (the CLAUDE.md live-push out-of-order hazard,
+  // the same one `stores/provisioningLogs.ts` guards). Each load takes a ticket; only the
+  // newest-issued one commits. NOT reactive — pure bookkeeping the UI never reads.
+  let loadTicket = 0
+  let latestOverviewLoad = 0
+  const latestExecLoad = new Map<string, number>()
+
+  /**
+   * Fold a freshly-loaded grading list into the live cache WITHOUT dropping live-only rows:
+   * a grading pushed via `upsert` while the load was in flight may not be in the server's
+   * response yet, and a blind replace would silently drop it. Loaded rows are authoritative
+   * for the ids they carry (keeping whichever `updatedAt` is greater on a shared id), and any
+   * live-only rows the response hasn't caught up to are preserved. Gradings are append/update-
+   * only (never deleted), so preserving an unmatched live row can't resurrect stale state.
+   * Returns the reconciled loaded rows and the surviving live-only rows separately so each
+   * caller can splice them in its own order (execution cache appends; screen history, which is
+   * newest-first, prepends).
+   */
+  function reconcileWithLive(loaded: KaizenGrading[], existing: KaizenGrading[]) {
+    const loadedIds = new Set(loaded.map((g) => g.id))
+    const reconciled = loaded.map((l) => {
+      const live = existing.find((e) => e.id === l.id)
+      return live && live.updatedAt > l.updatedAt ? live : l
+    })
+    const liveOnly = existing.filter((e) => !loadedIds.has(e.id))
+    return { reconciled, liveOnly }
+  }
+
   function gradingsFor(executionId: string): KaizenGrading[] {
     return byExecution.value[executionId] ?? []
   }
@@ -35,11 +65,18 @@ export const useKaizenStore = defineStore('kaizen', () => {
   async function loadOverview() {
     const ws = useWorkspaceStore()
     loadingOverview.value = true
+    const seq = ++loadTicket
+    latestOverviewLoad = seq
     try {
       const overview = await api.getKaizenOverview(ws.requireId())
-      history.value = overview.gradings
-      verified.value = overview.verified
       available.value = true
+      // A newer overview load superseded this one while it was in flight — discard the staler
+      // result so it can't clobber the fresher history (and any grading live-pushed since).
+      if (latestOverviewLoad !== seq) return
+      verified.value = overview.verified
+      // History is newest-first; live-pushed gradings are the newest, so prepend the survivors.
+      const { reconciled, liveOnly } = reconcileWithLive(overview.gradings, history.value)
+      history.value = [...liveOnly, ...reconciled]
     } catch (e) {
       if ((e as { statusCode?: number; status?: number })?.statusCode === 503)
         available.value = false
@@ -52,10 +89,20 @@ export const useKaizenStore = defineStore('kaizen', () => {
   async function loadForExecution(executionId: string) {
     const ws = useWorkspaceStore()
     loadingExecution.value = new Set(loadingExecution.value).add(executionId)
+    const seq = ++loadTicket
+    latestExecLoad.set(executionId, seq)
     try {
       const { gradings } = await api.getKaizenForExecution(ws.requireId(), executionId)
-      byExecution.value = { ...byExecution.value, [executionId]: gradings }
       available.value = true
+      // A newer load for this execution (or a live `upsert`) may have landed while this fetch
+      // was in flight — discard a superseded load, and merge rather than blind-replace so a
+      // grading pushed live mid-flight isn't dropped.
+      if (latestExecLoad.get(executionId) !== seq) return
+      const { reconciled, liveOnly } = reconcileWithLive(
+        gradings,
+        byExecution.value[executionId] ?? [],
+      )
+      byExecution.value = { ...byExecution.value, [executionId]: [...reconciled, ...liveOnly] }
     } catch (e) {
       if ((e as { statusCode?: number; status?: number })?.statusCode === 503)
         available.value = false

package/app/utils/slackMemberMapping.spec.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest'
+import type { SlackMemberMappingEntry } from '~/types/slack'
+import {
+  type MemberRow,
+  emptyMemberRow,
+  hasHalfFilledRow,
+  toMemberEntries,
+  toMemberRow,
+} from './slackMemberMapping'
+
+const row = (partial: Partial<MemberRow> & { uid: string }): MemberRow => ({
+  userId: '',
+  slackUserId: '',
+  role: 'engineering',
+  ...partial,
+})
+
+describe('hasHalfFilledRow', () => {
+  it('is false for fully-filled rows', () => {
+    expect(hasHalfFilledRow([row({ uid: 'a', userId: 'usr_1', slackUserId: 'U1' })])).toBe(false)
+  })
+
+  it('is false for fully-empty rows (unused slots)', () => {
+    expect(hasHalfFilledRow([row({ uid: 'a' }), row({ uid: 'b' })])).toBe(false)
+  })
+
+  it('is true when only the user id is filled', () => {
+    expect(hasHalfFilledRow([row({ uid: 'a', userId: 'usr_1' })])).toBe(true)
+  })
+
+  it('is true when only the Slack id is filled', () => {
+    expect(hasHalfFilledRow([row({ uid: 'a', slackUserId: 'U1' })])).toBe(true)
+  })
+
+  it('treats whitespace-only ids as blank', () => {
+    expect(hasHalfFilledRow([row({ uid: 'a', userId: '  ', slackUserId: 'U1' })])).toBe(true)
+  })
+
+  it('flags a half-filled row among valid ones', () => {
+    expect(
+      hasHalfFilledRow([
+        row({ uid: 'a', userId: 'usr_1', slackUserId: 'U1' }),
+        row({ uid: 'b', userId: 'usr_2' }),
+      ]),
+    ).toBe(true)
+  })
+})
+
+describe('toMemberEntries', () => {
+  it('keeps fully-filled rows, drops empty slots, and strips uid', () => {
+    const rows: MemberRow[] = [
+      row({ uid: 'a', userId: 'usr_1', slackUserId: 'U1', role: 'product' }),
+      row({ uid: 'b' }), // empty slot — dropped
+      row({ uid: 'c', userId: 'usr_2', slackUserId: 'U2' }),
+    ]
+    expect(toMemberEntries(rows)).toEqual([
+      { userId: 'usr_1', slackUserId: 'U1', role: 'product' },
+      { userId: 'usr_2', slackUserId: 'U2', role: 'engineering' },
+    ])
+  })
+
+  it('does not leak the client-only uid onto the wire payload', () => {
+    const [entry] = toMemberEntries([row({ uid: 'a', userId: 'usr_1', slackUserId: 'U1' })])
+    expect(entry).not.toHaveProperty('uid')
+  })
+})
+
+describe('toMemberRow', () => {
+  it('stamps the uid and defaults a missing role', () => {
+    const entry: SlackMemberMappingEntry = { userId: 'usr_1', slackUserId: 'U1' }
+    expect(toMemberRow(entry, 'm1')).toEqual({
+      userId: 'usr_1',
+      slackUserId: 'U1',
+      role: 'engineering',
+      uid: 'm1',
+    })
+  })
+
+  it('preserves an explicit role', () => {
+    const entry: SlackMemberMappingEntry = { userId: 'usr_1', slackUserId: 'U1', role: 'product' }
+    expect(toMemberRow(entry, 'm2').role).toBe('product')
+  })
+})
+
+describe('emptyMemberRow', () => {
+  it('builds a blank engineering row with the given uid', () => {
+    expect(emptyMemberRow('m9')).toEqual({
+      uid: 'm9',
+      userId: '',
+      slackUserId: '',
+      role: 'engineering',
+    })
+  })
+})

package/app/utils/slackMemberMapping.ts

@@ -0,0 +1,46 @@
+import type { SlackMemberMappingEntry } from '~/types/slack'
+
+// Pure helpers for the Slack member-mapping editor (SlackPanel.vue). Extracted so
+// the save-time integrity rules (UX-23) can be unit-tested without mounting the panel.
+
+/**
+ * An editable member-map row: the wire entry plus a client-only stable `uid` so a
+ * mid-list delete keys the `v-model` by identity, not the array index (index keys
+ * silently rebound a neighbour's inputs — UX-23).
+ */
+export type MemberRow = SlackMemberMappingEntry & { uid: string }
+
+/**
+ * True when any row has exactly one of the two ids filled. A half-entered mapping
+ * used to be silently dropped on save (UX-23); the panel blocks the save instead so
+ * the user doesn't lose it. A fully-empty row is an unused slot, not half-filled.
+ */
+export function hasHalfFilledRow(
+  rows: readonly Pick<MemberRow, 'userId' | 'slackUserId'>[],
+): boolean {
+  return rows.some((e) => Boolean(e.userId.trim()) !== Boolean(e.slackUserId.trim()))
+}
+
+/**
+ * The rows to persist: fully-filled only (empty slots dropped), with the client-only
+ * `uid` stripped from the wire payload.
+ */
+export function toMemberEntries(rows: readonly MemberRow[]): SlackMemberMappingEntry[] {
+  return rows
+    .filter((e) => e.userId.trim() && e.slackUserId.trim())
+    .map(({ uid: _uid, ...entry }) => entry)
+}
+
+/**
+ * Wrap a stored wire entry as an editable row: stamp a stable `uid` and default the
+ * `role` (absent on older maps) so the initial load and the post-save reload produce
+ * identical rows rather than drifting on the default.
+ */
+export function toMemberRow(entry: SlackMemberMappingEntry, uid: string): MemberRow {
+  return { role: 'engineering', ...entry, uid }
+}
+
+/** A fresh, empty editable row stamped with the given stable `uid`. */
+export function emptyMemberRow(uid: string): MemberRow {
+  return { uid, userId: '', slackUserId: '', role: 'engineering' }
+}