paperlint 13.1.0 → 13.2.0

package/skills/build-label-page/scripts/label-page-core.js

@@ -0,0 +1,850 @@
+/**
+ * The CORE of build-label-page's generator, with no page layout: the items.json schema and its
+ * checks, the leak guard, neutral ids, the key with its `allowed` and `needs_why` lists, the check of
+ * the store's dump against the key, and the export (labels and practice). The page is built from its
+ * payload by `label-page-html.ts`; the command line is `label-page.ts`. No side effect on import.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+// ── refusals and output ───────────────────────────────────────────────────────────────────────
+export class Refusal extends Error {
+    exitCode;
+    constructor(exitCode, message) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+export const fail = (message) => {
+    throw new Refusal(1, `REFUSED: ${message}`);
+};
+/** What a run printed, line by line; `cli` takes it out after each run. */
+const printed = [];
+/** The lines printed since the last call, each ending in a newline. */
+export const takePrinted = () => printed
+    .splice(0)
+    .map((l) => `${l}\n`)
+    .join("");
+export const say = (line) => {
+    printed.push(line);
+};
+const isList = (v) => Array.isArray(v);
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const has = (o, key) => Object.hasOwn(o, key);
+// ── how a value is quoted in a message: as Python wrote it, so messages read as before ───────
+const quoted = (s) => {
+    const q = s.includes("'") && !s.includes('"') ? '"' : "'";
+    const body = s
+        .replaceAll("\\", "\\\\")
+        .replaceAll("\n", "\\n")
+        .replaceAll("\t", "\\t")
+        .replaceAll("\r", "\\r");
+    return `${q}${q === "'" ? body.replaceAll("'", "\\'") : body}${q}`;
+};
+const repr = (v) => {
+    if (v === null || v === undefined)
+        return "None";
+    if (typeof v === "boolean")
+        return v ? "True" : "False";
+    if (typeof v === "string")
+        return quoted(v);
+    if (typeof v === "number")
+        return String(v);
+    if (Array.isArray(v))
+        return `[${v.map(repr).join(", ")}]`;
+    return `{${Object.entries(v)
+        .map(([k, x]) => `${quoted(k)}: ${repr(x)}`)
+        .join(", ")}}`;
+};
+/** The name Python gave the type of a value that is not an object, as the dump refusals print it. */
+const typeName = (v) => {
+    if (v === null)
+        return "NoneType";
+    if (Array.isArray(v))
+        return "list";
+    if (typeof v === "number")
+        return Number.isInteger(v) ? "int" : "float";
+    return typeof v === "boolean" ? "bool" : "str";
+};
+/** Code-point order of two strings, as Python's `sorted` has it. */
+const byText = (a, b) => Number(a > b) - Number(a < b);
+const writeJson = (path, value) => {
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+};
+const JSON_VALUE = z.json();
+const readJson = (path) => {
+    try {
+        return JSON_VALUE.parse(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch (e) {
+        return fail(`cannot read ${path} as JSON: ${String(e)}`);
+    }
+};
+// ── THE LEAK GUARD ───────────────────────────────────────────────────────────────────────────
+// What an item may carry. `PAGE_FIELDS` reach the labeller; `PRIVATE_FIELDS` go to key.json only.
+// Anything else on an item — a model answer, a checker verdict, a source label, a difficulty tag —
+// stops the build: a blind page fails by what leaked in, and a field nobody listed is exactly the
+// one nobody thought of. A NEW FIELD IS ADDED HERE ON PURPOSE, after asking "does this tell the
+// labeller what the answer is, or where the item came from?" — never to make a build pass.
+const PAGE_FIELDS = ["group", "title", "body", "code", "context"];
+const PRIVATE_FIELDS = ["source_id"];
+const ALLOWED_FIELDS = [...PAGE_FIELDS, ...PRIVATE_FIELDS];
+const FAMILIARITY = [
+    { value: "well", label: "Well" },
+    { value: "somewhat", label: "Somewhat" },
+    { value: "not_really", label: "Not really" },
+];
+// An id is a key of a plain JavaScript object on the page, so a name Object.prototype already has
+// is refused: `answers["__proto__"] = v` sets the prototype and saves nothing, and an unanswered
+// `answers["constructor"]` reads back a function instead of nothing.
+const RESERVED_NAMES = [
+    "__proto__",
+    "constructor",
+    "prototype",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "toLocaleString",
+    "toString",
+    "valueOf",
+    "__defineGetter__",
+    "__defineSetter__",
+    "__lookupGetter__",
+    "__lookupSetter__",
+];
+const NAME_PATTERN = `(?!(?:${RESERVED_NAMES.join("|")})$)[A-Za-z0-9_-]+`;
+const SOURCES = ["page", "chat"];
+const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
+const string = (required = true, pattern) => pattern === undefined
+    ? { kind: "string", required }
+    : { kind: "string", required, pattern };
+const integer = (required = true) => ({
+    kind: "integer",
+    required,
+});
+const array = (items, required = true, min = 0) => ({
+    kind: "array",
+    required,
+    min,
+    items,
+});
+const mapping = (values, keyPattern, min = 0) => ({
+    kind: "map",
+    required: true,
+    min,
+    key_pattern: keyPattern,
+    values,
+});
+const obj = (fields, closed = true) => ({ kind: "object", required: true, closed, fields });
+const ITEM_SCHEMA = obj({
+    source_id: string(),
+    ...Object.fromEntries(PAGE_FIELDS.map((f) => [f, string(f === "group" || f === "body")])),
+}, false);
+// `icon` (an emoji) tells the buttons apart at a glance. No coloured side stripe on a button: it
+// reads as decoration, not meaning (the build-label-page look test refuses one).
+// `ask_why` (a prompt) makes the answer incomplete until the labeller says why: an approval page's "drop".
+const OPTION_SCHEMA = obj({
+    value: string(),
+    label: string(),
+    example: string(),
+    icon: string(false),
+    ask_why: string(false),
+});
+const PRACTICE_SCHEMA = obj({
+    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group").map((f) => [
+        f,
+        string(f === "body"),
+    ])),
+    expected: mapping(string(), NAME_PATTERN, 1),
+    why: string(),
+});
+const MIN_PRACTICE = 3;
+const QUESTION_SCHEMA = obj({
+    id: string(true, NAME_PATTERN),
+    text: string(),
+    short: string(false),
+    options: array(OPTION_SCHEMA, true, 2),
+});
+export const CONFIG_SCHEMA = obj({
+    study: string(true, NAME_PATTERN), // becomes a file name
+    title: string(),
+    intro: string(false),
+    seed: integer(),
+    groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
+    labeller_knows: array(string(true, NAME_PATTERN), false),
+    familiarity_question: string(false),
+    questions: array(QUESTION_SCHEMA, true, 1),
+    practice: array(PRACTICE_SCHEMA, true, MIN_PRACTICE),
+    practice_round: integer(false),
+    items: array(ITEM_SCHEMA, true, 1),
+});
+// ── checking a value against the schema ──────────────────────────────────────────────────────
+const at = (path, name) => path ? `${path}.${name}` : name;
+const fullMatch = (pattern, s) => new RegExp(`^(?:${pattern})$`, "u").test(s);
+const ID_RULE = "letters, digits, - and _ only";
+function checkString(value, node, where) {
+    if (typeof value !== "string" || !value.trim()) {
+        fail(`${where}: must be a non-empty string, got ${repr(value)}`);
+    }
+    else if (node.pattern !== undefined && !fullMatch(node.pattern, value)) {
+        fail(`${where}: ${repr(value)} must be ${ID_RULE}`);
+    }
+}
+const checkCount = (n, min, where) => {
+    if (n < min)
+        fail(`${where}: needs ${String(min)} or more entries, has ${String(n)}`);
+};
+function checkArray(value, node, path, where) {
+    if (!isList(value))
+        return fail(`${where}: must be a list, got ${repr(value)}`);
+    checkCount(value.length, node.min, where);
+    value.forEach((entry, n) => {
+        checkValue(entry, node.items, `${path}[${String(n)}]`);
+    });
+}
+function checkMap(value, node, path, where) {
+    if (!isObject(value))
+        return fail(`${where}: must be an object, got ${repr(value)}`);
+    checkCount(Object.keys(value).length, node.min, where);
+    for (const [key, entry] of Object.entries(value)) {
+        if (!fullMatch(node.key_pattern, key))
+            fail(`${at(path, key)}: key must be ${ID_RULE}`);
+        checkValue(entry, node.values, at(path, key));
+    }
+}
+function checkObject(value, node, path, where) {
+    if (!isObject(value))
+        return fail(`${where}: must be an object, got ${repr(value)}`);
+    for (const [name, sub] of Object.entries(node.fields)) {
+        if (has(value, name))
+            checkValue(value[name] ?? null, sub, at(path, name));
+        else if (sub.required)
+            fail(`${at(path, name)}: is required and missing`);
+    }
+    const unknown = Object.keys(value).find((name) => !has(node.fields, name));
+    if (node.closed && unknown !== undefined) {
+        fail(`${at(path, unknown)}: not a known field (known: ${Object.keys(node.fields).join(", ")})`);
+    }
+}
+/** Refuse the first place `value` departs from `node`; the message starts with the field's path. */
+function checkValue(value, node, path) {
+    const where = path || "items.json";
+    switch (node.kind) {
+        case "string":
+            checkString(value, node, where);
+            break;
+        case "integer":
+            if (typeof value !== "number" || !Number.isInteger(value)) {
+                fail(`${where}: must be an integer, got ${repr(value)}`);
+            }
+            break;
+        case "array":
+            checkArray(value, node, path, where);
+            break;
+        case "map":
+            checkMap(value, node, path, where);
+            break;
+        case "object":
+            checkObject(value, node, path, where);
+    }
+}
+/** The config is typed by passing CONFIG_SCHEMA: `checkValue` refuses (throws) on any departure. */
+function assertConfig(value) {
+    checkValue(value, CONFIG_SCHEMA, "");
+}
+/**
+ * THE definition of a valid answer: the values the build offers, per question and for familiarity.
+ * The page script (`DATA.allowed`) and the exporter (`key.json`) both read this one result, so a
+ * stored value counts as an answer on the page exactly when it counts in the export.
+ */
+const allowedValues = (questions) => ({
+    questions: Object.fromEntries(questions.map((q) => [q.id, q.options.map((o) => o.value)])),
+    // The answers that need a reason, per question: the page and the export read the same list.
+    needs_why: Object.fromEntries(questions.map((q) => [
+        q.id,
+        q.options.filter((o) => o.ask_why !== undefined).map((o) => o.value),
+    ])),
+    familiarity: FAMILIARITY.map((o) => o.value),
+});
+/** Two values that read the same once case and surrounding space are gone. */
+const readsAs = (s) => s.trim().toLowerCase();
+/** The first entry whose reading repeats an earlier one, with the index of that earlier one. */
+const firstRepeat = (labels) => {
+    const seen = labels.map(readsAs);
+    const at = seen.findIndex((x, i) => seen.indexOf(x) !== i);
+    return at === -1
+        ? undefined
+        : { at, earlier: seen.findIndex((x) => x === seen[at]) };
+};
+// What a schema cannot say: references between fields, and values that must differ.
+function checkGroups(cfg) {
+    // The page heads each group with its label: two that read the same are two familiarity questions
+    // the labeller cannot tell apart, exported under different group ids.
+    const ids = Object.keys(cfg.groups);
+    const labels = Object.values(cfg.groups);
+    const twice = firstRepeat(labels);
+    if (twice !== undefined) {
+        fail(`groups.${String(ids[twice.at])}: ${repr(labels[twice.at])} reads the same as groups.${String(ids[twice.earlier])} — each group needs its own label`);
+    }
+    (cfg.labeller_knows ?? []).forEach((gid, n) => {
+        if (!has(cfg.groups, gid))
+            fail(`labeller_knows[${String(n)}]: ${repr(gid)} is not in \`groups\``);
+    });
+}
+function checkQuestion(q, qn, earlierIds) {
+    if (earlierIds.includes(q.id))
+        fail(`questions[${String(qn)}].id: ${repr(q.id)} is repeated`);
+    const values = q.options.map((o) => o.value);
+    if (new Set(values).size !== values.length) {
+        fail(`questions[${String(qn)}].options: values must be distinct, got ${repr(values)}`);
+    }
+    // Two buttons that read the same store different answers no one can tell apart afterwards.
+    const twice = firstRepeat(q.options.map((o) => o.label));
+    if (twice !== undefined) {
+        fail(`questions[${String(qn)}].options[${String(twice.at)}].label: ${repr(q.options[twice.at]?.label)} reads the same as options[${String(twice.earlier)}].label — each button needs its own label`);
+    }
+}
+/**
+ * Each practice item knows the answer to every question, and only offered answers: a practice the
+ * page cannot score would let a misread question through unseen.
+ */
+function checkPractice(cfg) {
+    const offered = Object.fromEntries(cfg.questions.map((q) => [q.id, q.options.map((o) => o.value)]));
+    if ((cfg.practice_round ?? 1) < 1) {
+        fail(`practice_round: ${repr(cfg.practice_round)} — must be 1 or more`);
+    }
+    cfg.practice.forEach((item, n) => {
+        const where = `practice[${String(n)}].expected`;
+        for (const [q, v] of Object.entries(item.expected)) {
+            const values = offered[q];
+            if (values === undefined)
+                fail(`${where}.${q}: not a question of this page (${Object.keys(offered).join(", ")})`);
+            else if (!values.includes(v))
+                fail(`${where}.${q}: ${repr(v)} is not one of ${values.join(", ")}`);
+        }
+        const missing = Object.keys(offered).find((q) => !has(item.expected, q));
+        if (missing !== undefined)
+            fail(`${where}.${missing}: every question needs its expected answer`);
+    });
+}
+function checkConfig(cfg) {
+    checkGroups(cfg);
+    cfg.questions.forEach((q, qn) => {
+        checkQuestion(q, qn, cfg.questions.slice(0, qn).map((x) => x.id));
+    });
+    checkPractice(cfg);
+}
+/** The practice as the page shows it and the key keeps it: neutral ids P1, P2 … in the given order. */
+const practiceOf = (cfg) => cfg.practice.map((item, n) => ({ id: `P${String(n + 1)}`, ...item }));
+// ── the items: the leak guard, and the references to the config ───────────────────────────────
+function checkItemFields(cfg) {
+    const sids = [];
+    cfg.items.forEach((item, n) => {
+        const extra = Object.keys(item)
+            .filter((f) => !ALLOWED_FIELDS.includes(f))
+            .sort();
+        if (extra.length) {
+            fail(`item #${String(n)} (${item.source_id}) carries ${extra.join(", ")}, which is not in the allow-list ${repr([...ALLOWED_FIELDS].sort())}. A blind page shows the labeller the item and nothing about the answer or the source. Remove the field from items.json; add it to PAGE_FIELDS only if it is safe for the labeller to see.`);
+        }
+        if (sids.includes(item.source_id))
+            fail(`items[${String(n)}].source_id: ${repr(item.source_id)} is repeated`);
+        sids.push(item.source_id);
+        if (!has(cfg.groups, item.group))
+            fail(`items[${String(n)}].group: ${repr(item.group)} is not in \`groups\``);
+    });
+}
+const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
+/**
+ * A source id typed into a visible field gives the source away as well as a field would. Short ids
+ * ("7") would match ordinary text, so only ids of four characters or more are looked for.
+ */
+function checkNoSourceShown(cfg) {
+    const long = cfg.items
+        .map((i) => i.source_id)
+        .filter((sid) => sid.length >= 4);
+    for (const item of cfg.items) {
+        for (const sid of long) {
+            const word = new RegExp(`(?<![\\p{L}\\p{N}_-])${escapeRegExp(sid)}(?![\\p{L}\\p{N}_-])`, "u");
+            const field = PAGE_FIELDS.find((f) => word.test(item[f] ?? ""));
+            if (field !== undefined) {
+                fail(`the source id ${repr(sid)} appears in the visible \`${field}\` of item ${item.source_id}. Take it out of the text (or use source ids that are not natural words).`);
+            }
+        }
+    }
+}
+/** key.json is this script's own output, written by `build`; its shape is trusted, not re-checked. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- an assertion signature, no body to run
+function assertOwnKey(_value) { }
+const readOldKey = (keyPath, seed) => {
+    if (!existsSync(keyPath))
+        return undefined;
+    const old = readJson(keyPath);
+    assertOwnKey(old);
+    if (old.seed !== seed) {
+        fail(`${keyPath} was made with seed ${String(old.seed)}; this config says ${String(seed)}. Answers are keyed by the old ids: restore the seed, or start a new study folder.`);
+    }
+    return old;
+};
+/** Neutral ids G001… in an order fixed by the seed, and kept when a key file already exists. */
+function assignIds(items, seed, keyPath) {
+    const old = readOldKey(keyPath, seed);
+    const entries = old?.ids ?? {};
+    const known = new Map(Object.entries(entries).map(([nid, v]) => [v.source_id, nid]));
+    const rank = (s) => createHash("sha256")
+        .update(`${String(seed)}:${s}`)
+        .digest("hex");
+    const fresh = items
+        .map((i) => i.source_id)
+        .filter((sid) => !known.has(sid))
+        .sort((a, b) => byText(rank(a), rank(b)));
+    const ids = new Map([
+        ...known,
+        ...fresh.map((sid, k) => [
+            sid,
+            `G${String(known.size + k + 1).padStart(3, "0")}`,
+        ]),
+    ]);
+    return { ids, entries };
+}
+// ── a build, short of the page ──────────────────────────────────────────────────────────────────
+const shownFields = (item) => Object.fromEntries(PAGE_FIELDS.flatMap((f) => {
+    const v = item[f];
+    return v === undefined ? [] : [[f, v]];
+}));
+/** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
+function itemsOnPage(cfg, keyPath) {
+    const knows = cfg.labeller_knows;
+    const items = cfg.items.filter((i) => knows === undefined || knows.includes(i.group));
+    if (!items.length)
+        fail("no item is left after `labeller_knows`");
+    const { ids, entries } = assignIds(items, cfg.seed, keyPath);
+    // Every item on the page was given an id by `assignIds` above.
+    const idOf = (i) => String(ids.get(i.source_id));
+    const sorted = [...items].sort((a, b) => byText(idOf(a), idOf(b)));
+    return { items: sorted, ids, entries, idOf };
+}
+const practiceRound = (cfg) => cfg.practice_round ?? 1;
+/** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
+function payloadOf(cfg, page) {
+    const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
+    return {
+        title: cfg.title,
+        intro: cfg.intro ?? "",
+        groups: used.map((g) => ({ id: g, label: String(cfg.groups[g]) })),
+        familiarity_question: cfg.familiarity_question ?? "How well do you know {group}?",
+        familiarity: FAMILIARITY,
+        allowed: allowedValues(cfg.questions),
+        questions: cfg.questions,
+        practice: { round: practiceRound(cfg), items: practiceOf(cfg) },
+        items: page.items.map((i) => ({ id: page.idOf(i), ...shownFields(i) })),
+    };
+}
+/** Every id the key keeps (on the page now, or kept from an earlier build), with its source and group. */
+function idsOf(cfg, page) {
+    const shown = new Set(page.items.map(page.idOf));
+    const groupOf = new Map([
+        ...Object.values(page.entries).map((v) => [
+            v.source_id,
+            v.group,
+        ]),
+        ...cfg.items.map((i) => [i.source_id, i.group]),
+    ]);
+    const byId = [...page.ids].sort(([, a], [, b]) => byText(a, b));
+    return Object.fromEntries(byId.map(([sid, nid]) => [
+        nid,
+        {
+            source_id: sid,
+            group: String(groupOf.get(sid)),
+            on_page: shown.has(nid),
+        },
+    ]));
+}
+/** Every round of a key's practice; a key from before `rounds` has only its own round. */
+const roundsIn = (p) => p.rounds ?? { [String(p.round)]: p.expected };
+/** The rounds an existing key holds, kept by the next build. */
+const roundsOf = (keyPath) => {
+    if (!existsSync(keyPath))
+        return {};
+    const old = readJson(keyPath);
+    assertKey(old);
+    return old.practice === undefined ? {} : roundsIn(old.practice);
+};
+function keyOf(cfg, page, earlier) {
+    const practice = practiceOf(cfg);
+    return {
+        study: cfg.study,
+        seed: cfg.seed,
+        questions: cfg.questions.map((q) => q.id),
+        // What counts as an answer: the same lists the page was given (`allowedValues`). `export`
+        // checks every stored answer and familiarity against them, so the build's options decide.
+        allowed: allowedValues(cfg.questions),
+        // The practice is scored against this at export; its answers never go into the labels.
+        practice: {
+            round: practiceRound(cfg),
+            expected: Object.fromEntries(practice.map((p) => [p.id, p.expected])),
+            // Every round's items and expected answers, kept across rebuilds: an earlier round's stored
+            // answers stay known to the export (a later round may have fewer items) and are scored too.
+            rounds: {
+                ...earlier,
+                [String(practiceRound(cfg))]: Object.fromEntries(practice.map((p) => [p.id, p.expected])),
+            },
+        },
+        ids: idsOf(cfg, page),
+    };
+}
+/**
+ * Everything a build does but lay out the page: reads and checks items.json (the schema, the
+ * cross-field checks, the leak guard), gives the items their ids, writes key.json beside the page and
+ * returns what the page shows. A page written by hand can take its blindness and its key from here.
+ */
+export function prepareBuild(configPath, outDir) {
+    const cfg = readJson(configPath);
+    assertConfig(cfg);
+    checkConfig(cfg);
+    checkItemFields(cfg);
+    checkNoSourceShown(cfg);
+    mkdirSync(outDir, { recursive: true });
+    const keyPath = join(outDir, "key.json");
+    const earlier = roundsOf(keyPath);
+    const page = itemsOnPage(cfg, keyPath);
+    writeJson(keyPath, keyOf(cfg, page, earlier));
+    return {
+        payload: payloadOf(cfg, page),
+        dropped: cfg.items.length - page.items.length,
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- an assertion signature, no body to run
+function assertKey(_value) {
+    // key.json is this script's own output; what an older build left out is checked where it is read.
+}
+const ANSWER_DOC_FIELDS = ["answers", "reasons", "savedAt", "source"];
+const GROUP_DOC_FIELDS = ["familiarity", "savedAt", "source"];
+const DOC_FIELD_TYPES = [
+    ["answers", isObject, "an object {question: value}"],
+    ["reasons", isObject, "an object {question: text}"],
+    [
+        "familiarity",
+        (v) => v === null || typeof v === "string",
+        "a familiarity value (a string) or null",
+    ],
+    [
+        "savedAt",
+        (v) => v === null || typeof v === "string",
+        "a timestamp string or null",
+    ],
+];
+const COLLECTIONS = ["answers", "groups", "practice"];
+const COLLECTION_NAMES = COLLECTIONS;
+const NOUN = {
+    answers: "answer",
+    groups: "group",
+    practice: "practice item",
+};
+/**
+ * The store documents a practice of this key may have: every round up to the key's, so the answers
+ * of an earlier round are known (and kept), not refused.
+ */
+const practiceDocs = (key) => {
+    const p = key.practice;
+    if (p === undefined)
+        return [];
+    // Each round's own questions: a later round may have dropped or renamed one.
+    return Object.entries(roundsIn(p)).flatMap(([r, expected]) => Object.entries(expected).map(([pid, answers]) => [`r${r}-${pid}`, Object.keys(answers)]));
+};
+function knownNames(key) {
+    const entries = Object.entries(key.ids);
+    const shown = entries.filter(([, m]) => m.on_page);
+    const practice = practiceDocs(key);
+    return {
+        answers: {
+            known: entries.map(([nid]) => [nid, key.questions]),
+            onPage: shown.map(([nid]) => nid),
+            fields: ANSWER_DOC_FIELDS,
+        },
+        groups: {
+            known: entries.map(([, m]) => [m.group, key.questions]),
+            onPage: shown.map(([, m]) => m.group),
+            fields: GROUP_DOC_FIELDS,
+        },
+        practice: {
+            known: practice,
+            onPage: practice.map(([n]) => n),
+            fields: ANSWER_DOC_FIELDS,
+        },
+    };
+}
+const sortedEntries = (o) => Object.entries(o).sort(([a], [b]) => byText(a, b));
+function checkDumpShape(dump) {
+    if (!isObject(dump))
+        return fail(`store: ${typeName(dump)} — must be an object {answers, groups, practice}`);
+    for (const kind of COLLECTIONS) {
+        const c = dump[kind];
+        if (c !== undefined && !isObject(c))
+            fail(`${kind}: ${typeName(c)} — must be an object {id: stored document}`);
+    }
+    const stray = Object.keys(dump)
+        .sort()
+        .find((top) => !COLLECTION_NAMES.includes(top));
+    if (stray !== undefined)
+        fail(`${stray}: the store has no such collection (expected ${COLLECTIONS.join(", ")})`);
+}
+function checkDocName(where, name, kind, names) {
+    const hit = names.known.find(([n]) => n === name);
+    if (hit === undefined) {
+        return fail(`${where}: the key does not know this ${NOUN[kind]} (${[...new Set(names.known.map(([n]) => n))].sort().join(", ")})`);
+    }
+    if (!names.onPage.includes(name)) {
+        fail(`${where}: stored, but no longer on the page (a rebuild left it out), so the export would drop it; rebuild with it on the page, or take it out of the dump on purpose`);
+    }
+    return hit[1];
+}
+function checkDocFields(where, doc, kind, fields) {
+    if (!isObject(doc))
+        return fail(`${where}: must be an object with ${fields.join(", ")}`);
+    const stray = Object.keys(doc)
+        .sort()
+        .find((f) => !fields.includes(f));
+    if (stray !== undefined)
+        fail(`${where}/${stray}: not a field of a stored ${NOUN[kind]} (${fields.join(", ")})`);
+    if (!has(doc, "source"))
+        fail(`${where}: no source; add "source": "chat" or "page" (one of ${SOURCES_SHOWN})`);
+    const source = doc["source"];
+    if (typeof source !== "string" || !SOURCES.includes(source)) {
+        fail(`${where}/source: ${repr(source)}; expected one of ${SOURCES_SHOWN}`);
+    }
+    // The types the export reads, so a hand merge is refused by path rather than crashing it.
+    for (const [field, ok, what] of DOC_FIELD_TYPES) {
+        const v = doc[field];
+        if (v !== undefined && !ok(v))
+            fail(`${where}/${field}: ${repr(v)} — must be ${what}`);
+    }
+}
+function checkDocAnswers(where, doc, questions) {
+    const known = (part, q) => {
+        if (!questions.includes(q))
+            fail(`${where}/${part}/${q}: not a question of the key (${questions.join(", ")})`);
+    };
+    for (const [q, v] of sortedEntries(isObject(doc["answers"]) ? doc["answers"] : {})) {
+        known("answers", q);
+        if (v !== null && typeof v !== "string")
+            fail(`${where}/answers/${q}: ${repr(v)} — must be an option value (a string) or null`);
+    }
+    for (const [q, v] of sortedEntries(isObject(doc["reasons"]) ? doc["reasons"] : {})) {
+        known("reasons", q);
+        if (typeof v !== "string")
+            fail(`${where}/reasons/${q}: ${repr(v)} — must be text`);
+    }
+}
+/**
+ * The whole store against the key, ONCE, before anything is read from it. Every name in it must be
+ * one the key knows: an item id, a group, a question id, a field of the document; an item or group
+ * must also still be on the page, or a rebuild that left it out would drop its stored answer. A
+ * name the export does not read would otherwise be dropped without a word — a misspelled question
+ * key in a chat merge (`boundry`), a misspelled group (`pyhton`) — and its answer lost from the
+ * labels. Refuses, naming the path; the fix is one edit in the dump. Every document also says where
+ * it came from: the page always writes `source: "page"`, so a document without one was merged by hand.
+ */
+function checkDump(dump, key) {
+    checkDumpShape(dump);
+    const names = knownNames(key);
+    for (const kind of COLLECTIONS) {
+        const collection = dump[kind];
+        for (const [name, doc] of sortedEntries(isObject(collection) ? collection : {})) {
+            const where = `${kind}/${name}`;
+            const questions = checkDocName(where, name, kind, names[kind]);
+            checkDocFields(where, doc, kind, names[kind].fields);
+            checkDocAnswers(where, doc, questions);
+        }
+    }
+}
+/** The key's `allowed` lists, or a refusal naming a key made by an older build. */
+function assertAllowed(a, key, keyPath) {
+    const questions = isObject(a) ? a["questions"] : undefined;
+    const complete = isObject(a) &&
+        has(a, "familiarity") &&
+        isObject(questions) &&
+        key.questions.every((q) => has(questions, q));
+    if (!complete) {
+        fail(`${keyPath} has no \`allowed\` values for every question and for familiarity (made by an older build). Run \`build\` again with the same items.json and seed: ids are kept, the key gains them.`);
+    }
+}
+const docOf = (collection, name) => {
+    const doc = isObject(collection) ? collection[name] : undefined;
+    return isObject(doc) ? doc : {};
+};
+/** The values a question offers (or needs a reason for); the key has a list for every question. */
+const valuesOf = (lists, q) => Object.entries(lists)
+    .filter(([k]) => k === q)
+    .flatMap(([, vs]) => vs);
+const listed = (lists, q, v) => valuesOf(lists, q).includes(v);
+const textOf = (v) => typeof v === "string" ? v : null;
+/** The text values of a stored object (answers, reasons): a null answer is no text. */
+const textsOf = (o) => Object.fromEntries(Object.entries(isObject(o) ? o : {}).filter((e) => typeof e[1] === "string"));
+/**
+ * An answer outside the question's allowed values (a typo in a chat answer, an option that was
+ * removed or renamed between builds) is MARKED, not refused and not dropped: the item is
+ * incomplete, the raw value is kept under `invalid_answers`, and the report names the item.
+ * Refusing would hold every good label hostage to one typo at the moment the export must happen
+ * (checklist rule 6); dropping it would lose what the labeller said.
+ */
+function answersOf(doc, ctx) {
+    const stored = textsOf(doc["answers"]);
+    const raw = ctx.key.questions.map((q) => [
+        q,
+        stored[q] ?? null,
+    ]);
+    const invalid = Object.fromEntries(raw.filter(([q, v]) => v !== null && !listed(ctx.allowed.questions, q, v)));
+    const given = Object.fromEntries(raw.map(([q, v]) => [q, has(invalid, q) ? null : v]));
+    return { given, invalid };
+}
+/** One item of the labels file: its answers, what is invalid, the reasons, and whether it is done. */
+function labelOf(nid, meta, doc, ctx) {
+    const { given, invalid } = answersOf(doc, ctx);
+    const reasons = Object.fromEntries(Object.entries(textsOf(doc["reasons"])).filter(([, r]) => r.trim()));
+    const needsWhy = ctx.allowed.needs_why ?? {};
+    const unexplained = Object.entries(given)
+        .filter(([q, v]) => v !== null && listed(needsWhy, q, v) && !has(reasons, q))
+        .map(([q]) => q);
+    return {
+        id: nid,
+        source_id: meta.source_id,
+        group: meta.group,
+        answers: given,
+        invalid_answers: invalid,
+        reasons,
+        unexplained,
+        complete: Object.values(given).every((v) => v !== null) && !unexplained.length,
+        source: textOf(doc["source"]),
+        saved_at: doc["savedAt"] ?? null,
+    };
+}
+/** Same rule as for item answers: a familiarity outside the options is marked, not counted as rated. */
+function groupsOf(groupIds, groups, allowed) {
+    return Object.fromEntries(groupIds.map((g) => {
+        const doc = docOf(groups, g);
+        const fam = textOf(doc["familiarity"]);
+        const bad = fam !== null && !allowed.familiarity.includes(fam);
+        return [
+            g,
+            {
+                familiarity: bad ? null : fam,
+                invalid_familiarity: bad ? fam : null,
+                source: textOf(doc["source"]),
+                saved_at: doc["savedAt"] ?? null,
+            },
+        ];
+    }));
+}
+function reportLabels(items, allowed) {
+    for (const i of items) {
+        for (const [q, v] of Object.entries(i.invalid_answers)) {
+            say(`  invalid ${i.id}: ${q}=${repr(v)} is not one of ${valuesOf(allowed.questions, q).join(", ")} (not counted)`);
+        }
+        const missing = Object.entries(i.answers)
+            .filter(([q, v]) => v === null && !has(i.invalid_answers, q))
+            .map(([q]) => q);
+        if (missing.length)
+            say(`  incomplete ${i.id}: missing ${missing.join(", ")}`);
+        for (const q of i.unexplained)
+            say(`  incomplete ${i.id}: ${q}=${String(i.answers[q])} needs a reason`);
+    }
+}
+function reportGroups(groups, allowed) {
+    for (const [g, v] of Object.entries(groups)) {
+        if (v.invalid_familiarity !== null) {
+            say(`  invalid group ${g}: familiarity=${repr(v.invalid_familiarity)} is not one of ${allowed.familiarity.join(", ")} (not counted as rated)`);
+        }
+        else if (v.familiarity === null)
+            say(`  group ${g}: no familiarity answer`);
+    }
+}
+/** Each practice item of the key's round: what was answered first, what was expected, whether they match. */
+function scorePractice(dump, round, all) {
+    return Object.entries(all).map(([pid, expected]) => {
+        const doc = docOf(dump["practice"], `r${round}-${pid}`);
+        const answers = isObject(doc["answers"]) ? doc["answers"] : {};
+        const matched = Object.entries(expected).every(([q, v]) => answers[q] === v);
+        return {
+            id: pid,
+            answers,
+            expected,
+            matched,
+            savedAt: doc["savedAt"] ?? null,
+        };
+    });
+}
+/** One file per round: a second round exported the same day keeps the first. */
+const practiceFile = (study, round, day) => `${study}-practice-r${String(round)}-${day}.json`;
+/**
+ * Every practice round the store holds answers for, each scored against its own expected answers
+ * into its own file; never into the labels. The key's own round is reported even unanswered.
+ */
+function exportPractice(dump, key, target, day) {
+    const p = key.practice;
+    if (p === undefined)
+        return;
+    Object.entries(roundsIn(p))
+        .sort(([a], [b]) => Number(a) - Number(b))
+        .forEach(([round, expected]) => {
+        exportRound(key.study, Number(round), scorePractice(dump, round, expected), {
+            target,
+            day,
+            current: Number(round) === p.round,
+        });
+    });
+}
+/** One round's scored practice to `<study>-practice-r<round>-<date>.json`, and one line about it. */
+function exportRound(study, round, items, at) {
+    if (!items.some((i) => Object.keys(i.answers).length)) {
+        if (at.current)
+            say(`practice round ${String(round)}: not answered`);
+        return;
+    }
+    const missed = items.filter((i) => !i.matched).map((i) => i.id);
+    const matched = items.length - missed.length;
+    const path = join(at.target, practiceFile(study, round, at.day));
+    writeJson(path, {
+        study,
+        round,
+        exported: at.day,
+        matched,
+        total: items.length,
+        items,
+    });
+    say(`practice round ${String(round)}: ${String(matched)} of ${String(items.length)} matched${missed.length ? `; missed ${missed.join(", ")}` : ""} -> ${path}`);
+}
+/** The labels file: every item on the page with its answers, the groups, and the counts. */
+function labelsOf(dump, ctx, day) {
+    const onPage = Object.entries(ctx.key.ids).filter(([, m]) => m.on_page);
+    const items = onPage.map(([nid, meta]) => labelOf(nid, meta, docOf(dump["answers"], nid), ctx));
+    const groups = groupsOf([...new Set(onPage.map(([, m]) => m.group))], dump["groups"], ctx.allowed);
+    return {
+        study: ctx.key.study,
+        exported: day,
+        questions: ctx.key.questions,
+        items,
+        groups,
+        complete_items: items.filter((i) => i.complete).length,
+        invalid_items: items.filter((i) => Object.keys(i.invalid_answers).length)
+            .length,
+        invalid_groups: Object.values(groups).filter((g) => g.invalid_familiarity !== null).length,
+        total_items: items.length,
+    };
+}
+export function exportLabels(dumpPath, keyPath, outDir, day) {
+    const dump = readJson(dumpPath);
+    const key = readJson(keyPath);
+    assertKey(key);
+    const allowed = key.allowed;
+    assertAllowed(allowed, key, keyPath);
+    checkDump(dump, key);
+    const out = labelsOf(dump, { key, allowed }, day);
+    mkdirSync(outDir, { recursive: true });
+    const path = join(outDir, `${key.study}-labels-${day}.json`);
+    writeJson(path, out);
+    exportPractice(dump, key, outDir, day);
+    say(`wrote ${path}: ${String(out.complete_items)} of ${String(out.total_items)} items complete`);
+    reportLabels(out.items, allowed);
+    reportGroups(out.groups, allowed);
+}