@devaccel-labs/app-comments-toolbar 1.0.0 → 1.3.0

package/src/runtime/clarity-model.ts

@@ -0,0 +1,634 @@
+/**
+ * The clarity check as the composer runs it (docs/adr/0002-clarity-check.md): what Send does before a new
+ * comment is posted, what the person is shown when a reader would still have to ask something, and what
+ * the comment says when it goes. Every decision is here; `./clarity-ui.tsx` draws it. DOM-free.
+ *
+ * The check is never the reason a comment is lost or late: no mode, mode `off`, a failed or slow request,
+ * or an answer this file cannot read all post the comment exactly as it would have gone without the check.
+ *
+ * The wire types and bounds mirror `packages/contract/src/clarity.ts` and `limits.ts`; the toolbar bundle
+ * does not import the contract package. `tests/clarity-model.spec.ts` holds the two in step.
+ *
+ * Native clients run the same decisions: `../native.ts` exports this file to `@devaccel-labs/app-comments-native`.
+ */
+import type { TicketDraft } from "./ticket-form-model";
+
+export type ClarityMode = "off" | "advise" | "require";
+
+export type ClarityGap = "expected" | "actual" | "steps" | "which" | "scope" | "done" | "other";
+
+/** Who would have to ask: the person making the change, or whoever checks it afterwards. */
+export type ClarityAudience = "developer" | "tester";
+
+export interface ClarityQuestion {
+  readonly id: string;
+  readonly gap: ClarityGap;
+  /** Absent on a report from before questions said who asks: read it as the developer's. */
+  readonly audience?: ClarityAudience;
+  /** The question, in one sentence. */
+  readonly ask: string;
+  /** Why a reader needs it, in a few words. */
+  readonly why: string;
+}
+
+export interface ClarityAnswer {
+  readonly questionId: string;
+  readonly ask: string;
+  readonly answer: string;
+}
+
+export interface ClarityAnswerCheck {
+  readonly questionId: string;
+  readonly status: "answered" | "partial" | "unrelated";
+  readonly note?: string;
+}
+
+/** The part of the service's report the composer reads. */
+export interface ClarityReport {
+  readonly verdict: "clear" | "needs_detail" | "unchecked";
+  readonly understood: string;
+  /** What the check took as given instead of asking. Absent when it took nothing, or predates the field. */
+  readonly assumed?: readonly string[];
+  readonly questions: readonly ClarityQuestion[];
+  readonly answers: readonly ClarityAnswerCheck[];
+}
+
+/** The body of `POST /v1/clarity`. */
+export interface ClarityDraft {
+  readonly body: string;
+  readonly url: string;
+  readonly route: string;
+  readonly target: string;
+  readonly attachmentIds: readonly string[];
+  /** As a new comment is posted with them: the role, custom field values by id, a tester's ticket answers. */
+  readonly role?: string | null;
+  readonly fields?: Readonly<Record<string, string>>;
+  readonly ticket?: TicketDraft;
+  readonly asked?: readonly ClarityQuestion[];
+  readonly answers?: readonly ClarityAnswer[];
+}
+
+export const CLARITY_MAX_QUESTIONS = 3;
+export const CLARITY_MAX_ASSUMED = 3;
+export const CLARITY_MAX_ROUNDS = 2;
+export const CLARITY_ANSWER_MAX_LENGTH = 2000;
+export const COMMENT_MESSAGE_MAX_LENGTH = 4000;
+/** How long Send waits for the check. The service gives its model eight seconds; past nine the comment goes. */
+export const CLARITY_WAIT_MS = 9_000;
+
+/** Every word the check puts on screen or into a comment. About the reader, never about the writer. */
+export const CLARITY_WORDS = {
+  /** The panel's name, for a screen reader. */
+  region: "More detail",
+  understood: "What a reader takes from this:",
+  /** Over what the check took as given, and the line under it. The console's inbox uses the same words. */
+  assumed: "Taken as given",
+  assumedNote: "Not asked about. Shown so a wrong one can be put right.",
+  /** The lead when every question is a developer's; `whoWouldAsk` names the reader otherwise. */
+  lead: "A developer would still have to ask:",
+  placeholder: "Add your answer…",
+  hint: "Add a little more so nobody has to guess.",
+  /** After the second look: nothing holds the comment any more. */
+  free: "You can send now. Add more if it helps.",
+  /** `require`, first look, Send pressed with nothing added. */
+  stay: "Answer a question or add to the comment, then send.",
+  sendAsIs: "Send as is",
+  working: "One moment…",
+  /** Beside a question whose answer the service said falls short without saying how. */
+  more: "A reader would still need a little more here.",
+  full: "The comment has no room for more.",
+  /** The line the answers sit under in the posted comment. */
+  detail: "More detail:",
+  question: "Q. ",
+  answer: "A. ",
+} as const;
+
+const GAPS: readonly ClarityGap[] = [
+  "expected",
+  "actual",
+  "steps",
+  "which",
+  "scope",
+  "done",
+  "other",
+];
+
+type UnknownFields = { readonly [field: string]: unknown };
+
+function isRecord(value: unknown): value is UnknownFields {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function oneLine(value: unknown): string {
+  return typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+}
+
+function isGap(value: unknown): value is ClarityGap {
+  return typeof value === "string" && (GAPS as readonly string[]).includes(value);
+}
+
+/**
+ * The environment's mode as `GET /v1/threads` carries it in `clarity`. Null when the field is missing or is
+ * not a mode: a service that predates the check, which is never asked.
+ */
+export function readClarityMode(value: unknown): ClarityMode | null {
+  return value === "off" || value === "advise" || value === "require" ? value : null;
+}
+
+/** Whether a new comment is checked before it is posted. */
+export function clarityChecks(mode: ClarityMode | null): mode is "advise" | "require" {
+  return mode === "advise" || mode === "require";
+}
+
+function readQuestions(raw: unknown): ClarityQuestion[] {
+  if (!Array.isArray(raw)) return [];
+  const questions: ClarityQuestion[] = [];
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    const id = oneLine(item["id"]);
+    const ask = oneLine(item["ask"]);
+    if (!id || !ask || questions.some((question) => question.id === id)) continue;
+    const audience = item["audience"];
+    questions.push({
+      id,
+      gap: isGap(item["gap"]) ? item["gap"] : "other",
+      ...(audience === "developer" || audience === "tester" ? { audience } : {}),
+      ask,
+      why: oneLine(item["why"]),
+    });
+    if (questions.length === CLARITY_MAX_QUESTIONS) break;
+  }
+  return questions;
+}
+
+/** What was taken as given, as `{ assumed }`, or nothing when it is absent, empty or unreadable. */
+function readAssumed(raw: unknown): { readonly assumed?: readonly string[] } {
+  if (!Array.isArray(raw)) return {};
+  const assumed: string[] = [];
+  for (const item of raw) {
+    const sentence = oneLine(item);
+    if (!sentence || assumed.includes(sentence)) continue;
+    assumed.push(sentence);
+    if (assumed.length === CLARITY_MAX_ASSUMED) break;
+  }
+  return assumed.length ? { assumed } : {};
+}
+
+function readChecks(raw: unknown): ClarityAnswerCheck[] {
+  if (!Array.isArray(raw)) return [];
+  const checks: ClarityAnswerCheck[] = [];
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    const questionId = oneLine(item["questionId"]);
+    const status = item["status"];
+    if (!questionId || checks.some((check) => check.questionId === questionId)) continue;
+    if (status !== "answered" && status !== "partial" && status !== "unrelated") continue;
+    const note = oneLine(item["note"]);
+    checks.push({ questionId, status, ...(note ? { note } : {}) });
+  }
+  return checks;
+}
+
+/**
+ * What `POST /v1/clarity` answered, or null when it is not an answer this build can act on. Null posts the
+ * comment: an unreadable answer is the check failing, and the check fails open.
+ */
+export function readClarityResponse(
+  payload: unknown,
+): { readonly mode: ClarityMode; readonly report: ClarityReport } | null {
+  if (!isRecord(payload) || !isRecord(payload["report"])) return null;
+  const mode = readClarityMode(payload["mode"]);
+  const report = payload["report"];
+  const verdict = report["verdict"];
+  if (mode === null) return null;
+  if (verdict !== "clear" && verdict !== "needs_detail" && verdict !== "unchecked") return null;
+  return {
+    mode,
+    report: {
+      verdict,
+      understood: oneLine(report["understood"]),
+      ...readAssumed(report["assumed"]),
+      questions: readQuestions(report["questions"]),
+      answers: readChecks(report["answers"]),
+    },
+  };
+}
+
+/** How one check ended: with the service's answer, or without one. */
+export type ClarityOutcome =
+  | { readonly kind: "answered"; readonly mode: ClarityMode; readonly report: ClarityReport }
+  | { readonly kind: "failed" };
+
+/**
+ * Runs one check and never throws. A rejection (a 404 from a service without the route, any other status,
+ * the network), an answer that cannot be read, or no answer within `waitMs` are all `failed`. The wait is
+ * raced, not only aborted, so a request that ignores its signal still lets Send go on time.
+ */
+export async function askClarity(
+  run: (signal: AbortSignal) => Promise<unknown>,
+  waitMs: number = CLARITY_WAIT_MS,
+): Promise<ClarityOutcome> {
+  const abort = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<"late">((resolve) => {
+    timer = setTimeout(() => resolve("late"), waitMs);
+  });
+  try {
+    const payload = await Promise.race([run(abort.signal), late]);
+    if (payload === "late") {
+      abort.abort();
+      return { kind: "failed" };
+    }
+    const read = readClarityResponse(payload);
+    return read ? { kind: "answered", mode: read.mode, report: read.report } : { kind: "failed" };
+  } catch {
+    return { kind: "failed" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The draft at the moment Send was pressed. */
+export interface ClarityFacts {
+  readonly body: string;
+  /** The page the comment is filed against. */
+  readonly url: string;
+  readonly route: string;
+  /** What it is attached to, in words. */
+  readonly target: string;
+  /** Its uploaded files, by attachment id. */
+  readonly attachmentIds: readonly string[];
+  /**
+   * What it will be posted with besides its words (the role, custom fields and a tester's ticket answers),
+   * exactly as the post sends them, so the check does not ask what one of them already says.
+   */
+  readonly posted?: Pick<ClarityDraft, "role" | "fields" | "ticket">;
+  /**
+   * Its files by their key in the draft. A key outlives a reload (an attachment id does not: a resumed
+   * draft uploads its files again), so this is what says whether the files changed.
+   */
+  readonly fileKeys: readonly string[];
+}
+
+/**
+ * A draft the check is holding: a reader would still have to ask something. Kept with the draft in storage
+ * (`./draft-model.ts`), so a reload or a minimise brings the questions and the typed answers back.
+ */
+export interface ClarityHold {
+  readonly v: 1;
+  /** Looks the service has taken at this draft that left a question open. */
+  readonly round: 1 | 2;
+  /** The environment's mode when it last looked. */
+  readonly mode: "advise" | "require";
+  readonly understood: string;
+  /** What the last look took as given. Absent when it took nothing. */
+  readonly assumed?: readonly string[];
+  /** Every question asked of this draft, most important first. */
+  readonly questions: readonly ClarityQuestion[];
+  /** The ones still open, by id. */
+  readonly open: readonly string[];
+  /** What was typed under each question, by id. An answer that closed its question is still here. */
+  readonly answers: Readonly<Record<string, string>>;
+  /** What the last look said is still needed, by question id. */
+  readonly notes: Readonly<Record<string, string>>;
+  /** The draft as it was last looked at (`draftMark`). */
+  readonly checked: string;
+}
+
+/** The draft's own content: its words and its files. Answers are not part of it. */
+export function draftMark(facts: Pick<ClarityFacts, "body" | "fileKeys">): string {
+  return [facts.body.trim(), ...facts.fileKeys].join("\u0000");
+}
+
+/** The draft and its answers together: what a look that let the comment through was shown. */
+export function passMark(
+  facts: Pick<ClarityFacts, "body" | "fileKeys">,
+  hold: ClarityHold | null,
+): string {
+  const answers = hold ? givenAnswers(hold, hold.questions) : [];
+  return [draftMark(facts), ...answers.map((item) => `${item.questionId}=${item.answer}`)].join(
+    "\u0001",
+  );
+}
+
+/** The questions still open, in the order they were asked. */
+export function openQuestions(hold: ClarityHold): ClarityQuestion[] {
+  return hold.questions.filter((question) => hold.open.includes(question.id));
+}
+
+function givenAnswers(hold: ClarityHold, questions: readonly ClarityQuestion[]): ClarityAnswer[] {
+  const answers: ClarityAnswer[] = [];
+  for (const question of questions) {
+    const answer = (hold.answers[question.id] ?? "").trim();
+    if (answer) answers.push({ questionId: question.id, ask: question.ask, answer });
+  }
+  return answers;
+}
+
+/** `hold` with `text` typed under one of its questions. */
+export function withAnswer(hold: ClarityHold, questionId: string, text: string): ClarityHold {
+  if (!hold.questions.some((question) => question.id === questionId)) return hold;
+  return { ...hold, answers: { ...hold.answers, [questionId]: text } };
+}
+
+/**
+ * Whether the comment may be sent with questions still open. In `advise` always; in `require` only once the
+ * service has looked twice, so the first Send with open questions cannot be skipped and the second always can.
+ */
+export function canSendAsIs(hold: ClarityHold): boolean {
+  return hold.mode === "advise" || hold.round >= CLARITY_MAX_ROUNDS;
+}
+
+/** "send" is the composer's own Send; "as-is" is the panel's "Send as is". */
+export type ClaritySend = "send" | "as-is";
+
+export type ClarityStep =
+  /** Post now. */
+  | { readonly kind: "post" }
+  /** Ask the service first. */
+  | { readonly kind: "check"; readonly request: ClarityDraft }
+  /** `require`, first look, and nothing was added: the questions stay. */
+  | { readonly kind: "stay" };
+
+function requestFor(
+  facts: ClarityFacts,
+  asked: readonly ClarityQuestion[],
+  answers: readonly ClarityAnswer[],
+): ClarityDraft {
+  return {
+    body: facts.body,
+    url: facts.url,
+    route: facts.route,
+    target: facts.target,
+    attachmentIds: facts.attachmentIds,
+    ...facts.posted,
+    ...(asked.length ? { asked, answers } : {}),
+  };
+}
+
+/**
+ * What a press of Send does to a new comment.
+ *
+ * - No mode (a service without the check) or `off`: post, and nothing is asked.
+ * - A draft the service already let through, unchanged since: post (a failed post is retried without asking again).
+ * - Not looked at yet: ask.
+ * - Held, and skipping is allowed and was chosen, or the service has looked twice: post.
+ * - Held after the first look: answers go to be judged against their questions; with none, an edited draft is
+ *   looked at afresh; with nothing added, `advise` posts and `require` stays.
+ */
+export function clarityStep(input: {
+  readonly mode: ClarityMode | null;
+  readonly hold: ClarityHold | null;
+  readonly draft: ClarityFacts;
+  readonly send: ClaritySend;
+  /** `passMark` of the draft the service last let through, if it has. */
+  readonly passed?: string | null;
+}): ClarityStep {
+  const { mode, hold, draft } = input;
+  if (!clarityChecks(mode)) return { kind: "post" };
+  if (typeof input.passed === "string" && input.passed === passMark(draft, hold))
+    return { kind: "post" };
+  if (!hold) return { kind: "check", request: requestFor(draft, [], []) };
+  if (input.send === "as-is" && canSendAsIs(hold)) return { kind: "post" };
+  if (hold.round >= CLARITY_MAX_ROUNDS) return { kind: "post" };
+  const asked = openQuestions(hold);
+  const answers = givenAnswers(hold, asked);
+  if (answers.length > 0) return { kind: "check", request: requestFor(draft, asked, answers) };
+  if (draftMark(draft) !== hold.checked)
+    return { kind: "check", request: requestFor(draft, [], []) };
+  return hold.mode === "advise" ? { kind: "post" } : { kind: "stay" };
+}
+
+/**
+ * The draft's hold after a check, or null when the comment goes: the check failed, the mode is `off`, the
+ * verdict is `clear` or `unchecked`, or it left nothing to ask. A second look at answers opens nothing new:
+ * only questions that were already asked can stay open, whatever the service sends.
+ */
+export function clarityAfterCheck(
+  hold: ClarityHold | null,
+  draft: ClarityFacts,
+  request: ClarityDraft,
+  outcome: ClarityOutcome,
+): ClarityHold | null {
+  if (outcome.kind === "failed") return null;
+  const { mode, report } = outcome;
+  if (!clarityChecks(mode)) return null;
+  switch (report.verdict) {
+    case "clear":
+    case "unchecked":
+      return null;
+    case "needs_detail":
+      break;
+    default: {
+      const never: never = report.verdict;
+      return never;
+    }
+  }
+  const checked = draftMark(draft);
+  const judged = hold !== null && (request.asked?.length ?? 0) > 0;
+  if (!judged) {
+    if (report.questions.length === 0) return null;
+    return {
+      v: 1,
+      round: hold ? 2 : 1,
+      mode,
+      understood: report.understood,
+      ...readAssumed(report.assumed),
+      questions: report.questions,
+      open: report.questions.map((question) => question.id),
+      answers: {},
+      notes: {},
+      checked,
+    };
+  }
+  const still = new Set(report.questions.map((question) => question.id));
+  const open = hold.open.filter((id) => still.has(id));
+  if (open.length === 0) return null;
+  const notes: Record<string, string> = {};
+  for (const check of report.answers) {
+    if (check.status === "answered" || !open.includes(check.questionId)) continue;
+    notes[check.questionId] = check.note ?? CLARITY_WORDS.more;
+  }
+  return {
+    v: 1,
+    round: 2,
+    mode,
+    understood: report.understood || hold.understood,
+    ...readAssumed(report.assumed?.length ? report.assumed : hold.assumed),
+    questions: hold.questions,
+    open,
+    answers: hold.answers,
+    notes,
+    checked,
+  };
+}
+
+/** The lines a question adds to the comment before its answer. */
+function questionHead(ask: string): string {
+  return `\n${CLARITY_WORDS.question}${ask}\n${CLARITY_WORDS.answer}`;
+}
+
+/** The comment's own words and the blank line before the answers; empty for a comment that is only files. */
+function bodyLead(body: string): string {
+  return body.trim() ? `${body.trimEnd()}\n\n` : "";
+}
+
+/** An answer is shortened only when at least this much of it fits; a stub of one says nothing. */
+const CLIPPED_ANSWER_MIN = 20;
+
+function clip(text: string, length: number): string {
+  let kept = text.slice(0, length - 1);
+  // Never half of a surrogate pair.
+  const last = kept.charCodeAt(kept.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) kept = kept.slice(0, -1);
+  return `${kept.trimEnd()}…`;
+}
+
+/**
+ * The text the comment is posted with: its own words, then every answered question under "More detail:", as
+ * plain text (the same lines the service's `detailText` writes for an inbox). With no answers it is `body`,
+ * untouched.
+ *
+ * It never passes `COMMENT_MESSAGE_MAX_LENGTH`, and the comment's own words are never cut to make room: an
+ * answer that does not fit whole is shortened and ends in "…", and one with no room left (and any after it)
+ * is left out. A comment already at the limit is posted as it is, with no answers.
+ */
+export function clarityBody(body: string, hold: ClarityHold | null): string {
+  if (!hold) return body;
+  const answers = givenAnswers(hold, hold.questions);
+  if (answers.length === 0) return body;
+  const lead = `${bodyLead(body)}${CLARITY_WORDS.detail}`;
+  let room = COMMENT_MESSAGE_MAX_LENGTH - lead.length;
+  const parts: string[] = [];
+  for (const item of answers) {
+    const head = questionHead(item.ask);
+    const left = room - head.length;
+    if (left < 1) break;
+    if (item.answer.length <= left) {
+      parts.push(`${head}${item.answer}`);
+      room -= head.length + item.answer.length;
+      continue;
+    }
+    if (left < CLIPPED_ANSWER_MIN) break;
+    parts.push(`${head}${clip(item.answer, left)}`);
+    break;
+  }
+  return parts.length ? `${lead}${parts.join("")}` : body;
+}
+
+/**
+ * How long the answer under `questionId` may be, so that what is typed is what is posted: the smaller of the
+ * service's cap for one answer and what is left of the comment's length after its words and the other answers.
+ */
+export function answerRoom(body: string, hold: ClarityHold, questionId: string): number {
+  const question = hold.questions.find((item) => item.id === questionId);
+  if (!question) return 0;
+  let used =
+    bodyLead(body).length + CLARITY_WORDS.detail.length + questionHead(question.ask).length;
+  for (const other of hold.questions) {
+    if (other.id === questionId) continue;
+    const answer = (hold.answers[other.id] ?? "").trim();
+    if (answer) used += questionHead(other.ask).length + answer.length;
+  }
+  return Math.max(0, Math.min(CLARITY_ANSWER_MAX_LENGTH, COMMENT_MESSAGE_MAX_LENGTH - used));
+}
+
+/**
+ * What a screen reader is told when questions appear, change or stay. `who` is the reader the lead names
+ * (`whoWouldAsk`); the native package's panel does not pass it yet and keeps "A developer".
+ */
+export function clarityAnnouncement(
+  hold: ClarityHold | null,
+  stayed: boolean,
+  who = "A developer",
+): string {
+  if (!hold) return "";
+  const count = hold.open.length;
+  if (stayed) return CLARITY_WORDS.stay;
+  if (hold.round >= CLARITY_MAX_ROUNDS)
+    return `${count === 1 ? "1 question is" : `${count} questions are`} still open. ${CLARITY_WORDS.free}`;
+  return `${who} would still have to ask ${count === 1 ? "1 question" : `${count} questions`}. ${CLARITY_WORDS.hint}`;
+}
+
+const AUDIENCES: readonly ClarityAudience[] = ["developer", "tester"];
+
+/** Who would ask `question`. A question from before questions said so is the developer's. */
+export function questionAudience(question: ClarityQuestion): ClarityAudience {
+  return question.audience === "tester" ? "tester" : "developer";
+}
+
+/** The reader who would ask, as the subject of a sentence. The console's inbox uses the same words. */
+export function clarityReader(audience: ClarityAudience): string {
+  switch (audience) {
+    case "developer":
+      return "A developer";
+    case "tester":
+      return "Whoever tests the fix";
+    default: {
+      const never: never = audience;
+      return never;
+    }
+  }
+}
+
+/** `questions` by who would ask them, the developer's first, leaving out a reader who has none. */
+export function clarityGroups(
+  questions: readonly ClarityQuestion[],
+): Array<{ readonly audience: ClarityAudience; readonly questions: ClarityQuestion[] }> {
+  return AUDIENCES.map((audience) => ({
+    audience,
+    questions: questions.filter((question) => questionAudience(question) === audience),
+  })).filter((group) => group.questions.length > 0);
+}
+
+/**
+ * Who would ask the open questions, as the subject of "… would still have to ask": the one reader when they
+ * are all one reader's, "A reader" when a developer and whoever tests the fix both have some.
+ */
+export function whoWouldAsk(questions: readonly ClarityQuestion[]): string {
+  const [only, ...others] = clarityGroups(questions);
+  return only && others.length === 0 ? clarityReader(only.audience) : "A reader";
+}
+
+function readTexts(raw: unknown, ids: ReadonlySet<string>): Record<string, string> {
+  const texts: Record<string, string> = {};
+  if (!isRecord(raw)) return texts;
+  for (const [id, text] of Object.entries(raw)) {
+    if (ids.has(id) && typeof text === "string") texts[id] = text;
+  }
+  return texts;
+}
+
+/**
+ * `value` as a hold, or null when it is not one this build can show. Storage holds whatever an earlier build
+ * wrote; a hold that does not read whole is dropped, and the draft it came with is resumed without it.
+ */
+export function readClarityHold(value: unknown): ClarityHold | null {
+  if (!isRecord(value) || value["v"] !== 1) return null;
+  const round = value["round"];
+  const mode = value["mode"];
+  if (round !== 1 && round !== 2) return null;
+  if (mode !== "advise" && mode !== "require") return null;
+  if (typeof value["checked"] !== "string") return null;
+  const questions = readQuestions(value["questions"]);
+  const ids = new Set(questions.map((question) => question.id));
+  const open = Array.isArray(value["open"])
+    ? value["open"].filter(
+        (id, index, all): id is string =>
+          typeof id === "string" && ids.has(id) && all.indexOf(id) === index,
+      )
+    : [];
+  if (open.length === 0) return null;
+  return {
+    v: 1,
+    round,
+    mode,
+    understood: oneLine(value["understood"]),
+    ...readAssumed(value["assumed"]),
+    questions,
+    open,
+    answers: readTexts(value["answers"], ids),
+    notes: readTexts(value["notes"], ids),
+    checked: value["checked"],
+  };
+}