@startsimpli/ui 0.4.134 → 0.4.136

package/src/components/history/__tests__/record-history-panel.test.tsx

@@ -0,0 +1,312 @@
+/**
+ * The rendered panel (bd startsim-g4rwo).
+ *
+ * The assertions that matter are the presentation rules, not the markup: a
+ * machine is always marked, a claimed person never is, `unknown` is CALM and
+ * explained once for the panel, a withheld field is named rather than shown as
+ * "changed to nothing", an attempt reads as an attempt, and the empty state
+ * never claims the record was never changed.
+ */
+import { render, screen, waitFor, fireEvent, within } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+import { ActorIdentity } from '../../ActorIdentity'
+import { RecordHistoryPanel } from '../RecordHistoryPanel'
+import type { EntityRevision, RevisionPage } from '../types'
+
+function mount(ui: React.ReactElement) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: 0 } },
+  })
+  return render(<QueryClientProvider client={client}>{ui}</QueryClientProvider>)
+}
+
+const T0 = Date.parse('2026-10-05T12:00:00.000Z')
+const at = (ms: number) => new Date(T0 + ms).toISOString()
+
+function rev(over: Partial<EntityRevision> & { version: number }): EntityRevision {
+  return {
+    id: `r${over.version}`,
+    action: 'updated',
+    source: 'patch',
+    precondition: 'none',
+    created_at: at(0),
+    actor_sub: 'u1',
+    actor_label: 'jurga@ogmc.example',
+    actor_kind: 'person',
+    actor_kind_source: 'claim',
+    metadata: { changed: { blog: { before: 'old', after: 'new' } } },
+    ...over,
+  }
+}
+
+function page(results: EntityRevision[], over: Partial<RevisionPage> = {}): RevisionPage {
+  return { count: results.length, next: null, previous: null, results, ...over }
+}
+
+const clientFor = (p: RevisionPage) => ({ list: jest.fn().mockResolvedValue(p) })
+
+describe('RecordHistoryPanel — the actor axis', () => {
+  it('ALWAYS marks a machine, and distinctly from a person', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({
+              version: 2,
+              actor_sub: 'svc:n8n-ogmc',
+              actor_label: 'svc:n8n-ogmc',
+              actor_kind: 'machine',
+              actor_kind_source: 'inferred',
+            }),
+            rev({ version: 1, created_at: at(-600_000) }),
+          ]),
+        )}
+      />,
+    )
+    const marks = await screen.findAllByTestId('actor-kind')
+    // Exactly ONE marker: the machine row. The claimed person gets none.
+    expect(marks).toHaveLength(1)
+    expect(marks[0]).toHaveTextContent('machine')
+  })
+
+  it('does NOT decorate a claimed person — the calm, common-good case', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    await screen.findByTestId('record-history-panel')
+    expect(screen.queryByTestId('actor-kind')).not.toBeInTheDocument()
+  })
+
+  it('renders UNKNOWN with no per-row badge, and explains it ONCE for the panel', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({ version: 2, actor_kind: 'unknown', actor_kind_source: 'inferred' }),
+            rev({
+              version: 1,
+              created_at: at(-600_000),
+              actor_kind: 'unknown',
+              actor_kind_source: 'inferred',
+            }),
+          ]),
+        )}
+      />,
+    )
+    const note = await screen.findByTestId('record-history-unknown-kind')
+    // ONE sentence for two unknown rows — not a badge per row, which is what
+    // would make the panel look broken for the whole rollout window.
+    expect(note).toBeInTheDocument()
+    expect(screen.queryByTestId('actor-kind')).not.toBeInTheDocument()
+    // And it must not read as a defect.
+    expect(note.textContent).toMatch(/not recorded/i)
+    expect(note.textContent).not.toMatch(/error|invalid|fail|broken|warning/i)
+  })
+
+  it('still says WHO on an unknown row — only the KIND is unrecorded', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(page([rev({ version: 1, actor_kind: 'unknown' })]))}
+      />,
+    )
+    expect(await screen.findByText('jurga@ogmc.example')).toBeInTheDocument()
+  })
+
+  it('does NOT show the unknown explanation when every row has a kind', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    await screen.findByTestId('record-history-panel')
+    expect(screen.queryByTestId('record-history-unknown-kind')).not.toBeInTheDocument()
+  })
+
+  it('marks a person whose kind was INFERRED, because that is a guess', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(page([rev({ version: 1, actor_kind_source: 'inferred' })]))}
+      />,
+    )
+    const mark = await screen.findByTestId('actor-kind')
+    expect(mark).toHaveTextContent(/inferred/)
+  })
+})
+
+describe('RecordHistoryPanel — redaction', () => {
+  it('names a withheld field at panel level instead of rendering it as empty', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([rev({ version: 1, metadata: { changed: { body: {} } }, redacted_fields: ['body'] })], {
+            redacted_fields: ['body'],
+          }),
+        )}
+      />,
+    )
+    const note = await screen.findByTestId('record-history-redacted')
+    expect(note).toHaveTextContent(/body/)
+    expect(note).toHaveTextContent(/not shown to you/i)
+  })
+
+  it('says a withheld field was changed but its values are not shown', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([rev({ version: 1, metadata: { changed: { body: {} } }, redacted_fields: ['body'] })]),
+        )}
+      />,
+    )
+    const row = await screen.findByRole('button', { name: /body/ })
+    expect(row).toHaveTextContent(/not shown to you/i)
+    fireEvent.click(row)
+    expect(await screen.findByText(/its\s*values are not shown to you/i)).toBeInTheDocument()
+  })
+
+  it('reads the camelised envelope roll-up too', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([rev({ version: 1, metadata: { changed: { body: {} } }, redactedFields: ['body'] })], {
+            redactedFields: ['body'],
+          }),
+        )}
+      />,
+    )
+    expect(await screen.findByTestId('record-history-redacted')).toHaveTextContent(/body/)
+  })
+})
+
+describe('RecordHistoryPanel — attempts, truncation and completeness', () => {
+  it('an ATTEMPT reads as an attempt, never as a change', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({
+              version: 1,
+              actor_sub: 'svc:n8n-ogmc',
+              actor_label: 'svc:n8n-ogmc',
+              actor_kind: 'machine',
+              actor_kind_source: 'inferred',
+              metadata: { changed: {}, preserved: ['team_verdict'] },
+            }),
+          ]),
+        )}
+      />,
+    )
+    expect(
+      await screen.findByText(/Tried to write team_verdict — held back/),
+    ).toBeInTheDocument()
+    expect(screen.getByTestId('revision-preserved')).toHaveTextContent(/was not written/i)
+  })
+
+  it('REFUSES to diff a truncated side and says why', async () => {
+    mount(
+      <RecordHistoryPanel
+        client={clientFor(
+          page([
+            rev({
+              version: 1,
+              metadata: { changed: { blog: { before: 'prefix only', after: 'other', truncated: true } } },
+            }),
+          ]),
+        )}
+      />,
+    )
+    const row = await screen.findByRole('button', { name: /blog/ })
+    expect(row).toHaveTextContent(/too large to store/i)
+    fireEvent.click(row)
+    expect(
+      await screen.findByText(/a missing side means nothing here/i),
+    ).toBeInTheDocument()
+  })
+
+  it('NEVER claims the trail is complete', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    const note = await screen.findByTestId('record-history-incomplete')
+    expect(note).toHaveTextContent(/not recorded yet/i)
+  })
+
+  it('an empty history says "no edits recorded", not "never changed"', async () => {
+    mount(<RecordHistoryPanel client={clientFor(page([]))} />)
+    expect(await screen.findByText('No edits recorded for this record')).toBeInTheDocument()
+    expect(screen.queryByText(/never been changed|never changed/i)).not.toBeInTheDocument()
+    // The caveat still stands on an empty panel — a quiet trail is the exact
+    // case a reader would otherwise over-read.
+    expect(screen.getByTestId('record-history-incomplete')).toBeInTheDocument()
+  })
+})
+
+describe('RecordHistoryPanel — valid HTML', () => {
+  it('never nests the field list inside a <p>', async () => {
+    // REGRESSION (bd startsim-g4rwo): ActivityTimeline wrapped `detail` in a
+    // <p>, and a <ul>/<div> inside a <p> is invalid HTML that React reparents
+    // during hydration — a hydration mismatch on EVERY row. tsc passed and
+    // jsdom rendered it happily; only a real browser reported it.
+    mount(<RecordHistoryPanel client={clientFor(page([rev({ version: 1 })]))} />)
+    const fields = await screen.findByTestId('revision-fields')
+    expect(fields.closest('p')).toBeNull()
+  })
+})
+
+describe('RecordHistoryPanel — fetching', () => {
+  it('asks the server for pages, never for everything (rule 8)', async () => {
+    const client = clientFor(page([rev({ version: 1 })]))
+    mount(<RecordHistoryPanel client={client} pageSize={25} />)
+    await screen.findByTestId('record-history-panel')
+    expect(client.list).toHaveBeenCalledWith({ page: 1, pageSize: 25 })
+  })
+
+  it('folds across page boundaries — one sitting, not one per page', async () => {
+    const list = jest
+      .fn()
+      .mockResolvedValueOnce(
+        page([rev({ version: 2, created_at: at(2000) })], { count: 3, next: 'p2' }),
+      )
+      .mockResolvedValueOnce(page([rev({ version: 1, created_at: at(0) })], { count: 3 }))
+    mount(<RecordHistoryPanel client={{ list }} pageSize={1} />)
+    await screen.findByTestId('record-history-panel')
+    // jsdom has no IntersectionObserver, so the auto-load sentinel no-ops by
+    // design and the explicit button is the path under test.
+    fireEvent.click(await screen.findByRole('button', { name: 'Load more' }))
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(2))
+    // Both rows are the same actor inside the window, so after the second page
+    // loads they are ONE entry reporting 2 saves.
+    await waitFor(() => expect(screen.getByText('2 saves')).toBeInTheDocument())
+  })
+
+  it('a 404 says the history is not available, never "no history"', async () => {
+    const list = jest.fn().mockRejectedValue(Object.assign(new Error('Not Found'), { status: 404 }))
+    mount(<RecordHistoryPanel client={{ list }} />)
+    expect(await screen.findByText('History is not available to you')).toBeInTheDocument()
+    expect(screen.queryByText('No edits recorded for this record')).not.toBeInTheDocument()
+  })
+
+  it('any other failure offers a retry', async () => {
+    const list = jest.fn().mockRejectedValue(new Error('boom'))
+    mount(<RecordHistoryPanel client={{ list }} />)
+    expect(await screen.findByText('Could not load history')).toBeInTheDocument()
+  })
+})
+
+describe('ActorIdentity — the kind props are additive', () => {
+  it('renders exactly as before when no kind is passed', () => {
+    const { container } = render(<ActorIdentity actor={{ email: 'a@b.com' }} />)
+    expect(container.querySelector('[data-testid="actor-kind"]')).toBeNull()
+    expect(screen.getByTestId('actor-identity')).toHaveTextContent('a@b.com')
+  })
+
+  it('still renders the machine marker when the actor has NO label at all', () => {
+    // A service token can carry no email; dropping the row would hide the one
+    // fact the actor axis exists to record.
+    render(<ActorIdentity actor={{}} kind="machine" kindSource="inferred" />)
+    expect(screen.getByTestId('actor-kind')).toHaveTextContent('machine')
+  })
+
+  it('renders nothing at all when there is neither a label nor a kind worth marking', () => {
+    const { container } = render(<ActorIdentity actor={{}} kind="unknown" />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('carries the full truth in the title even when it draws no marker', () => {
+    render(<ActorIdentity actor={{ email: 'a@b.com' }} kind="unknown" />)
+    const el = screen.getByTestId('actor-identity')
+    expect(el).toHaveAttribute('data-actor-kind', 'unknown')
+  })
+})

package/src/components/history/__tests__/revision-history.test.ts

@@ -0,0 +1,355 @@
+/**
+ * The fold, and what one field change SAYS (bd startsim-g4rwo).
+ *
+ * Every case here is one of the server contract's edge cases that a naive
+ * reading gets wrong — absence vs null, truncation gating the delete
+ * inference, `{}` meaning three different things, and the four fold refusals.
+ * Pure module, so none of it needs a render or a backend.
+ */
+import {
+  COLLAPSE_WINDOW_MS,
+  actorKindOf,
+  actorKindSourceOf,
+  canDiffFieldChange,
+  classifyFieldChange,
+  foldRevisions,
+  normalizeFieldChange,
+  normalizeRevision,
+  sittingHeadline,
+  sittingSummary,
+} from '../revision-history'
+import type { EntityRevision } from '../types'
+
+const T0 = Date.parse('2026-10-05T12:00:00.000Z')
+const at = (msAfter: number) => new Date(T0 + msAfter).toISOString()
+
+function rev(over: Partial<EntityRevision> & { version: number }): EntityRevision {
+  return {
+    id: `r${over.version}`,
+    action: 'updated',
+    source: 'patch',
+    precondition: 'none',
+    created_at: at(0),
+    actor_sub: 'u1',
+    actor_label: 'jurga@ogmc.example',
+    actor_kind: 'person',
+    actor_kind_source: 'claim',
+    metadata: { changed: {} },
+    ...over,
+  }
+}
+
+describe('actorKindOf — three-state, failing closed', () => {
+  it('reads person and machine', () => {
+    expect(actorKindOf(rev({ version: 1, actor_kind: 'person' }))).toBe('person')
+    expect(actorKindOf(rev({ version: 1, actor_kind: 'machine' }))).toBe('machine')
+  })
+
+  it('reads an ABSENT kind as unknown, never as person', () => {
+    expect(actorKindOf({ id: 'x', version: 1 })).toBe('unknown')
+    expect(actorKindOf(rev({ version: 1, actor_kind: null }))).toBe('unknown')
+    expect(actorKindOf(rev({ version: 1, actor_kind: '' }))).toBe('unknown')
+  })
+
+  it('reads a value from outside the vocabulary as unknown', () => {
+    expect(actorKindOf(rev({ version: 1, actor_kind: 'robot' }))).toBe('unknown')
+  })
+
+  it('reads the CAMELISED spelling the shared API client produces', () => {
+    expect(actorKindOf({ id: 'x', version: 1, actorKind: 'machine' })).toBe('machine')
+    expect(actorKindSourceOf({ id: 'x', version: 1, actorKindSource: 'inferred' })).toBe('inferred')
+  })
+
+  it('distinguishes a claimed kind from an inferred one', () => {
+    expect(actorKindSourceOf(rev({ version: 1, actor_kind_source: 'claim' }))).toBe('claim')
+    expect(actorKindSourceOf(rev({ version: 1, actor_kind_source: 'inferred' }))).toBe('inferred')
+    expect(actorKindSourceOf({ id: 'x', version: 1 })).toBeUndefined()
+  })
+})
+
+describe('normalizeFieldChange — absence is the payload', () => {
+  it('a CREATED key has after and no before', () => {
+    const c = normalizeFieldChange({ after: 'hello' })
+    expect(c.hasBefore).toBe(false)
+    expect(c.hasAfter).toBe(true)
+    expect(classifyFieldChange(c)).toBe('created')
+  })
+
+  it('a DELETED key has before and no after', () => {
+    const c = normalizeFieldChange({ before: 'gone' })
+    expect(c.hasAfter).toBe(false)
+    expect(classifyFieldChange(c)).toBe('deleted')
+  })
+
+  it('a key set to NULL is an update, not a deletion — null is a real value', () => {
+    const c = normalizeFieldChange({ before: 'x', after: null })
+    expect(c.hasAfter).toBe(true)
+    expect(c.after).toBeNull()
+    expect(classifyFieldChange(c)).toBe('updated')
+  })
+
+  it('a key created AS null is created, not deleted', () => {
+    const c = normalizeFieldChange({ after: null })
+    expect(classifyFieldChange(c)).toBe('created')
+  })
+
+  it('a WITHHELD key is {} and classifies as withheld, not as a deletion', () => {
+    expect(classifyFieldChange(normalizeFieldChange({}, { withheld: true }))).toBe('withheld')
+  })
+
+  it('an OMITTED row’s key is {} and classifies as omitted', () => {
+    expect(classifyFieldChange(normalizeFieldChange({}, { omitted: true }))).toBe('omitted')
+  })
+
+  it('TRUNCATION WINS over the delete inference — a missing side says nothing', () => {
+    // before present, after absent, but truncated: this is NOT a deletion.
+    const c = normalizeFieldChange({ before: 'a very long prefix', truncated: true })
+    expect(classifyFieldChange(c)).toBe('truncated')
+    expect(classifyFieldChange(c)).not.toBe('deleted')
+  })
+
+  it('refuses to diff a truncated, withheld or omitted side', () => {
+    expect(canDiffFieldChange(normalizeFieldChange({ before: 'a', after: 'b', truncated: true }))).toBe(false)
+    expect(canDiffFieldChange(normalizeFieldChange({}, { withheld: true }))).toBe(false)
+    expect(canDiffFieldChange(normalizeFieldChange({}, { omitted: true }))).toBe(false)
+  })
+
+  it('diffs only when both sides are text', () => {
+    expect(canDiffFieldChange(normalizeFieldChange({ before: 'a', after: 'b' }))).toBe(true)
+    expect(canDiffFieldChange(normalizeFieldChange({ before: { a: 1 }, after: { a: 2 } }))).toBe(false)
+    expect(canDiffFieldChange(normalizeFieldChange({ after: 'new' }))).toBe(false)
+  })
+})
+
+describe('normalizeRevision', () => {
+  it('marks a field named in redacted_fields as withheld', () => {
+    const n = normalizeRevision(
+      rev({ version: 3, metadata: { changed: { body: {} } }, redacted_fields: ['body'] }),
+    )
+    expect(n.changed.body!.withheld).toBe(true)
+    expect(n.redacted).toEqual(['body'])
+  })
+
+  it('marks every field omitted when the ROW was over the cap', () => {
+    const n = normalizeRevision(
+      rev({ version: 3, metadata: { changed: { a: {}, b: {} }, values_omitted: true } }),
+    )
+    expect(n.valuesOmitted).toBe(true)
+    expect(n.changed.a!.omitted).toBe(true)
+    expect(n.changed.b!.omitted).toBe(true)
+  })
+
+  it('reads values_omitted in its camelised spelling too', () => {
+    const n = normalizeRevision(rev({ version: 1, metadata: { changed: { a: {} }, valuesOmitted: true } }))
+    expect(n.valuesOmitted).toBe(true)
+  })
+
+  it('a PRESERVED row with no changes is an ATTEMPT', () => {
+    const n = normalizeRevision(
+      rev({ version: 4, metadata: { changed: {}, preserved: ['blog'] } }),
+    )
+    expect(n.isAttempt).toBe(true)
+    expect(n.preserved).toEqual(['blog'])
+  })
+
+  it('a row that both changed and preserved something is NOT an attempt', () => {
+    const n = normalizeRevision(
+      rev({ version: 4, metadata: { changed: { seo: { after: 'x' } }, preserved: ['blog'] } }),
+    )
+    expect(n.isAttempt).toBe(false)
+  })
+
+  it('survives a row with no metadata at all', () => {
+    const n = normalizeRevision({ id: 'x', version: 1 })
+    expect(n.changed).toEqual({})
+    expect(n.isAttempt).toBe(false)
+    expect(n.actorKind).toBe('unknown')
+  })
+})
+
+describe('foldRevisions', () => {
+  it('folds consecutive same-actor saves inside the window into one sitting', () => {
+    const rows = [
+      rev({ version: 3, created_at: at(4000), metadata: { changed: { blog: { before: 'b', after: 'c' } } } }),
+      rev({ version: 2, created_at: at(2000), metadata: { changed: { blog: { before: 'a', after: 'b' } } } }),
+      rev({ version: 1, created_at: at(0), action: 'created', metadata: { changed: { blog: { after: 'a' } } } }),
+    ]
+    const folded = foldRevisions(rows)
+    // The create does not absorb the later edits.
+    expect(folded).toHaveLength(2)
+    expect(folded[0]!.saves).toBe(2)
+    expect(folded[1]!.action).toBe('created')
+  })
+
+  it('takes BEFORE from the oldest row and AFTER from the newest', () => {
+    const rows = [
+      rev({ version: 3, created_at: at(4000), metadata: { changed: { blog: { before: 'two', after: 'three' } } } }),
+      rev({ version: 2, created_at: at(2000), metadata: { changed: { blog: { before: 'one', after: 'two' } } } }),
+    ]
+    const [sitting] = foldRevisions(rows)
+    expect(sitting!.changed.blog!.before).toBe('one')
+    expect(sitting!.changed.blog!.after).toBe('three')
+    expect(sitting!.fromVersion).toBe(2)
+    expect(sitting!.toVersion).toBe(3)
+  })
+
+  it('does not fold across the window', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(COLLAPSE_WINDOW_MS + 1000) }),
+      rev({ version: 1, created_at: at(0) }),
+    ]
+    expect(foldRevisions(rows)).toHaveLength(2)
+  })
+
+  it('does not fold two different actors', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), actor_sub: 'u2', actor_label: 'b@x' }),
+      rev({ version: 1, created_at: at(0), actor_sub: 'u1', actor_label: 'a@x' }),
+    ]
+    expect(foldRevisions(rows)).toHaveLength(2)
+  })
+
+  it('REFUSES to fold across a differing actor_kind even when the sub matches', () => {
+    // The healing window: one person's rows read unknown then person. Folding
+    // would stamp the sitting with whichever end won.
+    const rows = [
+      rev({ version: 2, created_at: at(1000), actor_kind: 'person', actor_kind_source: 'claim' }),
+      rev({ version: 1, created_at: at(0), actor_kind: 'unknown', actor_kind_source: 'inferred' }),
+    ]
+    const folded = foldRevisions(rows)
+    expect(folded).toHaveLength(2)
+    expect(folded[0]!.actorKind).toBe('person')
+    expect(folded[1]!.actorKind).toBe('unknown')
+  })
+
+  it('REFUSES to fold across a differing actor_kind_source', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), actor_kind_source: 'claim' }),
+      rev({ version: 1, created_at: at(0), actor_kind_source: 'inferred' }),
+    ]
+    expect(foldRevisions(rows)).toHaveLength(2)
+  })
+
+  it('REFUSES to fold an ATTEMPT into a change', () => {
+    const rows = [
+      rev({
+        version: 2,
+        created_at: at(1000),
+        actor_sub: 'svc:n8n',
+        actor_kind: 'machine',
+        actor_kind_source: 'inferred',
+        metadata: { changed: {}, preserved: ['blog'] },
+      }),
+      rev({
+        version: 1,
+        created_at: at(0),
+        actor_sub: 'svc:n8n',
+        actor_kind: 'machine',
+        actor_kind_source: 'inferred',
+        metadata: { changed: { seo: { after: 'x' } } },
+      }),
+    ]
+    const folded = foldRevisions(rows)
+    expect(folded).toHaveLength(2)
+    expect(folded[0]!.isAttempt).toBe(true)
+    expect(folded[1]!.isAttempt).toBe(false)
+  })
+
+  it('folds two attempts together', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), metadata: { changed: {}, preserved: ['seo'] } }),
+      rev({ version: 1, created_at: at(0), metadata: { changed: {}, preserved: ['blog'] } }),
+    ]
+    const folded = foldRevisions(rows)
+    expect(folded).toHaveLength(1)
+    expect(folded[0]!.preserved).toEqual(['blog', 'seo'])
+  })
+
+  it('carries a withheld flag FORWARD through a fold rather than dropping it', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), metadata: { changed: { body: { before: 'x', after: 'y' } } } }),
+      rev({ version: 1, created_at: at(0), metadata: { changed: { body: {} } }, redacted_fields: ['body'] }),
+    ]
+    const [sitting] = foldRevisions(rows)
+    expect(sitting!.saves).toBe(2)
+    expect(sitting!.changed.body!.withheld).toBe(true)
+    expect(sitting!.redacted).toEqual(['body'])
+    expect(canDiffFieldChange(sitting!.changed.body!)).toBe(false)
+  })
+
+  it('carries a truncated flag forward, so a fold never produces a clean diff from a capped side', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000), metadata: { changed: { blog: { before: 'b', after: 'c' } } } }),
+      rev({ version: 1, created_at: at(0), metadata: { changed: { blog: { before: 'a', truncated: true } } } }),
+    ]
+    const [sitting] = foldRevisions(rows)
+    expect(sitting!.changed.blog!.truncated).toBe(true)
+    expect(canDiffFieldChange(sitting!.changed.blog!)).toBe(false)
+  })
+
+  it('windowMs of 0 renders a row per save', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(1000) }),
+      rev({ version: 1, created_at: at(0) }),
+    ]
+    expect(foldRevisions(rows, 0)).toHaveLength(2)
+  })
+
+  it('treats an out-of-order clock as the same sitting rather than inventing a precedence', () => {
+    const rows = [rev({ version: 2, created_at: at(0) }), rev({ version: 1, created_at: at(0) })]
+    expect(foldRevisions(rows)).toHaveLength(1)
+  })
+
+  it('returns nothing for an empty trail', () => {
+    expect(foldRevisions([])).toEqual([])
+  })
+})
+
+describe('sittingSummary / sittingHeadline', () => {
+  const sit = (rows: EntityRevision[]) => foldRevisions(rows)[0]!
+
+  it('a single save does not claim to be a sitting', () => {
+    expect(sittingSummary(sit([rev({ version: 1 })]))).toBe('1 save')
+  })
+
+  it('a collapsed sitting says it is a collapse, with its span', () => {
+    const rows = [
+      rev({ version: 2, created_at: at(120_000) }),
+      rev({ version: 1, created_at: at(0) }),
+    ]
+    expect(sittingSummary(sit(rows))).toBe('2 saves over 2 min')
+  })
+
+  it('a sub-minute burst reports the count without a misleading 0 min', () => {
+    const rows = [rev({ version: 2, created_at: at(3000) }), rev({ version: 1, created_at: at(0) })]
+    expect(sittingSummary(sit(rows))).toBe('2 saves')
+  })
+
+  it('names the fields it edited', () => {
+    const s = sit([rev({ version: 1, metadata: { changed: { blog: { after: 'x' }, seo: { after: 'y' } } } })])
+    expect(sittingHeadline(s)).toBe('Edited blog and seo')
+  })
+
+  it('counts instead of listing beyond three fields', () => {
+    const changed = Object.fromEntries(['a', 'b', 'c', 'd'].map((k) => [k, { after: '1' }]))
+    const s = sit([rev({ version: 1, metadata: { changed } })])
+    expect(sittingHeadline(s)).toBe('Edited 4 fields')
+  })
+
+  it('AN ATTEMPT READS AS AN ATTEMPT — the sentence nobody could produce', () => {
+    const s = sit([
+      rev({ version: 1, metadata: { changed: {}, preserved: ['team_verdict'] } }),
+    ])
+    expect(sittingHeadline(s)).toBe('Tried to write team_verdict — held back')
+  })
+
+  it('a name-only move reads as a rename', () => {
+    const s = sit([rev({ version: 2, metadata: { changed: {}, name: { before: 'a', after: 'b' } } })])
+    expect(sittingHeadline(s)).toBe('Renamed the record')
+  })
+
+  it('applies a fieldLabel mapping', () => {
+    const s = sit([rev({ version: 1, metadata: { changed: { team_verdict: { after: 'x' } } } })])
+    expect(sittingHeadline(s, (f) => f.replace('_', ' '))).toBe('Edited team verdict')
+  })
+})