@startsimpli/integrations 0.2.25 → 0.2.27

package/src/__tests__/corpus-planning.test.tsx

@@ -0,0 +1,556 @@
+/**
+ * THE PLANNING TOOLSET (bd startsim-8l6ef).
+ *
+ * The screen makes one claim the tracker does not — "an extracted item and one
+ * you typed are the same list, and you can still tell them apart" — and every
+ * case below is a way that could be false on screen while the database is fine.
+ *
+ * Three of them are regression tests for bugs that were live in this branch and
+ * would each have shipped a silent wrong answer rather than an error:
+ *
+ *   1. a `Commitment.origin` field whose mapper wrote the key `origin` while the
+ *      tenant indexes `_origin` — every filter over it returns an empty page;
+ *   2. an authored item with no `first_seen_at`/`last_seen_at`, which vanishes
+ *      from three of the tracker's four tabs while sitting in the same table;
+ *   3. a `focus` filter the server answers as `related_to`, which — unreconciled
+ *      — makes the screen announce that the workspace did not filter by focus
+ *      while it verifiably did.
+ */
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PlanningPage } from '../components/pages/PlanningPage';
+import { createPlanningApi } from '../corpus/client';
+import { ORIGIN, ORIGIN_KEY, commitmentToEntity, toCommitment } from '../corpus/entities';
+import {
+  authoredItemToEntity,
+  displayProgress,
+  focusProgress,
+  focusSlug,
+  focusToEntity,
+  isAuthored,
+  toFocus,
+} from '../corpus/planning';
+import type {
+  Commitment,
+  CorpusPage,
+  Focus,
+  FocusStanding,
+  PlanningApi,
+} from '../corpus/types';
+
+const NOW = Date.parse('2026-08-26T12:00:00Z');
+const SCOPE = { orgId: 'tandem' };
+
+function commitment(
+  overrides: Partial<Commitment> & { externalId: string; title: string },
+): Commitment {
+  return {
+    id: overrides.externalId,
+    dedupeKey: overrides.externalId.replace('commit:', ''),
+    subtype: 'action',
+    detail: '',
+    status: 'open',
+    subjectKey: '',
+    actionKey: '',
+    mentions: [{
+      documentId: 'doc_1',
+      originKey: 'rules:x',
+      occurredAt: '2026-08-01T15:00:00Z',
+      quote: 'Jonathan to complete a filing before the next call.',
+      extractor: 'rules',
+    }],
+    firstSeenAt: '2026-08-01T15:00:00Z',
+    lastSeenAt: '2026-08-01T15:00:00Z',
+    extractorVersion: 'rules+model@1',
+    source: 'granola',
+    sourceLabel: 'Granola',
+    scope: SCOPE,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  the origin key
+// ---------------------------------------------------------------------------
+
+describe('_origin — the key the tenant actually indexes', () => {
+  it('writes the literal underscore key, not a field named origin', () => {
+    /**
+     * THE BUG THIS PINS. `camelToSnakeKey('origin')` is `origin`, a DIFFERENT
+     * `data` key from `_origin` — which is what three writers have used for
+     * months and what the tenant declares an AttributeDef for. A mapper that
+     * emitted `origin` would write to a key nothing indexes, and every
+     * `?attr._origin=` filter would answer 200/count:0 forever with no error.
+     */
+    const payload = commitmentToEntity(
+      commitment({ externalId: 'item:a', title: 'Renew the lease', origin: ORIGIN.authored }),
+    );
+    expect(payload.data[ORIGIN_KEY]).toBe('human');
+    expect(ORIGIN_KEY).toBe('_origin');
+    expect(payload.data).not.toHaveProperty('origin');
+  });
+
+  it('does not relabel an authored item as extracted when it passes back through the bulk upsert', () => {
+    // Otherwise a human's item would come back claiming a meeting said it — and
+    // it has no mention to contradict the claim.
+    const payload = commitmentToEntity(
+      commitment({ externalId: 'item:a', title: 'Renew the lease', origin: ORIGIN.authored }),
+    );
+    expect(payload.data[ORIGIN_KEY]).toBe(ORIGIN.authored);
+  });
+
+  it('still marks an extractor-written row as extracted', () => {
+    const payload = commitmentToEntity(
+      commitment({ externalId: 'commit:a', title: 'Chase the inventor' }),
+    );
+    expect(payload.data[ORIGIN_KEY]).toBe(ORIGIN.extracted);
+  });
+
+  it('reads BOTH spellings, because the browser client camelCases the key', () => {
+    /**
+     * `snakeToCamelKey('_origin')` is `Origin`, so a row read through
+     * @startsimpli/api in a browser arrives under that name while a plain
+     * server-side fetch sees `_origin`. Reading only one spelling is the bug
+     * that made the deployed Tracker report a filter gap that did not exist.
+     */
+    const fromServer = toCommitment(
+      { id: '1', external_id: 'item:a', name: 'x', data: { title: 'x', _origin: 'human' } },
+      SCOPE,
+    );
+    const fromBrowser = toCommitment(
+      { id: '1', external_id: 'item:a', name: 'x', data: { title: 'x', Origin: 'human' } },
+      SCOPE,
+    );
+    expect(fromServer.origin).toBe('human');
+    expect(fromBrowser.origin).toBe('human');
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  authored items
+// ---------------------------------------------------------------------------
+
+describe('an authored item', () => {
+  it('stamps both timestamps, or it disappears from three of four tabs', () => {
+    /**
+     * THE BUG THIS PINS, and it is invisible rather than loud. "Changed this
+     * week" filters on `last_seen_at`; the age line reads `first_seen_at`; the
+     * server-side `changedAfter` is a `attr.last_seen_at__gte` that a null never
+     * matches. An authored item with neither sits in the same table as the
+     * extracted ones and shows up in one view out of four — which makes the
+     * whole "one list" claim false on screen while it stays true in the DB.
+     */
+    const payload = authoredItemToEntity({ title: 'Renew the office lease' }, { now: NOW });
+    expect(payload.data.first_seen_at).toBe(new Date(NOW).toISOString());
+    expect(payload.data.last_seen_at).toBe(new Date(NOW).toISOString());
+  });
+
+  it('cannot collide with an extracted row', () => {
+    const payload = authoredItemToEntity({ title: 'x' }, { id: 'abc', now: NOW });
+    expect(payload.external_id).toBe('item:abc');
+    expect(payload.external_id.startsWith('commit:')).toBe(false);
+  });
+
+  it('writes an EMPTY mention list rather than omitting the key', () => {
+    // The row renderer branches on "no mentions"; "authored, so no meeting" and
+    // "the key is missing" must not be the same shape.
+    const payload = authoredItemToEntity({ title: 'x' }, { now: NOW });
+    expect(payload.data.mentions).toEqual([]);
+    expect(payload.data.mention_count).toBe(0);
+  });
+
+  it('defaults to an action, and carries a requirement when asked', () => {
+    expect(authoredItemToEntity({ title: 'x' }, { now: NOW }).data.subtype).toBe('action');
+    // `requirement` costs nothing precisely because CommitmentSubtype is a
+    // string rather than an enum.
+    expect(
+      authoredItemToEntity({ title: 'x', subtype: 'requirement' }, { now: NOW }).data.subtype,
+    ).toBe('requirement');
+  });
+
+  it('is recognisable as authored from either the origin or the id', () => {
+    expect(isAuthored(commitment({ externalId: 'item:a', title: 'x' }))).toBe(true);
+    expect(isAuthored(commitment({
+      externalId: 'x', title: 'x', origin: ORIGIN.authored,
+    }))).toBe(true);
+    expect(isAuthored(commitment({ externalId: 'commit:a', title: 'x' }))).toBe(false);
+  });
+
+  it('lands in the same list as an extracted item, and reads honestly', async () => {
+    // The placement argument, on screen. Both rows render; each says where it
+    // came from; neither claims a meeting it did not have.
+    render(
+      <PlanningPage
+        api={fakeApi({
+          items: [
+            commitment({ externalId: 'commit:a', title: 'Chase the inventor for 2148' }),
+            {
+              ...commitment({ externalId: 'item:b', title: 'Renew the office lease' }),
+              mentions: [], origin: ORIGIN.authored, firstSeenAt: null, lastSeenAt: null,
+            },
+          ],
+        })}
+        scope={SCOPE}
+        now={NOW}
+      />,
+    );
+    expect(await screen.findByText('Chase the inventor for 2148')).toBeTruthy();
+    expect(screen.getByText('Renew the office lease')).toBeTruthy();
+    expect(screen.getByText('Added by hand')).toBeTruthy();
+    // ...and the extracted one still cites its meeting rather than being
+    // flattened into the same line.
+    expect(screen.getByText('From 1 meeting')).toBeTruthy();
+    // The bug this replaces: "From 0 meetings" over an empty disclosure.
+    expect(screen.queryByText('From 0 meetings')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  focuses
+// ---------------------------------------------------------------------------
+
+describe('focus mapping', () => {
+  it('keeps an absent target absent rather than coercing it to zero', () => {
+    /**
+     * `target_value`'s absence is `Goal.is_measurable`'s switch. A 0 would turn
+     * every qualitative focus into a measurable one that is fully achieved.
+     */
+    const focus = toFocus(
+      { id: '1', external_id: 'focus:a', name: 'Ship v2', data: { title: 'Ship v2' } },
+      SCOPE,
+    );
+    expect(focus.targetValue).toBeUndefined();
+    expect(focus.currentValue).toBeUndefined();
+    expect(focusProgress(focus, null)).toBeNull();
+  });
+
+  it('falls back to draft rather than active on an unrecognised status', () => {
+    // A row whose status did not survive a round trip must not present as work
+    // somebody committed to.
+    const focus = toFocus(
+      { id: '1', external_id: 'focus:a', name: 'x', data: { title: 'x', status: 'nonsense' } },
+      SCOPE,
+    );
+    expect(focus.status).toBe('draft');
+  });
+
+  it('round-trips the Goal vocabulary', () => {
+    const payload = focusToEntity({
+      title: 'Close the Series A', status: 'at_risk', category: 'financial',
+      timeFrame: 'Q3', year: 2026, targetValue: 2_000_000, currentValue: 500_000, unit: 'usd',
+    });
+    expect(payload.data).toMatchObject({
+      title: 'Close the Series A', status: 'at_risk', category: 'financial',
+      time_frame: 'Q3', year: 2026, target_value: 2_000_000, current_value: 500_000, unit: 'usd',
+    });
+    const back = toFocus({ id: '1', external_id: payload.external_id, name: payload.name, data: payload.data }, SCOPE);
+    expect(back.status).toBe('at_risk');
+    expect(back.timeFrame).toBe('Q3');
+    expect(back.targetValue).toBe(2_000_000);
+  });
+
+  it('derives a slug once, so renaming does not fork the row', () => {
+    expect(focusSlug('Close the Series A!')).toBe('close-the-series-a');
+    expect(focusSlug('   ')).toBe('untitled');
+    expect(focusToEntity({ title: 'Close the Series A' }).external_id).toBe('focus:close-the-series-a');
+    // An explicit external_id wins, which is what an update relies on.
+    expect(focusToEntity({ title: 'Renamed' }, 'focus:close-the-series-a').external_id)
+      .toBe('focus:close-the-series-a');
+  });
+});
+
+describe('progress', () => {
+  const base = (over: Partial<Focus> = {}): Focus => ({
+    id: 'f1', externalId: 'focus:a', title: 'x', detail: '', status: 'active', scope: SCOPE, ...over,
+  });
+  const standing = (done: number, total: number): FocusStanding =>
+    ({ focusId: 'f1', done, total, overdue: 0 });
+
+  it('measures against the target when there is one', () => {
+    expect(focusProgress(base({ targetValue: 100, currentValue: 25 }), null)).toBe(0.25);
+  });
+
+  it('counts items when there is no target', () => {
+    expect(focusProgress(base(), standing(3, 12))).toBe(0.25);
+  });
+
+  it('is null — not zero — when there is nothing to say', () => {
+    // 0% reads as "started and got nowhere" about work nobody has filed
+    // anything under yet.
+    expect(focusProgress(base(), standing(0, 0))).toBeNull();
+    expect(focusProgress(base(), null)).toBeNull();
+  });
+
+  it('clamps rather than rendering over 100%', () => {
+    expect(focusProgress(base({ targetValue: 10, currentValue: 40 }), null)).toBe(1);
+  });
+
+  it('prefers the STORED value, because that is what the server sorts by', () => {
+    // A card showing a number the list was not ordered by makes the sort look
+    // broken.
+    expect(displayProgress(base({ progress: 0.9 }), standing(1, 10))).toBe(0.9);
+    expect(displayProgress(base(), standing(1, 10))).toBe(0.1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  the focus filter, end to end through the client
+// ---------------------------------------------------------------------------
+
+type Body = { data: Record<string, unknown> };
+
+const FOCUS_ROW: Focus = {
+  id: 'f1', externalId: 'focus:a', title: 'Close the Series A', detail: '',
+  status: 'cancelled', scope: SCOPE,
+};
+
+/** A client whose writes can be inspected. */
+function writeSpy() {
+  const posted: unknown[] = [];
+  const http = {
+    get: vi.fn(async () => ({ count: 0, next: null, previous: null, results: [] })),
+    post: vi.fn(async (_path: string, body: unknown) => {
+      posted.push(body);
+      return { id: 'f1', external_id: 'focus:a', name: 'x', data: { title: 'x' } };
+    }),
+  };
+  return { posted, api: createPlanningApi({ http: http as never, scope: SCOPE }) };
+}
+
+describe('filing is an edge, and the client has to say so', () => {
+  function httpSpy(applied: string[] = []) {
+    const calls: Array<{ path: string; params: Record<string, unknown> }> = [];
+    return {
+      calls,
+      http: {
+        get: vi.fn(async (path: string, options?: { params?: Record<string, unknown> }) => {
+          calls.push({ path, params: options?.params ?? {} });
+          return { count: 0, next: null, previous: null, results: [], applied_filters: applied };
+        }),
+        post: vi.fn(async () => ({ id: 'x', external_id: 'item:x', name: 'x', data: {} })),
+      },
+    };
+  }
+
+  it('asks for the focus as an edge walk, in the direction that returns items', async () => {
+    const { calls, http } = httpSpy();
+    const api = createPlanningApi({ http: http as never, scope: SCOPE });
+    await api.listCommitments({ focus: 'focus-uuid' });
+    const params = calls.at(-1)!.params;
+    expect(params.related_to).toBe('focus-uuid');
+    expect(params.related_via).toBe('in_focus');
+    // `in` here returns an empty page rather than an error, so it is asserted.
+    expect(params.related_direction).toBe('out');
+  });
+
+  it('counts a server-reported related_to as the focus filter being HONOURED', async () => {
+    /**
+     * THE BUG THIS PINS. The client asks for `focus`; the server confirms
+     * `related_to`. Unreconciled, the composer's banner tells the user this
+     * workspace's data API did not filter by focus — while the server
+     * verifiably did. Same lie, same cause, as reading one spelling of
+     * `applied_filters`.
+     */
+    const { http } = httpSpy(['related_to', 'attr.status']);
+    const api = createPlanningApi({ http: http as never, scope: SCOPE });
+    const page = await api.listCommitments({ focus: 'focus-uuid', status: 'open' });
+    expect(page.appliedFilters).toContain('focus');
+    expect(page.appliedFilters).toContain('status');
+  });
+
+  it('still reports a genuinely ignored filter', async () => {
+    const { http } = httpSpy(['attr.status']);
+    const api = createPlanningApi({ http: http as never, scope: SCOPE });
+    const page = await api.listCommitments({ focus: 'focus-uuid', status: 'open' });
+    expect(page.appliedFilters).not.toContain('focus');
+  });
+
+  it('filters origin on the underscore attribute', async () => {
+    const { calls, http } = httpSpy();
+    const api = createPlanningApi({ http: http as never, scope: SCOPE });
+    await api.listCommitments({ origin: ORIGIN.authored });
+    expect(calls.at(-1)!.params['attr._origin']).toBe('human');
+  });
+
+  it('counts a focus standing without pulling a single row body', async () => {
+    const { calls, http } = httpSpy();
+    const api = createPlanningApi({ http: http as never, scope: SCOPE });
+    await api.focusStanding!('focus-uuid', NOW);
+    const counting = calls.slice(-3);
+    expect(counting).toHaveLength(3);
+    for (const call of counting) expect(call.params.page_size).toBe(1);
+  });
+
+  it('sends a snake_cased key when its camelCase draft field was patched', async () => {
+    // The map exists because the two names DIFFER. A guard that compared the
+    // wrong side would pass on `ownerName` — where both spellings coincide —
+    // and drop `time_frame` silently.
+    const { posted, api } = writeSpy();
+    await api.updateFocus!(FOCUS_ROW, { timeFrame: 'Q4' });
+    expect((posted.at(-1) as Body).data.time_frame).toBe('Q4');
+  });
+
+  it('sends status when status IS what changed', async () => {
+    // The other half of the pair below. Together they distinguish a working
+    // filter from one that drops everything.
+    const { posted, api } = writeSpy();
+    await api.updateFocus!(FOCUS_ROW, { status: 'completed' });
+    expect((posted.at(-1) as Body).data.status).toBe('completed');
+  });
+
+  it('never lets an edit relabel where the row came from', async () => {
+    // `focusToEntity` stamps `_origin` because a CREATE needs one. Merging that
+    // on every edit would rewrite provenance from a rename.
+    const { posted, api } = writeSpy();
+    await api.updateFocus!(FOCUS_ROW, { title: 'Renamed' });
+    expect((posted.at(-1) as Body).data).not.toHaveProperty('_origin');
+  });
+
+  it('sends only the keys an edit actually changed', async () => {
+    /**
+     * The upsert shallow-merges, so every key in the body is a WRITE. An edit to
+     * an owner must not carry `focusToEntity`'s defaulted `status` — that would
+     * resurrect this cancelled focus from a rename, on live data, silently.
+     */
+    const { posted, api } = writeSpy();
+    await api.updateFocus!(FOCUS_ROW, { ownerName: 'Rae' });
+    const body = posted.at(-1) as Body;
+    expect(body.data.owner_name).toBe('Rae');
+    expect(body.data).not.toHaveProperty('status');
+  });
+
+  it('refuses to unfile when the client has no delete, rather than no-opping', async () => {
+    // A control that appears to unfile and does not is worse than one that is
+    // disabled — the row would sit under a focus it looks removed from.
+    const { api } = writeSpy();
+    const item = commitment({ externalId: 'item:a', title: 'x' });
+    await expect(api.fileCommitment!(item, null)).rejects.toThrow(/cannot unfile/);
+  });
+
+  it('files through the edge endpoint when a focus IS named', async () => {
+    const { posted, api } = writeSpy();
+    const item = commitment({ externalId: 'item:a', title: 'x' });
+    await api.fileCommitment!(item, 'focus-uuid');
+    expect(posted.at(-1)).toMatchObject({
+      rel_type: 'in_focus', source: item.id, target: 'focus-uuid',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  the screen
+// ---------------------------------------------------------------------------
+
+function fakeApi(options: {
+  items?: Commitment[];
+  focuses?: Focus[];
+  standings?: Record<string, FocusStanding>;
+  applied?: string[];
+  onList?: (query: unknown) => void;
+} = {}): PlanningApi {
+  const page = <T,>(results: T[], applied: string[] = []): CorpusPage<T> =>
+    ({ count: results.length, next: null, previous: null, results, appliedFilters: applied });
+  return {
+    listCommitments: async (query) => {
+      options.onList?.(query);
+      return page(options.items ?? [], options.applied ?? ['status']);
+    },
+    listFocuses: async () => page(options.focuses ?? []),
+    focusStanding: async (focusId) =>
+      options.standings?.[focusId] ?? { focusId, total: 0, done: 0, overdue: 0 },
+  };
+}
+
+const FOCUS: Focus = {
+  id: 'f1', externalId: 'focus:series-a', title: 'Close the Series A',
+  detail: '', status: 'at_risk', category: 'financial', scope: SCOPE,
+};
+
+describe('PlanningPage', () => {
+  it('says a focus has nothing filed under it, rather than "0 of 0 done"', async () => {
+    render(
+      <PlanningPage
+        api={fakeApi({ focuses: [FOCUS] })}
+        scope={SCOPE}
+        now={NOW}
+      />,
+    );
+    expect(await screen.findByText('Close the Series A')).toBeTruthy();
+    await waitFor(() => expect(screen.getByText('Nothing filed under this yet')).toBeTruthy());
+  });
+
+  it('reports done over total from counts', async () => {
+    render(
+      <PlanningPage
+        api={fakeApi({
+          focuses: [FOCUS],
+          standings: { f1: { focusId: 'f1', total: 40, done: 12, overdue: 3 } },
+        })}
+        scope={SCOPE}
+        now={NOW}
+      />,
+    );
+    await waitFor(() => expect(screen.getByText(/12 of 40 done/)).toBeTruthy());
+    expect(screen.getByText(/3 overdue/)).toBeTruthy();
+  });
+
+  it('advises about an empty workspace only when it is really empty', async () => {
+    render(<PlanningPage api={fakeApi({ focuses: [] })} scope={SCOPE} now={NOW} />);
+    expect(await screen.findByText(/No focuses yet/)).toBeTruthy();
+  });
+
+  it('stays silent about filtering the server actually did', async () => {
+    render(
+      <PlanningPage
+        api={fakeApi({ focuses: [FOCUS], items: [], applied: ['status', 'focus'] })}
+        scope={SCOPE}
+        now={NOW}
+      />,
+    );
+    await screen.findByText('Close the Series A');
+    await waitFor(() =>
+      expect(screen.queryByText(/did not filter by/)).toBeNull());
+  });
+
+  it('confesses when the server ignored a filter it was given', async () => {
+    const api = fakeApi({ focuses: [FOCUS], items: [], applied: [] });
+    render(<PlanningPage api={api} scope={SCOPE} now={NOW} />);
+    await waitFor(() => expect(screen.getByText(/did not filter by status/)).toBeTruthy());
+  });
+
+  it('does not loop even when the app hands it a NEW api object every render', async () => {
+    /**
+     * The 917-requests-in-ten-minutes guard, carried over from the tracker. An
+     * api built inline in a parent's render is a new identity every pass; if it
+     * is an effect dependency, the load sets state, which renders, which
+     * rebuilds the api.
+     */
+    let calls = 0;
+    function Host() {
+      const [, force] = React.useState(0);
+      React.useEffect(() => { const t = setTimeout(() => force(1), 10); return () => clearTimeout(t); }, []);
+      return (
+        <PlanningPage
+          api={fakeApi({ focuses: [FOCUS], onList: () => { calls += 1; } })}
+          scope={{ orgId: 'tandem' }}
+          now={NOW}
+        />
+      );
+    }
+    render(<Host />);
+    await screen.findByText('Close the Series A');
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    expect(calls).toBeLessThanOrEqual(2);
+  });
+
+  it('hides authoring when the client cannot write', async () => {
+    // A control that appears to work and does not is worse than one that is
+    // absent — the read-only fork is a real deployment, not a degraded one.
+    render(<PlanningPage api={fakeApi({ focuses: [FOCUS] })} scope={SCOPE} now={NOW} />);
+    await screen.findByText('Close the Series A');
+    expect(screen.queryByText('New focus')).toBeNull();
+    expect(screen.queryByPlaceholderText('What needs doing?')).toBeNull();
+  });
+});

package/src/components/index.ts

@@ -32,3 +32,20 @@ export type {
 export * from './pages/LibraryPage';
 export * from './pages/AskPage';
 export * from './pages/TrackerPage';
+
+// The planning toolset (bd startsim-8l6ef): focuses, and the items filed under
+// them. `work-items` carries the pieces the tracker and the planner SHARE — the
+// row, the honesty banner, the overdue/changed predicates — so two views over
+// one list cannot drift into disagreeing about what they mean.
+export * from './pages/PlanningPage';
+export {
+  PRIORITY_LABELS,
+  UnfilteredNotice,
+  WORK_ITEM_DEFAULTS,
+  WorkItemRow,
+  changedSince,
+  compareForScreen,
+  isOverdue,
+  priorityLabel,
+} from './pages/work-items';
+export type { WorkItemSlot } from './pages/work-items';

package/src/components/pages/LibraryPage.tsx

@@ -85,6 +85,29 @@ function readFailureMessage(err: unknown): string {
   return (err as { message?: string })?.message || 'Could not load the library.';
 }
 
+/**
+ * Why the record the screen was asked to open is not on the screen
+ * (bd startsim-2lt8y).
+ *
+ * FOUR ANSWERS, NOT ONE, and the branch is the point: "sign in again", "you may
+ * not see this", "that record is not here" and "something went wrong" send the
+ * reader to four different places, and only one of them is true at a time.
+ * Calling an expired session a missing record is a different lie from the one
+ * this bead is fixing, not a smaller version of it.
+ *
+ * The id is NAMED because it came out of the address bar. A citation or a
+ * bookmark that no longer resolves is worth being able to quote back to
+ * somebody, and "a record" is not quotable.
+ */
+function openFailureMessage(err: unknown, id: string): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 404) {
+    return `That record could not be found in this workspace (${id}). It may have been removed, or it may not be one you can see.`;
+  }
+  if (status === 401 || status === 403) return readFailureMessage(err);
+  return (err as { message?: string })?.message || `That record could not be opened (${id}).`;
+}
+
 function formatDate(value: string | null | undefined): string {
   if (!value) return 'No date';
   const at = Date.parse(value);
@@ -160,6 +183,13 @@ export function LibraryPage({
   const [parties, setParties] = React.useState<Party[]>([]);
   const [selectedId, setSelectedId] = React.useState<string | null>(initialDocumentId ?? null);
   const [selected, setSelected] = React.useState<SourceDocument | null>(null);
+  /**
+   * Why the open record is not open. Held separately from `loadError`, which is
+   * about the LIST: a Library that loaded fine and a citation that no longer
+   * resolves are different facts, and blanking the list for the second one would
+   * be a worse answer than the silence this replaces.
+   */
+  const [selectError, setSelectError] = React.useState('');
   const [loading, setLoading] = React.useState(true);
   const [loadError, setLoadError] = React.useState('');
   /**
@@ -216,18 +246,22 @@ export function LibraryPage({
   }, [api, filters, scope]);
 
   React.useEffect(() => {
-    if (!selectedId) { setSelected(null); return; }
+    if (!selectedId) { setSelected(null); setSelectError(''); return; }
     let live = true;
     void (async () => {
       // Prefer the row already on screen; fall back to a fetch so a citation
       // deep-link opens a record that is not on the current page.
       const onPage = documents.find((document) => document.id === selectedId);
-      if (onPage) { setSelected(onPage); return; }
+      if (onPage) { setSelected(onPage); setSelectError(''); return; }
       try {
         const fetched = await api.getDocument(selectedId);
-        if (live) setSelected(fetched);
-      } catch {
-        if (live) setSelected(null);
+        if (live) { setSelected(fetched); setSelectError(''); }
+      } catch (err) {
+        // THE REPORTED BUG (bd startsim-4s4um). This was `setSelected(null)` and
+        // nothing else, so `?doc=<id>` in the address bar produced a Library
+        // with no record and no explanation — the one outcome a reader cannot
+        // act on, and indistinguishable from a page that simply ignored them.
+        if (live) { setSelected(null); setSelectError(openFailureMessage(err, selectedId)); }
       }
     })();
     return () => { live = false; };
@@ -235,6 +269,7 @@ export function LibraryPage({
 
   const select = React.useCallback((id: string | null) => {
     setSelectedId(id);
+    if (!id) setSelectError('');
     onSelectDocument?.(id);
   }, [onSelectDocument]);
 
@@ -459,6 +494,16 @@ export function LibraryPage({
           onFilterByParty={(partyId) => update({ partyId })}
         />
       ) : null}
+
+      {/* Asked for, and not shown — said out loud rather than left blank. */}
+      {!selected && selectError ? (
+        <section className={cn.card} aria-label="Record">
+          <div className="flex items-start justify-between gap-4">
+            <p className={cn.warning} role="alert">{selectError}</p>
+            <button type="button" className={cn.button} onClick={() => select(null)}>Close</button>
+          </div>
+        </section>
+      ) : null}
     </div>
   );
 }