@kernhq/module-inventory 0.2.0 → 0.3.0

package/src/client/errors.ts

@@ -0,0 +1,201 @@
+/**
+ * Turning a refusal from the server into a sentence in the reader's own language.
+ *
+ * **Every actionable failure this module could produce reached the user in English, in all five
+ * locales.** Eight call sites were written as `toast.error(error.message || t('common.error'))`,
+ * and `error.message` is prose the *server* wrote: "Somebody changed who is holding this a moment
+ * before you did. Reload to see where it is now." That is the most useful sentence in the module
+ * and a Persian reader was shown it in English, at exactly the moment they needed to understand it.
+ * The comments at those call sites even said so — that the server's message was "the actionable
+ * one" — which was true, and was an argument for translating it rather than for printing it.
+ *
+ * The thing a client can translate is the **reason**, not the message. `KernError.conflict(message,
+ * reason)` has carried one since it was written, and `kernErrorToORPC` puts it in `data.reason`
+ * precisely so a client can branch on it: `inventory.custody.already_held` is a stable token that
+ * ships with the contract, where the sentence is prose that changes when somebody rewords it. So:
+ *
+ *   1. a `reason` this module knows → its own translated sentence;
+ *   2. otherwise the error **code** → the sentence that class of failure deserves;
+ *   3. otherwise a generic failure, and the server's own words underneath it.
+ *
+ * Step three is not a shrug. Dropping the server's message entirely would hide the one clue
+ * somebody could act on when the reason is one this build has never heard of — a newer server, an
+ * error from core rather than from here. It is shown as *detail*, under a sentence that at least
+ * names what failed, rather than as the whole of what the interface has to say.
+ *
+ * Pure and string-free: this file decides *which* key, `i18n.ts` holds the words, and a `.svelte`
+ * file cannot be unit-tested. `errorMessage()` at the bottom is the one function the screens call.
+ */
+
+/** What oRPC hands a screen. `code` is the contract's `ErrorCode`; `data` is what the server put in it. */
+export interface ServerError {
+  code?: unknown
+  message?: unknown
+  data?: unknown
+  status?: unknown
+}
+
+/**
+ * The reason token, out of wherever this particular transport put it.
+ *
+ * `data.reason` is the real one — that is what `kernErrorToORPC` folds it into. `reason` on the
+ * error itself is read too, because that is where a `KernError` thrown in-process carries it, and
+ * the mock in this package is neither: a demo that could not reproduce a translated conflict would
+ * be a demo that hides the branch this file exists for.
+ */
+export function reasonOf(err: unknown): string | null {
+  if (!err || typeof err !== 'object') return null
+  const e = err as ServerError & { reason?: unknown }
+  const data = e.data as { reason?: unknown } | undefined
+  const found = (data && typeof data === 'object' ? data.reason : undefined) ?? e.reason
+  return typeof found === 'string' && found ? found : null
+}
+
+/** The `ErrorCode` the server refused with, if this is one of its errors at all. */
+export function codeOf(err: unknown): string | null {
+  if (!err || typeof err !== 'object') return null
+  const { code } = err as ServerError
+  return typeof code === 'string' && code ? code : null
+}
+
+/**
+ * Whether a `BAD_REQUEST` is oRPC saying the *input* was malformed, or a service refusing.
+ *
+ * **Both arrive as `BAD_REQUEST`, and only one of them is about the form.** oRPC throws
+ * `ORPCError('BAD_REQUEST', { message: 'Input validation failed', data: { issues } })` when a zod
+ * schema rejects the input — that one really is "check what you entered". The ones this module's
+ * own services throw are not:
+ *
+ *   - "That person is not a member of this workspace, so nothing can be handed to them."
+ *   - "That file has not finished uploading yet."
+ *   - "That file is not one this workspace can attach."
+ *   - "That page marker is not one this list issued"
+ *   - "That category is not one this workspace has."
+ *   - "A repair cannot be sent in the future."
+ *
+ * Every field on those forms is fine. Sending somebody to re-read them is worse than saying
+ * nothing, because it is a confident wrong instruction: nobody finds the mistake, because there
+ * isn't one. `issues` is the one structural difference between the two, so it is what decides.
+ *
+ * This is a stopgap, and the report that came with it says so. The right fix is a **stable reason
+ * token** on each of those four — `KernError.badRequest` takes `details` where `conflict` takes a
+ * `reason`, so today they carry nothing a client can branch on and the server's English prose is
+ * the only clue that survives. Once they carry one, they belong in `REASON_KEYS` with a sentence
+ * each in all five languages, and this branch goes back to being about validation alone.
+ */
+export function isInputValidation(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false
+  const data = (err as ServerError).data as { issues?: unknown } | undefined
+  return Boolean(data && typeof data === 'object' && Array.isArray(data.issues))
+}
+
+/** Whatever the server said, for the detail line under a failure nothing here recognises. */
+export function messageOf(err: unknown): string | null {
+  if (!err) return null
+  if (typeof err === 'string') return err.trim() || null
+  if (typeof err !== 'object') return null
+  const { message } = err as ServerError
+  return typeof message === 'string' && message.trim() ? message.trim() : null
+}
+
+/**
+ * Every reason this module's server actually throws, and the sentence each one earns.
+ *
+ * Not "every reason imaginable": each key here is one this package's own services produce, and
+ * `errors.test.ts` reads them out of `src/server` to hold the two lists together. A sentence for a
+ * refusal that cannot happen is dead weight nobody will ever notice is wrong; a refusal with no
+ * sentence is English on somebody's screen, which is the defect this file was written for.
+ *
+ * The wording is what the reader can *do*, in the same voice as the rest of the module. A lost race
+ * says to look again; a conflict of state says which handover to use instead.
+ */
+const REASON_KEYS: Record<string, string> = {
+  'inventory.custody.conflict': 'error_custody_conflict',
+  'inventory.custody.archived': 'error_custody_archived',
+  'inventory.custody.already_held': 'error_custody_already_held',
+  'inventory.custody.not_held': 'error_custody_not_held',
+  'inventory.asset.still_held': 'error_asset_still_held',
+  'inventory.asset.under_repair': 'error_asset_under_repair',
+  'inventory.repair.already_open': 'error_repair_already_open',
+  'inventory.repair.archived': 'error_repair_archived',
+  'inventory.repair.already_complete': 'error_repair_already_complete',
+  'inventory.repair.returned_before_sent': 'error_repair_returned_before_sent',
+  'inventory.category.name_taken': 'error_category_name_taken',
+}
+
+export const reasonKeys = (): readonly string[] => Object.keys(REASON_KEYS)
+
+/**
+ * The sentence a whole class of failure earns, when no reason narrows it further.
+ *
+ * `NOT_FOUND` and `MODULE_DISABLED` are the two worth spelling out. A 404 here almost always means
+ * somebody else archived or removed the row while this screen was open, so "it is no longer there —
+ * reload" is both true and the next step. `MODULE_DISABLED` is what a workspace gets when Inventory
+ * is switched off underneath it, and "Forbidden" would be the wrong word for it entirely.
+ *
+ * A **disabled capability answers 404, not 403** — that is the module contract — so a capability
+ * switched off mid-session lands on `NOT_FOUND` here, which is the same "it is not there any more,
+ * look again" sentence, and correctly so.
+ */
+const CODE_KEYS: Record<string, string> = {
+  NOT_FOUND: 'error_not_found',
+  FORBIDDEN: 'error_forbidden',
+  MODULE_DISABLED: 'error_module_disabled',
+  CONFLICT: 'error_conflict',
+  // Reached only when the request really did fail validation — `errorLine` peels off the refusals
+  // first. `VALIDATION` is here because the code itself is the claim; `BAD_REQUEST` is not.
+  BAD_REQUEST: 'error_bad_request',
+  VALIDATION: 'error_bad_request',
+  UNAUTHORIZED: 'error_unauthorized',
+  RATE_LIMITED: 'error_rate_limited',
+  UNAVAILABLE: 'error_unavailable',
+}
+
+/**
+ * Which sentence to show, and whether the server's own words go under it.
+ *
+ * `detail` is filled only for the fallback: when this module named the failure itself, repeating
+ * the server's English beneath its own Persian sentence would undo the translation.
+ */
+export interface ErrorLine {
+  /** A key for `t()`, always one this module's catalogue has. */
+  key: string
+  /** The server's own sentence, for a failure nothing here recognised. Null otherwise. */
+  detail: string | null
+}
+
+export function errorLine(err: unknown): ErrorLine {
+  const reason = reasonOf(err)
+  const byReason = reason ? REASON_KEYS[reason] : undefined
+  if (byReason) return { key: byReason, detail: null }
+
+  const code = codeOf(err)
+
+  // A `BAD_REQUEST` with no validation issues on it is a service refusing something, not a schema
+  // rejecting a field — so it gets a sentence that does not send anybody back to a form that is
+  // fine, and the server's own explanation as the detail. That prose is English until those four
+  // refusals carry a reason token; an English clue under a translated sentence is worse than a
+  // translated one and much better than a confident wrong instruction.
+  if (code === 'BAD_REQUEST' && !isInputValidation(err))
+    return { key: 'error_refused', detail: messageOf(err) }
+
+  const byCode = code ? CODE_KEYS[code] : undefined
+  if (byCode) return { key: byCode, detail: null }
+
+  // Nothing recognised it — a newer server, a failure from core, or the network. The generic
+  // sentence names what happened and the server's words are kept as the only actionable clue left.
+  return { key: 'error_unknown', detail: messageOf(err) }
+}
+
+/**
+ * The one call a screen makes: `toast.error(errorMessage(error, t))`.
+ *
+ * `t` is passed in rather than imported so this file goes on importing nothing — `i18n.ts` reaches
+ * `@kernhq/ui`, and that entry point drags a Svelte compiler into whatever imports it, which is
+ * what makes a helper untestable.
+ */
+export function errorMessage(err: unknown, translate: (key: string) => string): string {
+  const line = errorLine(err)
+  const sentence = translate(line.key)
+  return line.detail ? `${sentence} — ${line.detail}` : sentence
+}

package/src/client/links.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { ASSET_PARAM, assetHref, INVENTORY_PATH, inventoryHref } from './links.js'
+
+/**
+ * The link a dashboard card follows, and the parameter the page reads.
+ *
+ * Both cards showed rows and did nothing with them — `kern-widget` §3, a table of contents rather
+ * than a card. A row now opens the asset's panel, which is a URL, which means three things have to
+ * agree: the route `module.ts` declares, the parameter `AssetsPage` reads, and the href built here.
+ * They are one constant each now, and this holds them to it: a link that is one character off does
+ * not fail, it silently lands on the list with nothing open, which looks like the panel is broken.
+ */
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+describe('assetHref', () => {
+  it('scopes the link to the workspace, because the shell mounts every module under a slug', () => {
+    // Without the slug a card on one workspace's dashboard links into another's, or into nothing.
+    expect(inventoryHref('acme')).toBe('/acme/inventory')
+    expect(assetHref('acme', '0192-abc')).toBe('/acme/inventory?asset=0192-abc')
+  })
+
+  it('produces a URL whose parameter is the one the page reads back', () => {
+    const url = new URL(assetHref('acme', '0192-abc'), 'https://kern.example.com')
+    expect(url.pathname).toBe('/acme/inventory')
+    expect(url.searchParams.get(ASSET_PARAM)).toBe('0192-abc')
+  })
+
+  it('encodes the id rather than trusting it to be a uuid for ever', () => {
+    const href = assetHref('acme', 'a&b=c')
+    expect(href).toContain('asset=a%26b%3Dc')
+    expect(new URL(href, 'https://x.test').searchParams.get(ASSET_PARAM)).toBe('a&b=c')
+  })
+})
+
+describe('the route this links to is the route the module declares', () => {
+  /**
+   * `module.ts` cannot be imported here — it reaches `@kernhq/ui`, whose entry point pulls in Svelte
+   * components this package's test setup cannot transform. So the declaration is read as text,
+   * which is enough: what would break is a path renamed in one file and not the other.
+   */
+  it('matches the path in `module.ts`', () => {
+    const source = readFileSync(join(HERE, 'module.ts'), 'utf8')
+    expect(source).toContain(`path: '${INVENTORY_PATH}'`)
+  })
+
+  it('is the parameter `AssetsPage` opens its panel from', () => {
+    // The page imports `ASSET_PARAM` rather than repeating the literal, so this checks the import
+    // is actually what it reads — a re-introduced `params.get('asset')` would pass by accident and
+    // then drift the first time the name changed.
+    const page = readFileSync(join(HERE, 'pages', 'AssetsPage.svelte'), 'utf8')
+    expect(page).toContain('params.get(ASSET_PARAM)')
+    expect(page).toContain("from '../links.js'")
+  })
+
+  it('is what both dashboard cards send somebody to', () => {
+    // The defect being guarded: a widget row that is inert. Each card builds its href from this
+    // module, so neither can go back to being a list nobody can act on without this failing.
+    for (const widget of ['OverviewWidget.svelte', 'RepairsWidget.svelte']) {
+      const source = readFileSync(join(HERE, 'widgets', widget), 'utf8')
+      expect({ widget, links: source.includes('assetHref(workspaceSlug') }).toEqual({
+        widget,
+        links: true,
+      })
+      // An anchor, not a click handler: that is what makes the keyboard route the same route.
+      expect({ widget, anchor: /<a\s+class="row"\s+href=/.test(source) }).toEqual({
+        widget,
+        anchor: true,
+      })
+    }
+  })
+})

package/src/client/links.ts

@@ -0,0 +1,44 @@
+/**
+ * Where this module's screens live, as URLs.
+ *
+ * Two things need to agree and were three files apart: `module.ts` declares the route, `AssetsPage`
+ * reads `?asset=<id>` to decide which panel is open, and a dashboard card has to be able to send
+ * somebody to exactly that. A widget that only *shows* rows is a table of contents — `kern-widget`
+ * §3 — and both of this module's cards were exactly that, with no way to act on a row at all.
+ *
+ * A pure module rather than a constant inside a component, for the reason `custody.ts` and
+ * `price.ts` are: `module.ts` imports `@kernhq/ui`, so anything that reads its route declaration
+ * drags a Svelte compiler behind it, and "does this href open that panel" is a fact with a right
+ * answer.
+ */
+
+/** The module's own route, as declared in `module.ts`. The workspace slug goes in front of it. */
+export const INVENTORY_PATH = '/inventory'
+
+/** The parameter `AssetsPage` reads to decide which asset's panel is open. */
+export const ASSET_PARAM = 'asset'
+
+/**
+ * The list, scoped to a workspace.
+ *
+ * The shell mounts every module route under `/<workspaceSlug>`, so a link built without the slug
+ * lands on the wrong workspace — or on nothing, which is what a widget on a second workspace's
+ * dashboard would have done.
+ */
+export function inventoryHref(workspaceSlug: string): string {
+  return `/${workspaceSlug}${INVENTORY_PATH}`
+}
+
+/**
+ * One asset, open in its panel over the list.
+ *
+ * Deliberately the list URL with a parameter rather than a page of its own: that is the URL the
+ * page already owns, so following it from a dashboard card leaves somebody in the same place they
+ * would have reached by clicking the row — with the list behind the panel, and Back closing it.
+ *
+ * The id is encoded even though it is always a uuid. A raw value in a query string is how a link
+ * builder eventually ships an injection, and `encodeURIComponent` costs nothing on a uuid.
+ */
+export function assetHref(workspaceSlug: string, assetId: string): string {
+  return `${inventoryHref(workspaceSlug)}?${ASSET_PARAM}=${encodeURIComponent(assetId)}`
+}

package/src/client/members.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { directory, directoryStatus, displayName, type NameWords, nameOf, resolveName } from './members.js'
+import { en } from './messages.js'
+
+/**
+ * What a stored uuid reads as, and — the part that was wrong — *when* it is entitled to say so.
+ *
+ * `nameOf` resolved every id it could not find to "a former member". That is a claim about a
+ * person, and it was made in two states where nothing was known about anybody: while the members
+ * request was still in flight, and after it had failed. So an asset panel opened on a laptop that
+ * had changed hands twice read
+ *
+ *     A former member handed it to A former member
+ *     A former member took it back from A former member
+ *
+ * for the first moments of every load — and permanently whenever core was unreachable, which is
+ * exactly when somebody is most likely to be staring at the screen trying to work out what happened.
+ *
+ * Neither state can be told from an empty map, which is why the fix is on the `Directory` rather
+ * than at the call sites: the request's own state has to travel with the rows.
+ */
+const member = (userId: string, name: string | null, email: string) => ({
+  userId,
+  user: { id: userId, name, email },
+})
+
+const PEOPLE = [
+  member('a', 'Ada Lovelace', 'ada@example.com'),
+  member('b', null, 'bruno@example.com'),
+  member('c', '   ', 'carla@example.com'),
+]
+
+const words: NameWords = {
+  loading: '…',
+  unknown: 'Someone',
+  former: 'A former member',
+  system: 'The system',
+}
+
+describe('displayName', () => {
+  it('falls back to the email for somebody who has never signed in', () => {
+    const dir = directory(PEOPLE)
+    expect(displayName(dir.byId.get('b'))).toBe('bruno@example.com')
+  })
+
+  it('treats a blank name as absent, so no row has an empty person column', () => {
+    const dir = directory(PEOPLE)
+    expect(displayName(dir.byId.get('c'))).toBe('carla@example.com')
+  })
+})
+
+describe('directoryStatus', () => {
+  it('reads a query that has not answered as loading, not as an empty workspace', () => {
+    expect(directoryStatus({ isSuccess: false, isError: false })).toBe('loading')
+  })
+
+  it('reads a failure as its own state rather than as an absence', () => {
+    expect(directoryStatus({ isSuccess: false, isError: true })).toBe('error')
+  })
+
+  it('is ready only once the data is actually in hand', () => {
+    // `isSuccess`, never `!isPending`: a query with `enabled: false` reports `isPending` for ever,
+    // and the assets page disables this one until something is filtered by custodian.
+    expect(directoryStatus({ isSuccess: true, isError: false })).toBe('ready')
+  })
+})
+
+describe('resolveName tells the three unknowns apart', () => {
+  const ready = directory(PEOPLE, 'ready')
+  const loading = directory([], 'loading')
+  const failed = directory([], 'error')
+  const gone = '01920000-0000-7000-8000-00000000dead'
+
+  it('names somebody the workspace has', () => {
+    expect(resolveName('a', ready)).toEqual({ kind: 'person', name: 'Ada Lovelace' })
+  })
+
+  it('says nothing at all while the member list is still in flight', () => {
+    // The regression. This answered `former` — "A former member handed it to A former member" —
+    // for the first moments of every panel, about people who had not gone anywhere.
+    expect(resolveName('a', loading)).toEqual({ kind: 'loading', name: null })
+    expect(resolveName(gone, loading)).toEqual({ kind: 'loading', name: null })
+  })
+
+  it('says the lookup failed rather than that the person left', () => {
+    // The same claim, made permanent: with core unreachable, every name on the screen used to
+    // report that its owner had been removed from the workspace.
+    expect(resolveName('a', failed)).toEqual({ kind: 'unknown', name: null })
+  })
+
+  it('says somebody has left only once the list is in hand and does not contain them', () => {
+    expect(resolveName(gone, ready)).toEqual({ kind: 'former', name: null })
+  })
+
+  it('has no name for a row nothing signed, in every state', () => {
+    for (const dir of [ready, loading, failed])
+      expect(resolveName(null, dir)).toEqual({ kind: 'system', name: null })
+  })
+
+  it('carries a name only for somebody actually found, which is what the avatar reads', () => {
+    // An `Avatar` seeded with "…" would draw the initials of an ellipsis in a coloured square.
+    for (const resolved of [resolveName('a', loading), resolveName(gone, ready), resolveName(null, ready)])
+      if (resolved.kind !== 'person') expect(resolved.name).toBe(null)
+  })
+})
+
+describe('nameOf', () => {
+  const ready = directory(PEOPLE, 'ready')
+
+  it('gives each of the four unknowns its own word', () => {
+    expect(nameOf('a', ready, words)).toBe('Ada Lovelace')
+    expect(nameOf('a', directory([], 'loading'), words)).toBe('…')
+    expect(nameOf('a', directory([], 'error'), words)).toBe('Someone')
+    expect(nameOf('gone', ready, words)).toBe('A former member')
+    expect(nameOf(null, ready, words)).toBe('The system')
+  })
+
+  it('never renders a raw uuid', () => {
+    const uuid = '01920000-0000-7000-8000-00000000dead'
+    for (const dir of [ready, directory([], 'loading'), directory([], 'error')])
+      expect(nameOf(uuid, dir, words)).not.toContain(uuid)
+  })
+
+  /**
+   * The words are translated, and a missing one would render the key — `inventory.member_loading`
+   * — in the middle of a timeline entry, in every locale at once.
+   */
+  it('has a catalogue entry for every word it asks a screen for', () => {
+    for (const key of ['member_loading', 'member_unknown', 'member_former', 'member_system'])
+      expect({ key, has: `inventory.${key}` in en }).toEqual({ key, has: true })
+  })
+})

package/src/client/members.ts

@@ -0,0 +1,116 @@
+import type { CoreMember } from './core-api.js'
+
+/**
+ * Turning a stored user id into a name a person recognises.
+ *
+ * Custody rows and history rows both carry plain uuids — a module keeps cross-schema ids plain, and
+ * a name copied into this module's tables would be a name that goes stale the day somebody marries.
+ * So every screen that shows *who* resolves the id here, against the members core says the workspace
+ * has right now.
+ *
+ * **The list is a request, and a request has three answers, not one.** This file resolved an
+ * unknown id straight to "a former member" without ever asking whether the list had arrived — so
+ * for the first moments of every panel, before the members request came back, an entire timeline
+ * read "A former member handed it to A former member", and it stayed that way for ever if the
+ * request failed. The claim was false in both cases: nobody had left. `status` is what separates
+ * *we do not know yet*, *we could not find out* and *this person really is gone*, and the three are
+ * rendered as three different things.
+ *
+ * Pure, and here rather than inside a component, for the reason `price.ts` and `timeline.ts` are:
+ * a `.svelte` file drags a compiler behind it and cannot be unit-tested, and "what does this id
+ * read as" is a fact with a right answer.
+ */
+
+/** Where the members request has got to. `ready` is the only state whose absences mean anything. */
+export type DirectoryStatus = 'loading' | 'error' | 'ready'
+
+export interface Directory {
+  /** Everybody the workspace has, by user id. Empty until `status` is `ready`. */
+  byId: ReadonlyMap<string, CoreMember>
+  /** The same ids as a set, which is what `actorKind` asks about. */
+  ids: ReadonlySet<string>
+  /** Whether this directory is in a position to say that somebody is missing from it. */
+  status: DirectoryStatus
+}
+
+export function directory(members: readonly CoreMember[], status: DirectoryStatus = 'ready'): Directory {
+  const byId = new Map<string, CoreMember>()
+  for (const member of members) byId.set(member.userId, member)
+  return { byId, ids: new Set(byId.keys()), status }
+}
+
+/**
+ * A TanStack query's flags as the one word this file needs.
+ *
+ * Here rather than inlined into each screen because the mapping has a trap in it: a query with
+ * `enabled: false` reports `isPending` for ever, so "not pending" is not the same question as
+ * "arrived". `isSuccess` is the only flag that means the data is in hand.
+ */
+export function directoryStatus(query: { isSuccess: boolean; isError: boolean }): DirectoryStatus {
+  if (query.isError) return 'error'
+  return query.isSuccess ? 'ready' : 'loading'
+}
+
+/**
+ * What to call somebody.
+ *
+ * `name` is nullable in core — an invited person who has never signed in has an email and nothing
+ * else — so the email is the fallback rather than an empty label. A blank name is treated as absent
+ * for the same reason: a row whose person column is empty reads as a bug in the register.
+ */
+export function displayName(member: CoreMember | undefined): string | null {
+  if (!member) return null
+  const name = member.user.name?.trim()
+  return name || member.user.email
+}
+
+/**
+ * The five answers to "who is this id", before any of them is turned into words.
+ *
+ * `person` is the only one carrying a name. The other four each say something different and only
+ * one of them is a claim about the *person*:
+ *
+ * - `loading` — the workspace's members have not arrived. Nothing is known yet, and saying anything
+ *   about who this is would be inventing it.
+ * - `unknown` — the members request failed. Somebody did this; which somebody cannot be found out
+ *   right now, and that is a fact about the request rather than about them.
+ * - `former` — the list is in hand and this id is not in it. *Now* "a former member" is true.
+ * - `system` — there is no id at all: a nightly sweep, an import, an offboarding hook.
+ */
+export type NameKind = 'person' | 'loading' | 'unknown' | 'former' | 'system'
+
+export interface ResolvedName {
+  kind: NameKind
+  /** The name, and only for `person`. Everything else has no name to give. */
+  name: string | null
+}
+
+export function resolveName(userId: string | null, dir: Directory): ResolvedName {
+  if (!userId) return { kind: 'system', name: null }
+  const name = displayName(dir.byId.get(userId))
+  if (name) return { kind: 'person', name }
+  if (dir.status === 'loading') return { kind: 'loading', name: null }
+  if (dir.status === 'error') return { kind: 'unknown', name: null }
+  return { kind: 'former', name: null }
+}
+
+/** The words a screen supplies for the four answers that have no name of their own. */
+export interface NameWords {
+  loading: string
+  unknown: string
+  former: string
+  system: string
+}
+
+/**
+ * The one place an unresolvable id is turned into words.
+ *
+ * The words are given by the caller because they are translated strings, and this file holds no
+ * strings — it decides *which* of the five answers applies and leaves the wording to the catalogue.
+ * Never the raw uuid: a sentence with a uuid in the middle of it is the interface admitting it does
+ * not know what it is talking about.
+ */
+export function nameOf(userId: string | null, dir: Directory, words: NameWords): string {
+  const resolved = resolveName(userId, dir)
+  return resolved.kind === 'person' ? (resolved.name as string) : words[resolved.kind]
+}