@cat-factory/app 0.238.0 → 0.241.0

package/app/composables/useDocumentFreshness.ts

@@ -0,0 +1,111 @@
+import { ref } from 'vue'
+import type {
+  DocumentFreshness,
+  DocumentOrigin,
+  DocumentSourceKind,
+  RefreshedDocumentView,
+  SourceDocument,
+} from '~/types/domain'
+
+/**
+ * A verdict plus WHEN it was reached. The two are one value because either alone is a half-truth:
+ * the verdict says the copy matched the source, and only the stamp says how long ago that was true
+ * of a page someone else is still editing. A surface handed the verdict without the stamp can only
+ * render it as "just now", which is exactly the false confidence this feature exists to remove: an
+ * hour-old confirmation would keep showing a green check.
+ *
+ * `checkedAt` is stamped where the answer LANDS rather than on the server, so it is on the clock the
+ * person reading it is looking at. A skewed browser clock renders its own time consistently; a
+ * server stamp would render "checked at 14:32" to someone whose clock says 14:29.
+ */
+export interface DatedFreshness {
+  readonly verdict: DocumentFreshness
+  /** Epoch ms, on the reader's own clock. */
+  readonly checkedAt: number
+}
+
+/**
+ * The "is the copy on the board still the current one" half of the documents store: the per-document
+ * verdict a manual check produced, the in-flight flags, and the call that produces both.
+ *
+ * Its own collaborator rather than more lines in the store because it holds a DIFFERENT KIND of
+ * state from everything around it. The store's other state is the projection itself (sources,
+ * connections, imported rows), which the backend owns and the SPA mirrors; a freshness verdict is a
+ * statement about one MOMENT ("as of the click, this was the live revision"), owned by nothing and
+ * true of no row. Keeping it separate is what makes the three rules below expressible at all instead
+ * of folding into the document list and quietly becoming a claim about it.
+ *
+ * The rules, in one place so no surface can get half of them right:
+ *
+ *   - **An absent verdict means "nobody has asked", never "unknown".** Listing documents
+ *     deliberately probes nothing (confirming costs a round trip to the source per page), so a
+ *     freshly imported document has no verdict and is perfectly fine, which is not the same fact as
+ *     a check that ran and could not conclude.
+ *   - **The verdict never merges into the row.** A refresh that finds nothing changed writes
+ *     nothing, so `syncedAt` legitimately stays where it was; folding a confirmation into the row
+ *     would either claim a write that never happened or leave the confirmation sitting on a body
+ *     the source has moved past since.
+ *   - **A verdict belongs to the BOARD it was asked on.** The same Figma file can be imported into
+ *     two boards, and the pair `(source, externalId)` is identical in both, so a map keyed by that
+ *     alone would render board A's "confirmed, revision v3" against board B's row, which nobody
+ *     checked, breaking the first rule in the one direction that cannot be noticed. Hence
+ *     {@link keyOf}, and hence the read below asking for the ACTIVE board each time rather than
+ *     capturing it once.
+ */
+export function useDocumentFreshness(deps: {
+  /**
+   * The board these maps are ABOUT. A getter rather than a value because it changes under a
+   * long-lived store, and every read has to see the change.
+   */
+  workspaceId: () => string | null
+  /** Ask the backend to re-confirm one document. Only a CONNECTABLE source can be asked. */
+  refresh: (source: DocumentSourceKind, externalId: string) => Promise<RefreshedDocumentView>
+  /** Reconcile the (possibly rewritten) row back into the list every surface reads. */
+  onRefreshed: (document: SourceDocument) => void
+}): {
+  refresh: (source: DocumentSourceKind, externalId: string) => Promise<RefreshedDocumentView>
+  freshnessFor: (source: DocumentOrigin, externalId: string) => DatedFreshness | undefined
+  isRefreshing: (source: DocumentOrigin, externalId: string) => boolean
+} {
+  const freshness = ref<Record<string, DatedFreshness>>({})
+  const refreshing = ref<Record<string, boolean>>({})
+  const keyOf = (workspaceId: string | null, source: DocumentOrigin, externalId: string) =>
+    `${workspaceId ?? ''}:${source}:${externalId}`
+
+  async function refresh(source: DocumentSourceKind, externalId: string) {
+    // Captured ONCE, at the start, and used for every write below: a check that outlives a board
+    // switch must land under the board it was asked on, not whichever one is showing when it
+    // returns. Re-reading the getter at the end would file the answer under a board that never
+    // asked, which is the same wrong render the key exists to prevent, just harder to reproduce.
+    const board = deps.workspaceId()
+    const key = keyOf(board, source, externalId)
+    refreshing.value = { ...refreshing.value, [key]: true }
+    try {
+      const result = await deps.refresh(source, externalId)
+      // The document LIST is the active board's, and it is not keyed by board, so a row can only be
+      // merged into it while that board is still the one showing. The verdict is filed either way:
+      // it stays true of the board it was asked on, and switching back should not have to re-ask.
+      if (deps.workspaceId() === board) deps.onRefreshed(result.document)
+      freshness.value = {
+        ...freshness.value,
+        [key]: { verdict: result.freshness, checkedAt: Date.now() },
+      }
+      return result
+    } finally {
+      // Cleared however the call ended. A failure that left the flag set would disable the button
+      // that is the whole remedy, so the person could not try again.
+      const { [key]: _settled, ...rest } = refreshing.value
+      refreshing.value = rest
+    }
+  }
+
+  // The verdict map itself stays INSIDE: a caller that could write it could record a conclusion
+  // nobody reached, which is the one thing this vocabulary exists to make impossible.
+  return {
+    refresh,
+    freshnessFor: (source, externalId) =>
+      freshness.value[keyOf(deps.workspaceId(), source, externalId)],
+    isRefreshing: (source, externalId) =>
+      !!refreshing.value[keyOf(deps.workspaceId(), source, externalId)],
+  }
+}

package/app/stores/accounts.audit.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest'
+import { useAccountsStore } from '~/stores/accounts'
+
+/**
+ * The audit feed and the one write that produces a row in it.
+ *
+ * What these guard is the seam between them. Forcing a member's sessions to end leaves nothing
+ * visible in the roster — the row IS the trace — so the feed has to be brought back into step.
+ * Doing that by awaiting the read inside the write is what conflated the two: a revocation that
+ * had already succeeded was reported to the admin as "could not sign the member out" whenever the
+ * follow-up read failed, which on a deployment with no audit store wired is every time.
+ */
+describe('accounts store — audit feed and forced revocation', () => {
+  it('reports a successful revocation as successful even when the audit read is broken', async () => {
+    // The 204 landed. Nothing about a failing GET afterwards changes that, and telling an admin
+    // otherwise invites them to do it again or to escalate a problem they do not have.
+    const listAuditEvents = vi.fn(() => Promise.reject(new Error('audit store down')))
+    const revokeMemberSessions = vi.fn(() => Promise.resolve())
+    vi.stubGlobal('useApi', () => ({ listAuditEvents, revokeMemberSessions }))
+
+    const store = useAccountsStore()
+    await expect(store.revokeMemberSessions('acc_1', 'usr_2')).resolves.toBeUndefined()
+    expect(revokeMemberSessions).toHaveBeenCalledWith('acc_1', 'usr_2')
+  })
+
+  it('does not read the audit log from the write path at all', async () => {
+    // The write must not pay for a read nothing may be showing: the panel is absent in basic mode
+    // and on any deployment that wires no audit store. Marking the feed stale leaves the reload to
+    // the viewer, which is the only place that knows it is on screen and the only place that
+    // renders a failed read AS a failed read.
+    const listAuditEvents = vi.fn(() => Promise.resolve({ events: [], nextCursor: null }))
+    vi.stubGlobal('useApi', () => ({
+      listAuditEvents,
+      revokeMemberSessions: () => Promise.resolve(),
+    }))
+
+    const store = useAccountsStore()
+    await store.revokeMemberSessions('acc_1', 'usr_2')
+
+    expect(listAuditEvents).not.toHaveBeenCalled()
+    expect(store.auditStale).toBe(true)
+  })
+
+  it('propagates a failed revocation, which IS the caller’s business', async () => {
+    vi.stubGlobal('useApi', () => ({
+      listAuditEvents: () => Promise.resolve({ events: [], nextCursor: null }),
+      revokeMemberSessions: () => Promise.reject(new Error('nope')),
+    }))
+
+    const store = useAccountsStore()
+    store.auditStale = false
+
+    await expect(store.revokeMemberSessions('acc_1', 'usr_2')).rejects.toThrow('nope')
+    // Nothing was written, so the feed is not behind.
+    expect(store.auditStale).toBe(false)
+  })
+
+  it('clears the stale flag on the reload ATTEMPT, not on its success', async () => {
+    // Clearing on success would re-trigger the watch that just failed, on every failure, forever.
+    // The failure is reported by the viewer's own error slot instead.
+    vi.stubGlobal('useApi', () => ({
+      listAuditEvents: () => Promise.reject(new Error('still down')),
+      revokeMemberSessions: () => Promise.resolve(),
+    }))
+
+    const store = useAccountsStore()
+    await store.revokeMemberSessions('acc_1', 'usr_2')
+    expect(store.auditStale).toBe(true)
+
+    await expect(store.loadAuditEvents('acc_1')).rejects.toThrow('still down')
+    expect(store.auditStale).toBe(false)
+    expect(store.auditLoading).toBe(false)
+  })
+})

package/app/stores/accounts.ts

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import { useUpsertList } from '~/composables/useUpsertList'
+import type { AuditEventWire } from '@cat-factory/contracts'
 import type {
   Account,
   AccountInvitation,
@@ -113,6 +114,73 @@ export const useAccountsStore = defineStore(
       return updated
     }
 
+    // ---- audit log + session revocation -----------------------------------
+    // The audit log is a paginated, append-only feed, so it is kept OUT of `useUpsertList`: the
+    // rows never change and never arrive out of band, and a keyed upsert list would quietly
+    // reorder a page whose whole meaning is its order. Pages are appended in the order the server
+    // served them, and `auditCursor` is opaque — it round-trips verbatim, never inspected.
+    const auditEvents = ref<AuditEventWire[]>([])
+    const auditCursor = ref<string | null>(null)
+    const auditLoading = ref(false)
+
+    /**
+     * The audit feed has fallen behind something this session did. Set by the writers below and
+     * cleared by whoever reloads; the audit viewer watches it.
+     *
+     * A flag rather than a reload, because reloading here is what conflated two outcomes: the
+     * revocation and the feed refresh are separate calls that fail separately, and awaiting the
+     * second inside the first reported a revocation that HAD succeeded as "could not sign the
+     * member out" whenever the read failed after it. It also fired on surfaces with no audit
+     * panel rendered (basic mode, and any account whose deployment wires no audit store), paying
+     * for a read nothing was going to show and turning its 503 into an error about the write.
+     *
+     * The viewer owns the reload instead, which is where it belongs: it already distinguishes a
+     * failed page from an empty one, and a refresh failure now renders in that slot rather than
+     * as a false report about the revocation.
+     */
+    const auditStale = ref(false)
+
+    /**
+     * Load the newest page, replacing whatever was held. Used on open and on refresh, so a reader
+     * is never shown a feed spliced from two different moments.
+     */
+    async function loadAuditEvents(accountId: string) {
+      auditLoading.value = true
+      // Cleared on ATTEMPT, not on success. A failed reload is reported by the viewer's own error
+      // slot, and leaving the flag set would re-trigger the watch that just failed.
+      auditStale.value = false
+      try {
+        const page = await api.listAuditEvents(accountId)
+        auditEvents.value = page.events
+        auditCursor.value = page.nextCursor
+      } finally {
+        auditLoading.value = false
+      }
+    }
+
+    /** Append the next (older) page. A no-op at the end of the log. */
+    async function loadMoreAuditEvents(accountId: string) {
+      if (!auditCursor.value || auditLoading.value) return
+      auditLoading.value = true
+      try {
+        const page = await api.listAuditEvents(accountId, { cursor: auditCursor.value })
+        auditEvents.value = [...auditEvents.value, ...page.events]
+        auditCursor.value = page.nextCursor
+      } finally {
+        auditLoading.value = false
+      }
+    }
+
+    /**
+     * End every session a member holds. Their membership and roles are untouched, so the roster
+     * needs no patching — what changed is not visible in it, which is why the audit feed is
+     * marked stale instead: the revocation's only lasting trace is the row it wrote.
+     */
+    async function revokeMemberSessions(accountId: string, userId: string) {
+      await api.revokeMemberSessions(accountId, userId)
+      auditStale.value = true
+    }
+
     // ---- email sender connection -----------------------------------------
 
     const emailConnection = ref<EmailConnection | null>(null)
@@ -144,6 +212,10 @@ export const useAccountsStore = defineStore(
       ready,
       members,
       invitations,
+      auditEvents,
+      auditCursor,
+      auditLoading,
+      auditStale,
       emailConnection,
       emailConfigured,
       load,
@@ -155,6 +227,9 @@ export const useAccountsStore = defineStore(
       invite,
       revokeInvite,
       setMemberRoles,
+      loadAuditEvents,
+      loadMoreAuditEvents,
+      revokeMemberSessions,
       loadEmailConnection,
       connectEmail,
       disconnectEmail,

package/app/stores/board/moveRefusal.spec.ts

@@ -0,0 +1,40 @@
+import type { RiskPolicySelectionRefusal } from '@cat-factory/contracts'
+import { describe, expect, it } from 'vitest'
+import en from '../../../i18n/locales/en.json'
+import { moveRefusalKey } from './moveRefusal'
+
+/** The thrown shape the contract client produces for a refused reparent (`ApiError.body`). */
+const refused = (reason: string) => ({
+  body: { error: { code: 'forbidden', details: { reason } } },
+})
+
+const REASONS: RiskPolicySelectionRefusal[] = [
+  'relaxes_role_sandbox',
+  'relaxes_role_submission_allowlist',
+  'relaxes_role_class_rule',
+]
+
+describe('moveRefusalKey', () => {
+  it('maps every refusal reason to a key the catalog actually holds', () => {
+    // Derived from the contracts union rather than a list written here, so a new reason fails
+    // this rather than silently reaching the user as the backend's untranslated English.
+    const catalog = (en as { board: { toast: { moveRefused: Record<string, string> } } }).board
+      .toast.moveRefused
+    for (const reason of REASONS) {
+      const key = moveRefusalKey(refused(reason))
+      expect(key, `${reason} has no key`).toBe(`board.toast.moveRefused.${reason}`)
+      expect(catalog[reason], `${reason} has no copy`).toBeTruthy()
+    }
+    // And nothing else: copy for a reason the backend cannot send is copy nobody translates for
+    // a purpose.
+    expect(Object.keys(catalog).sort()).toEqual([...REASONS].sort())
+  })
+
+  it('falls back to the raw message for anything else', () => {
+    // A 403 the guard did not raise, a network fault, a reason a newer backend knows and this
+    // build does not: the backend's own prose is the honest last resort, not a wrong translation.
+    expect(moveRefusalKey(refused('some_future_reason'))).toBeNull()
+    expect(moveRefusalKey({ body: { error: { code: 'forbidden' } } })).toBeNull()
+    expect(moveRefusalKey(new Error('Network down'))).toBeNull()
+  })
+})

package/app/stores/board/moveRefusal.ts

@@ -0,0 +1,34 @@
+import type { RiskPolicySelectionRefusal } from '@cat-factory/contracts'
+import { apiErrorReason } from '~/composables/api/errors'
+
+/**
+ * The translated description for a reparent the backend refused on merge-preset grounds, or
+ * `null` when the failure is anything else.
+ *
+ * A cross-home drag carries a task into another workspace's preset library, which re-decides
+ * whether its runs are sandboxed for the mover's role (ADR 0037), so the backend refuses one that
+ * would drop a restriction they are under. That refusal is a condition a person can act on, and
+ * the backend does not localize prose: it emits the machine-readable `details.reason` and the SPA
+ * maps it here, exactly as `usePipelineErrorToast` maps a conflict's. Without this the drag toast
+ * showed the raw English `ForbiddenError` message to every locale.
+ *
+ * The copy is deliberately NOT the picker's `riskPolicy.picker.refused.*`, which is worded for
+ * someone holding a control: this person picked no policy at all, and telling them about "the
+ * policy you picked" sends them looking for a picker they never touched.
+ *
+ * Keyed on the contracts union so a renamed reason fails the typecheck rather than silently
+ * falling through to the untranslated prose. An unrecognised reason returns `null` and the caller
+ * falls back to the backend's own message, which is the honest last resort.
+ */
+const MOVE_REFUSAL_KEY: Record<RiskPolicySelectionRefusal, string> = {
+  relaxes_role_sandbox: 'board.toast.moveRefused.relaxes_role_sandbox',
+  relaxes_role_submission_allowlist: 'board.toast.moveRefused.relaxes_role_submission_allowlist',
+  relaxes_role_class_rule: 'board.toast.moveRefused.relaxes_role_class_rule',
+}
+
+/** The i18n key for a thrown reparent error's refusal reason, else `null`. */
+export function moveRefusalKey(error: unknown): string | null {
+  const reason = apiErrorReason(error)
+  if (!reason) return null
+  return MOVE_REFUSAL_KEY[reason as RiskPolicySelectionRefusal] ?? null
+}

package/app/stores/board/placement.ts

@@ -2,6 +2,7 @@ import type { UpdateBlockInput } from '@cat-factory/contracts'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { createBoardDependencies } from './dependencies'
+import { moveRefusalKey } from './moveRefusal'
 import type { BoardWriteContext } from './context'
 import { UNDO_WINDOW_MS } from './context'
 
@@ -69,9 +70,13 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     } catch (e) {
       b.parentId = prevParentId
       b.position = prevPosition
+      // A cross-home drag can be refused on merge-preset grounds, which is a condition the mover
+      // can act on rather than a fault. The backend sends the machine-readable reason and no
+      // translated prose, so map it here; anything else keeps the raw message as the last resort.
+      const refusal = moveRefusalKey(e)
       toast.add({
         title: tr('board.toast.moveFailed'),
-        description: e instanceof Error ? e.message : String(e),
+        description: refusal ? tr(refusal) : e instanceof Error ? e.message : String(e),
         icon: 'i-lucide-triangle-alert',
         color: 'error',
       })

package/app/stores/documents.spec.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useDocumentsStore } from '~/stores/documents'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { DocumentFreshness, SourceDocument } from '~/types/domain'
+
+// The document store's REFRESH half: what a person gets back when they ask a source whether the
+// copy on the board is still the current one.
+//
+// Two things are worth pinning here rather than leaving to the component. The verdict is kept
+// SEPARATE from the row because it is a statement about a moment, not a property of the projection,
+// so an absent entry has to keep meaning "nobody has asked" (listing documents deliberately probes
+// nothing). And a refresh that pulls a moved page has to reconcile the returned row into the same
+// list every surface reads, or the panel goes on showing the title and excerpt import stored while
+// claiming, one line below, that it just confirmed the newer revision.
+
+function doc(over: Partial<SourceDocument> = {}): SourceDocument {
+  return {
+    source: 'figma',
+    externalId: 'file1:1-2',
+    title: 'Checkout flow',
+    url: 'https://figma.com/design/file1',
+    excerpt: 'Checkout',
+    linkedBlockId: 'task_1',
+    role: null,
+    docKind: null,
+    syncedAt: 1_000,
+    ...over,
+  }
+}
+
+const CONFIRMED: DocumentFreshness = { status: 'confirmed', version: 'v2', change: 'reimported' }
+
+/** The store reads `useApi()` off the auto-import, so each test stubs just what it calls. */
+function stubApi(over: Record<string, unknown>) {
+  vi.stubGlobal('useApi', () => ({
+    listDocuments: () => Promise.resolve([]),
+    ...over,
+  }))
+}
+
+beforeEach(() => {
+  useWorkspaceStore().workspaceId = 'ws1'
+})
+
+describe('documents store: manual refresh', () => {
+  it('reconciles the refreshed row into the list every surface reads', async () => {
+    stubApi({
+      listDocuments: () => Promise.resolve([doc()]),
+      refreshDocument: () =>
+        Promise.resolve({
+          document: doc({ title: 'Checkout flow v2', syncedAt: 2_000 }),
+          freshness: CONFIRMED,
+        }),
+    })
+    const store = useDocumentsStore()
+    await store.loadDocuments()
+
+    await store.refresh('figma', 'file1:1-2')
+
+    // Upserted by `(source, externalId)`, not appended: a refresh must not leave the old title
+    // sitting beside the new one in a picker keyed by the same document.
+    expect(store.documents).toHaveLength(1)
+    expect(store.documents[0]?.title).toBe('Checkout flow v2')
+  })
+
+  it('records the verdict beside the row, and reports "nobody asked" until someone does', async () => {
+    stubApi({
+      refreshDocument: () => Promise.resolve({ document: doc(), freshness: CONFIRMED }),
+    })
+    const store = useDocumentsStore()
+
+    // An unasked document has NO verdict. It must not read as unknown-and-therefore-suspect: a
+    // freshly imported page is fine, it simply has not been re-checked since.
+    expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
+
+    await store.refresh('figma', 'file1:1-2')
+
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+    // Stamped with WHEN it was reached, because a verdict never expires: what keeps an hour-old
+    // confirmation from rendering as the present state of a page that has had an hour to move is
+    // that the moment travels with it.
+    expect(store.freshnessFor('figma', 'file1:1-2')?.checkedAt).toBeTypeOf('number')
+    // Scoped to the document that was asked about, never to the source.
+    expect(store.freshnessFor('figma', 'other:9-9')).toBeUndefined()
+  })
+
+  it('never shows one board\u2019s verdict against another board\u2019s row', async () => {
+    // The same Figma file can be imported into two boards, and `(source, externalId)` is identical
+    // in both, so a verdict keyed by that pair alone would render board A's "confirmed, revision
+    // v2" against a board B row nobody has ever checked. That breaks the "absent means nobody has
+    // asked" rule in the one direction nothing can notice, since the wrong answer looks like a
+    // right one.
+    stubApi({
+      refreshDocument: () => Promise.resolve({ document: doc(), freshness: CONFIRMED }),
+    })
+    const store = useDocumentsStore()
+    await store.refresh('figma', 'file1:1-2')
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+
+    useWorkspaceStore().workspaceId = 'ws2'
+
+    expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
+
+    // …and switching back does not lose it: the verdict stays true of the board it was asked on.
+    useWorkspaceStore().workspaceId = 'ws1'
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+  })
+
+  it('does not merge a check that outlived a board switch into the new board\u2019s list', async () => {
+    // The list is the ACTIVE board's and is not keyed by board, so a row arriving after the switch
+    // would be a document from somewhere else appearing on a board that never imported it. The
+    // verdict is still filed, under the board that asked.
+    let resolve!: (v: unknown) => void
+    stubApi({
+      listDocuments: () => Promise.resolve([]),
+      refreshDocument: () =>
+        new Promise((res) => {
+          resolve = res
+        }),
+    })
+    const store = useDocumentsStore()
+    await store.loadDocuments()
+
+    const pending = store.refresh('figma', 'file1:1-2')
+    useWorkspaceStore().workspaceId = 'ws2'
+    resolve({ document: doc(), freshness: CONFIRMED })
+    await pending
+
+    expect(store.documents).toHaveLength(0)
+    useWorkspaceStore().workspaceId = 'ws1'
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+  })
+
+  it('reports in-flight state per document, and clears it when the source refuses', async () => {
+    let reject!: (e: Error) => void
+    stubApi({
+      refreshDocument: () =>
+        new Promise((_res, rej) => {
+          reject = rej
+        }),
+    })
+    const store = useDocumentsStore()
+
+    const pending = store.refresh('figma', 'file1:1-2')
+    expect(store.isRefreshing('figma', 'file1:1-2')).toBe(true)
+    expect(store.isRefreshing('figma', 'other:9-9')).toBe(false)
+
+    reject(new Error('figma 429'))
+    await expect(pending).rejects.toThrow('figma 429')
+
+    // A failure that left the flag set would disable the button that is the whole remedy, and the
+    // person would have no way to try again.
+    expect(store.isRefreshing('figma', 'file1:1-2')).toBe(false)
+    expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
+  })
+})

package/app/stores/documents.ts

@@ -13,6 +13,7 @@ import type {
   SourceDocument,
 } from '~/types/domain'
 import { isConnectableSource } from '@cat-factory/contracts'
+import { useDocumentFreshness } from '~/composables/useDocumentFreshness'
 import { useSourceIntegration } from '~/composables/useSourceIntegration'
 import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -56,6 +57,16 @@ export const useDocumentsStore = defineStore('documents', () => {
   })
   const loading = ref(false)
 
+  // The "is this still the current revision" half, in its own collaborator: a verdict is a
+  // statement about a moment rather than a property of a row, and `useDocumentFreshness` owns why
+  // the two must not merge.
+  const { refresh, freshnessFor, isRefreshing } = useDocumentFreshness({
+    workspaceId: () => workspace.workspaceId,
+    refresh: (source, externalId) =>
+      api.refreshDocument(workspace.requireId(), { source, externalId }),
+    onRefreshed: upsertDoc,
+  })
+
   // Workspace+DocKind template / exemplar role links (WS1). Loaded lazily when the management
   // panel opens; the full list of role-tagged documents across kinds.
   const roleLinks = ref<SourceDocument[]>([])
@@ -224,6 +235,9 @@ export const useDocumentsStore = defineStore('documents', () => {
     loadDocuments,
     resolveRef,
     importDocument,
+    refresh,
+    freshnessFor,
+    isRefreshing,
     search,
     plan,
     spawn,

package/app/types/documents.ts

@@ -15,6 +15,10 @@ export type {
   CredentialField,
   DocumentSourceDescriptor,
   DocumentConnection,
+  DocumentFreshness,
+  DocumentFreshnessChange,
+  DocumentFreshnessGap,
+  RefreshedDocumentView,
   SourceDocument,
   DocumentSearchResult,
   DocumentRefReason,