From 10c007348968dd161b44aab50236105213de7f6c Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:13:21 -0400
Subject: [PATCH 1/4] feat(pdf): a flat form's fill-in list comes from the
 fields tagging makes

A scanned or flat PDF has no form fields, so the demo offered nothing to
fill in. iris-pdf 4533bdf (#13) makes fields from the HTML's controls,
named the same way on every run. GET /fields now tags such a PDF once,
with no values, and lists the fields on the output. /pdf then fills them
by those names.

Only when the source has no fields, the session is extracted, and the
HTML has an input, select or textarea. A failed tag lists none; the
download reports the error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/API.md                     |  3 +-
 public/demo.html                |  4 +-
 src/routes/sessions.ts          | 67 ++++++++++++++++++++++-----------
 src/util/taggedPdf.ts           | 19 +++++++++-
 test/fixtures/fake-iris-pdf.mjs | 12 +++++-
 test/tagged-pdf.test.ts         | 58 ++++++++++++++++++++++++++--
 6 files changed, 133 insertions(+), 30 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index d80c57d0..017bbc97 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -987,7 +987,8 @@ curl -s -H "$AUTH" "$BASE/sessions/$SID/fields" | jq '.fields[0]'
 ```
 
 `type` is one of `text`, `checkbox`, `radio`, `combobox`, `listbox`, `button` or `signature`. A PDF with
-no form gives `{"fields": []}`. It can answer `404`, `409 no_source_pdf`, `422` for a PDF the tagger
+no form gives `{"fields": []}`, unless its HTML has form controls. Then tagging makes the fields, so this
+tags the PDF once and lists those, by the names `/pdf` fills. It can answer `404`, `409 no_source_pdf`, `422` for a PDF the tagger
 refuses, or `503 busy`, the same as below.
 
 **Get the tagged PDF:**
diff --git a/public/demo.html b/public/demo.html
index a4b197e8..37c128dd 100644
--- a/public/demo.html
+++ b/public/demo.html
@@ -167,8 +167,8 @@ <h2 id="result-h" tabindex="-1">Your accessible HTML</h2>
       </div>
 
       <!-- Only where this deployment makes tagged PDFs (GET /v1/limits `tagged_pdf`) and
-           the upload was one PDF. The fields come from that PDF (GET .../fields), so the
-           form is built when the result is shown. -->
+           the upload was one PDF. The fields come from that PDF, or for a flat form from
+           tagging it (GET .../fields), so the form is built when the result is shown. -->
       <div id="pdf-part" hidden>
         <h3 id="pdf-h">Get your PDF back, tagged</h3>
         <p>The same PDF you uploaded, tagged so a screen reader can read it in order. The pages look the same. The tags come from Iris's first reading of each page, before review, so the HTML above is the more accurate version.</p>
diff --git a/src/routes/sessions.ts b/src/routes/sessions.ts
index 527db36f..72e38c39 100644
--- a/src/routes/sessions.ts
+++ b/src/routes/sessions.ts
@@ -42,7 +42,7 @@ import {
 } from "../providers/imageLimits.ts";
 import { imageDimensions } from "../util/imageSize.ts";
 import { usableFieldName } from "../pipeline/fields.ts";
-import { readFields, tagPdf, taggedPdfCommand, tagTimeoutSeconds, TaggedPdfError, type PdfField } from "../util/taggedPdf.ts";
+import { createdFields, readFields, tagPdf, taggedPdfCommand, tagTimeoutSeconds, TaggedPdfError, type PdfField, type TagInput } from "../util/taggedPdf.ts";
 
 // 50 MB is a memory bound, not the image limit. It stays well above what an image may
 // be (see imageLimits.ts) because a PDF legitimately is: 25 pages of scans is a large
@@ -602,6 +602,33 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
     return true;
   }
 
+  function readyToTag(s: SessionRecord): boolean {
+    return (s.status === "ready_for_review" || s.status === "closed") && existsSync(paths.sessionFinalFragments(s.session_id));
+  }
+  // The download's name, and the pages as extracted, for the tagger. Order is the PDF's page
+  // number, because the session is one PDF. A page that failed extraction holds only its
+  // `@page-failed` note, so it is left out and the tagger reports it untagged.
+  function tagInput(s: SessionRecord): { base: string; input: TagInput } {
+    const finalPath = paths.sessionFinalFragments(s.session_id);
+    const base = existsSync(paths.sessionSourceName(s.session_id))
+      ? readFileSync(paths.sessionSourceName(s.session_id), "utf8").trim() || "document"
+      : "document";
+    const { fragments = [] } = JSON.parse(readFileSync(finalPath, "utf8")) as { fragments?: Fragment[] };
+    const outPath = paths.sessionOutput(s.session_id);
+    const output = existsSync(outPath) ? readFileSync(outPath, "utf8") : "";
+    return {
+      base,
+      input: {
+        lang: output.match(/<html\b[^>]*\blang="([^"]+)"/i)?.[1],
+        title: base,
+        pages: [...fragments]
+          .filter((f) => !f.innerHtml.trimStart().startsWith("<!-- @page-failed"))
+          .sort((a, b) => a.order - b.order)
+          .map((f) => ({ sourcePage: f.order, html: f.innerHtml })),
+      },
+    };
+  }
+
   // GET /v1/sessions/{id}/fields — the source PDF's form fields, for a fill-in form.
   r.get("/:id/fields", async (req: AuthedRequest, res) => {
     const src = sourcePdf(req, res);
@@ -609,7 +636,22 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
     if (tooBusy(res)) return;
     tagging++;
     try {
-      res.json({ fields: await readFields(src.command, src.pdf) });
+      let fields = await readFields(src.command, src.pdf);
+      // A PDF with no fields, whose HTML has form controls: a flat form. Tagging gives it
+      // fields, so list those. If that fails, list none; the download says why.
+      if (!fields.length && readyToTag(src.s)) {
+        fields = await (async () => {
+          const { input } = tagInput(src.s);
+          if (!input.pages.some((p) => /<(input|select|textarea)\b/i.test(p.html))) return [];
+          return createdFields(src.command, {
+            pdfPath: src.pdf,
+            input,
+            scratchRoot: paths.pdfScratchRoot(),
+            timeoutSeconds: tagTimeoutSeconds(cfg),
+          });
+        })().catch(() => []);
+      }
+      res.json({ fields });
     } catch (e) {
       taggerError(res, e);
     } finally {
@@ -624,8 +666,7 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
     const src = sourcePdf(req, res);
     if (!src) return;
     const { s } = src;
-    const finalPath = paths.sessionFinalFragments(s.session_id);
-    if ((s.status !== "ready_for_review" && s.status !== "closed") || !existsSync(finalPath)) {
+    if (!readyToTag(s)) {
       sendError(res, 409, "invalid_state", "The PDF can be tagged once the session is ready_for_review.");
       return;
     }
@@ -639,23 +680,7 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
     const started = Date.now();
     tagging++;
     try {
-      const base = existsSync(paths.sessionSourceName(s.session_id))
-        ? readFileSync(paths.sessionSourceName(s.session_id), "utf8").trim() || "document"
-        : "document";
-      // The pages as extracted, by page order. Order is the PDF's page number, because
-      // the session is one PDF. A page that failed extraction holds only its
-      // `@page-failed` note, so it is left out and the tagger reports it untagged.
-      const { fragments = [] } = JSON.parse(readFileSync(finalPath, "utf8")) as { fragments?: Fragment[] };
-      const outPath = paths.sessionOutput(s.session_id);
-      const output = existsSync(outPath) ? readFileSync(outPath, "utf8") : "";
-      const input = {
-        lang: output.match(/<html\b[^>]*\blang="([^"]+)"/i)?.[1],
-        title: base,
-        pages: [...fragments]
-          .filter((f) => !f.innerHtml.trimStart().startsWith("<!-- @page-failed"))
-          .sort((a, b) => a.order - b.order)
-          .map((f) => ({ sourcePage: f.order, html: f.innerHtml })),
-      };
+      const { base, input } = tagInput(s);
       const { pdf, report } = await tagPdf(src.command, {
         pdfPath: src.pdf,
         input,
diff --git a/src/util/taggedPdf.ts b/src/util/taggedPdf.ts
index c17c8a96..6b5a2d6f 100644
--- a/src/util/taggedPdf.ts
+++ b/src/util/taggedPdf.ts
@@ -123,6 +123,23 @@ export async function tagPdf(
   command: string,
   args: { pdfPath: string; input: TagInput; values: Record<string, unknown>; scratchRoot: string; timeoutSeconds: number },
 ): Promise<{ pdf: Buffer; report: unknown }> {
+  return inScratch(command, args, (out, report) => ({ pdf: readFileSync(out), report: JSON.parse(readFileSync(report, "utf8")) }));
+}
+
+// The fields a flat form gets when tagged: iris-pdf makes them from the HTML's controls, and
+// names them the same way on every run. So tag it with no values and read them off the output.
+export async function createdFields(
+  command: string,
+  args: { pdfPath: string; input: TagInput; scratchRoot: string; timeoutSeconds: number },
+): Promise<PdfField[]> {
+  return inScratch(command, { ...args, values: {} }, (out) => readFields(command, out));
+}
+
+async function inScratch<T>(
+  command: string,
+  args: { pdfPath: string; input: TagInput; values: Record<string, unknown>; scratchRoot: string; timeoutSeconds: number },
+  read: (out: string, report: string) => T | Promise<T>,
+): Promise<T> {
   mkdirSync(args.scratchRoot, { recursive: true });
   const dir = mkdtempSync(join(args.scratchRoot, "pdf-"));
   const f = (name: string) => join(dir, name);
@@ -135,7 +152,7 @@ export async function tagPdf(
     } catch (e) {
       throw failure(e);
     }
-    return { pdf: readFileSync(f("out.pdf")), report: JSON.parse(readFileSync(f("report.json"), "utf8")) };
+    return await read(f("out.pdf"), f("report.json"));
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
diff --git a/test/fixtures/fake-iris-pdf.mjs b/test/fixtures/fake-iris-pdf.mjs
index bc02045b..17f4aa2f 100755
--- a/test/fixtures/fake-iris-pdf.mjs
+++ b/test/fixtures/fake-iris-pdf.mjs
@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // Stands in for the `iris-pdf` command in test/tagged-pdf.test.ts. Same arguments, exit
 // codes and one-line errors, and no PDF work. Its "PDF" is JSON of what it was given.
-import { readFileSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 
 const [command, ...rest] = process.argv.slice(2);
@@ -22,7 +23,11 @@ if (a.help) {
 const pdf = readFileSync(a.pdf, "utf8");
 if (pdf.includes("ENCRYPTED")) fail("encrypted", "The PDF is encrypted.", 1);
 
-if (command === "fields") {
+// A "PDF" holding FLAT is a flat form: no fields, until tagging makes one from an <input>.
+if (command === "fields" && pdf.includes("FLAT")) {
+  const made = pdf.startsWith("%PDF-fake ") && JSON.parse(pdf.slice(10)).input.pages.some((p) => p.html.includes("<input"));
+  console.log(JSON.stringify(made ? [{ name: "full-name", type: "text", page: 1, options: [], required: false, readonly: false, maxlen: null, editable: false, multiSelect: false }] : []));
+} else if (command === "fields") {
   console.log(JSON.stringify([
     { name: "applicant.name", type: "text", page: 1, options: [], required: true, readonly: false, maxlen: 40, editable: false, multiSelect: false },
     { name: "applicant.consent", type: "checkbox", page: 1, options: ["Yes"], required: false, readonly: false, maxlen: null, editable: false, multiSelect: false },
@@ -31,6 +36,9 @@ if (command === "fields") {
       : []),
   ]));
 } else if (command === "tag") {
+  // So a test can tell whether a tag ran: one line per run, beside the source.
+  appendFileSync(join(dirname(a.pdf), "tag-runs.txt"), "tag\n");
+  if (pdf.includes("TAGFAIL")) fail("text_lost", "Page 1 lost text.", 2);
   const values = JSON.parse(readFileSync(a.values, "utf8"));
   if ("unknown.field" in values) fail("bad_value", "No field is named unknown.field.", 3);
   if ("crash" in values) fail("internal_error", `Cannot set ${values.crash}.`, 3);
diff --git a/test/tagged-pdf.test.ts b/test/tagged-pdf.test.ts
index df884f43..923cedff 100644
--- a/test/tagged-pdf.test.ts
+++ b/test/tagged-pdf.test.ts
@@ -32,7 +32,7 @@ function cfg(dir: string, command?: string, timeout_seconds?: number): IrisConfi
 }
 
 // A session made from one PDF, finished, with two extracted pages.
-async function serve(opts: { command?: string; source?: string | null; status?: string; timeout?: number } = {}) {
+async function serve(opts: { command?: string; source?: string | null; status?: string; timeout?: number; page1?: string } = {}) {
   const dir = mkdtempSync(join(tmpdir(), "iris-tagged-pdf-"));
   const config = cfg(dir, "command" in opts ? opts.command : FAKE, opts.timeout);
   const store = new Store(config.storage.database);
@@ -46,7 +46,7 @@ async function serve(opts: { command?: string; source?: string | null; status?:
   const frag = (order: number, innerHtml: string) => ({ image: `p${order}.png`, order, agent: "page.md", region: "page", innerHtml, edges: [], log: "" });
   // Stored out of order on purpose: the pages must reach the tagger by page order.
   // Page 3 failed extraction, so it holds only its note.
-  const pages = [frag(2, "<p>two</p>"), frag(3, "<!-- @page-failed 3: timeout -->"), frag(1, "<h1>one</h1>")];
+  const pages = [frag(2, "<p>two</p>"), frag(3, "<!-- @page-failed 3: timeout -->"), frag(1, opts.page1 ?? "<h1>one</h1>")];
   writeFileSync(paths.sessionFinalFragments(id), JSON.stringify({ fragments: pages, body: "" }));
   writeFileSync(paths.sessionOutput(id), '<!DOCTYPE html><html lang="fr"><head><title>x</title></head><body></body></html>');
 
@@ -66,6 +66,7 @@ async function serve(opts: { command?: string; source?: string | null; status?:
     paths,
     id,
     fields: () => fetch(`${base}/sessions/${id}/fields`),
+    tagRuns: () => (existsSync(join(paths.sessionDir(id), "tag-runs.txt")) ? readFileSync(join(paths.sessionDir(id), "tag-runs.txt"), "utf8").split("\n").length - 1 : 0),
     tag: (body: unknown) =>
       fetch(`${base}/sessions/${id}/pdf`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
     limits: () => fetch(`${base}/limits`),
@@ -169,6 +170,57 @@ test("GET /fields passes the PDF's fields through", async () => {
   }
 });
 
+test("a flat form lists the fields tagging makes from its HTML, and only then tags it", async () => {
+  const names = async (s: Awaited<ReturnType<typeof serve>>) => {
+    const res = await s.fields();
+    assert.equal(res.status, 200);
+    return ((await res.json()).fields as { name: string }[]).map((f) => f.name);
+  };
+  const form = '<h1>one</h1><label>Full name <input type="text"></label>';
+  const cases = [
+    { opts: { source: "%PDF FLAT", page1: form }, fields: ["full-name"], runs: 1 },
+    // No control in the HTML, or not extracted yet: nothing to make, so no tag runs.
+    { opts: { source: "%PDF FLAT" }, fields: [], runs: 0 },
+    { opts: { source: "%PDF FLAT", page1: form, status: "processing" }, fields: [], runs: 0 },
+    // The PDF has fields of its own: those, and no tag.
+    { opts: { page1: form }, fields: ["applicant.name", "applicant.consent"], runs: 0 },
+    // Tagging fails: no fields to offer, and the download will say why.
+    { opts: { source: "%PDF FLAT TAGFAIL", page1: form }, fields: [], runs: 1 },
+  ];
+  for (const [i, c] of cases.entries()) {
+    const s = await serve(c.opts);
+    try {
+      assert.deepEqual(await names(s), c.fields, `case ${i}`);
+      assert.equal(s.tagRuns(), c.runs, `case ${i}`);
+      assert.deepEqual((existsSync(s.paths.pdfScratchRoot()) ? readdirSync(s.paths.pdfScratchRoot()) : []).filter((n) => n.startsWith("pdf-")), [], `case ${i}: scratch removed`);
+      if (i === 0) {
+        // The download fills the created field by that name.
+        const res = await s.tag({ values: { "full-name": "Test Person" } });
+        assert.equal(res.status, 200);
+        const out = JSON.parse(Buffer.from((await res.json()).pdf, "base64").toString().slice(10));
+        assert.deepEqual(out.values, { "full-name": "Test Person" });
+      }
+    } finally {
+      s.close();
+    }
+  }
+});
+
+test("unreadable extracted pages: /fields lists none, /pdf answers 500", async () => {
+  const s = await serve({ source: "%PDF FLAT" });
+  try {
+    writeFileSync(s.paths.sessionFinalFragments(s.id), "{not json");
+    const res = await s.fields();
+    assert.equal(res.status, 200);
+    assert.deepEqual((await res.json()).fields, []);
+    const tagged = await s.tag({});
+    assert.equal(tagged.status, 500);
+    assert.equal((await tagged.json()).error.code, "tagger_failed");
+  } finally {
+    s.close();
+  }
+});
+
 test("a deployment without the command, or a session without a PDF, says so", async () => {
   const off = await serve({ command: undefined });
   try {
@@ -209,7 +261,7 @@ test("POST /pdf tags the pages in page order, leaves out a failed page, fills th
     // The values, and the filled PDF, are gone once the answer is sent.
     assert.equal(existsSync(made.scratch), false);
     assert.equal(dirname(made.scratch).startsWith(s.paths.pdfScratchRoot()), true);
-    assert.deepEqual(readdirSync(s.paths.pdfScratchRoot()).filter((f) => f.startsWith("pdf-")), []);
+    assert.deepEqual((existsSync(s.paths.pdfScratchRoot()) ? readdirSync(s.paths.pdfScratchRoot()) : []).filter((f) => f.startsWith("pdf-")), []);
     const log = readFileSync(s.paths.sessionLog(s.id), "utf8");
     assert.match(log, /"tagged_pdf"/);
     assert.match(log, /applicant\.name/, "the field names are logged");

From 5f2e6c3c9de66c98bbd15e78b7d0ed671faa8d07 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:36:11 -0400
Subject: [PATCH 2/4] fix(pdf): log, cache and label a flat form's created
 fields

Review notes on #517:
- GET /fields logs tagged_pdf_fields (ms, created) or
  tagged_pdf_fields_failed (ms, code), so a failed or empty attempt is visible.
- The created list is kept per session until the extracted pages' mtime
  changes. A failure is not kept.
- Created fields carry created: true. The demo labels them in words
  ("home-address-2" reads "Home address 2") and still sends the name.
- API.md names the iris-pdf it needs (#16) and documents both events.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/API.md                | 22 +++++++++++++----
 public/demo.html           |  8 ++++---
 src/routes/sessions.ts     | 48 ++++++++++++++++++++++++++++----------
 test/demo-pdf-form.test.ts | 15 +++++++++++-
 test/tagged-pdf.test.ts    | 18 +++++++++++++-
 5 files changed, 90 insertions(+), 21 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index 017bbc97..adbca242 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -987,8 +987,15 @@ curl -s -H "$AUTH" "$BASE/sessions/$SID/fields" | jq '.fields[0]'
 ```
 
 `type` is one of `text`, `checkbox`, `radio`, `combobox`, `listbox`, `button` or `signature`. A PDF with
-no form gives `{"fields": []}`, unless its HTML has form controls. Then tagging makes the fields, so this
-tags the PDF once and lists those, by the names `/pdf` fills. It can answer `404`, `409 no_source_pdf`, `422` for a PDF the tagger
+no form gives `{"fields": []}`.
+
+A flat form, such as a scan, has no fields until it is tagged. If its HTML has form controls, Iris
+tags it once and lists the fields it made, each with `"created": true`. `POST /pdf` fills them by
+those names. This needs iris-pdf with
+[equalify-iris-pdf#16](https://github.com/EqualifyEverything/equalify-iris-pdf/pull/16). An older
+one makes no fields, so the list is empty.
+
+It can answer `404`, `409 no_source_pdf`, `422` for a PDF the tagger
 refuses, or `503 busy`, the same as below.
 
 **Get the tagged PDF:**
@@ -1064,8 +1071,8 @@ The events worth grepping for have a section each below, and the index is a link
 the index when you have a `type` off a log line and want to know what it means; read a section when
 you want to know what the field it names is for and what it costs.
 
-**The index is the whole log.** `src/` emits **125** event types and every one of them has a section
-below — **117** sections, because a few cover two or three events that are only read together. So a
+**The index is the whole log.** `src/` emits **127** event types and every one of them has a section
+below — **118** sections, because a few cover two or three events that are only read together. So a
 `type` you cannot find here is not one the index skipped: it is a misread line, or a name `src/` no
 longer emits.
 
@@ -1192,6 +1199,7 @@ emits fails it too.
 | [`contribution_failed`](#contribution_failed) | The filing step threw, **after** `run_complete` |
 | [`run_failed`](#run_failed) | The run threw, so there is **no document** |
 | [`tagged_pdf` / `tagged_pdf_failed`](#tagged_pdf--tagged_pdf_failed) | A tagged PDF was made, or could not be |
+| [`tagged_pdf_fields` / `tagged_pdf_fields_failed`](#tagged_pdf_fields--tagged_pdf_fields_failed) | A flat form was tagged to list its fields, or could not be |
 | [`form_fields` / `page_fields` / `page_fields_missing`](#form_fields--page_fields--page_fields_missing) | The PDF's form field names were read, shown to a page, or not used |
 | [`calibrate_call_failed`](#calibrate_call_failed) | One calibration verifier call threw — a tool's line, never a run's |
 
@@ -4384,6 +4392,12 @@ A [tagged PDF](#get-a-tagged-pdf-optional) was made, or the tagger refused. `ms`
 never logged. `tagged_pdf_failed` has the tagger's `code` and `error`. An `internal_error`'s
 message is left out, because it may quote a value.
 
+### `tagged_pdf_fields` / `tagged_pdf_fields_failed`
+
+`GET /fields` tagged a flat form to list the fields it gets. `ms` is how long it took.
+`tagged_pdf_fields` has `created`, how many fields were made. `tagged_pdf_fields_failed` has the
+tagger's `code`. A list is reused until the extracted pages change, so this is written once per change.
+
 ### `form_fields` / `page_fields` / `page_fields_missing`
 
 With tagged PDFs on, the upload reads the PDF's form fields, and the page agent is asked to name
diff --git a/public/demo.html b/public/demo.html
index 37c128dd..8e405717 100644
--- a/public/demo.html
+++ b/public/demo.html
@@ -440,6 +440,8 @@ <h2 class="visually-hidden">About</h2>
     function renderFields(doc, list, fields) {
       const el = (tag, props = {}) => Object.assign(doc.createElement(tag), props);
       const req = (f) => (f.required ? ' (required on the form)' : '');
+      // A field Iris made for a flat form is named like `home-address-2`. Read it as words.
+      const label = (f) => (f.created ? f.name.replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase()) : f.name) + req(f);
       let n = 0;
       for (const f of fields) {
         if (f.readonly) continue;
@@ -447,7 +449,7 @@ <h2 class="visually-hidden">About</h2>
         let box;
         if (f.type === 'text' || (f.type === 'combobox' && f.editable)) {
           box = el('div');
-          box.append(el('label', { htmlFor: id, textContent: f.name + req(f) }));
+          box.append(el('label', { htmlFor: id, textContent: label(f) }));
           const input = el('input', { id, type: 'text' });
           if (f.maxlen) input.maxLength = f.maxlen;
           if (f.options.length) {
@@ -459,7 +461,7 @@ <h2 class="visually-hidden">About</h2>
           box.append(input);
         } else if (f.type === 'radio' || f.type === 'checkbox') {
           box = el('fieldset');
-          box.append(el('legend', { textContent: f.name + req(f) }));
+          box.append(el('legend', { textContent: label(f) }));
           // A chosen radio cannot be unchosen, so "leave it" is a choice of its own. A
           // checkbox is asked the same way: the page cannot show whether the PDF has it
           // checked, so an unticked box would not say "leave it" or "untick it".
@@ -474,7 +476,7 @@ <h2 class="visually-hidden">About</h2>
           });
         } else if (f.type === 'combobox' || f.type === 'listbox') {
           box = el('div');
-          box.append(el('label', { htmlFor: id, textContent: f.name + req(f) }));
+          box.append(el('label', { htmlFor: id, textContent: label(f) }));
           const select = el('select', { id, multiple: f.multiSelect });
           if (!f.multiSelect) select.append(el('option', { value: '', textContent: 'Leave as it is' }));
           for (const o of f.options) select.append(el('option', { value: o, textContent: o }));
diff --git a/src/routes/sessions.ts b/src/routes/sessions.ts
index 72e38c39..6c80c793 100644
--- a/src/routes/sessions.ts
+++ b/src/routes/sessions.ts
@@ -1,7 +1,7 @@
 import { Router } from "express";
 import type { Request, Response, NextFunction } from "express";
 import multer from "multer";
-import { writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { writeFileSync, readFileSync, existsSync, rmSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { ulid } from "ulid";
 import type { IrisConfig } from "../config.ts";
@@ -629,6 +629,10 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
     };
   }
 
+  // A flat form's created fields, per session. The tagger names them the same way on every
+  // run, so the list holds until the extracted pages change.
+  const createdCache = new Map<string, { mtimeMs: number; fields: (PdfField & { created: true })[] }>();
+
   // GET /v1/sessions/{id}/fields — the source PDF's form fields, for a fill-in form.
   r.get("/:id/fields", async (req: AuthedRequest, res) => {
     const src = sourcePdf(req, res);
@@ -636,20 +640,40 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
     if (tooBusy(res)) return;
     tagging++;
     try {
-      let fields = await readFields(src.command, src.pdf);
+      const fields: PdfField[] = await readFields(src.command, src.pdf);
       // A PDF with no fields, whose HTML has form controls: a flat form. Tagging gives it
-      // fields, so list those. If that fails, list none; the download says why.
+      // fields, so list those, marked `created`. If that fails, list none; the download
+      // says why.
       if (!fields.length && readyToTag(src.s)) {
-        fields = await (async () => {
+        const id = src.s.session_id;
+        const mtimeMs = statSync(paths.sessionFinalFragments(id)).mtimeMs;
+        const hit = createdCache.get(id);
+        if (hit?.mtimeMs === mtimeMs) {
+          res.json({ fields: hit.fields });
+          return;
+        }
+        const started = Date.now();
+        let created: (PdfField & { created: true })[] = [];
+        let code: string | undefined;
+        try {
           const { input } = tagInput(src.s);
-          if (!input.pages.some((p) => /<(input|select|textarea)\b/i.test(p.html))) return [];
-          return createdFields(src.command, {
-            pdfPath: src.pdf,
-            input,
-            scratchRoot: paths.pdfScratchRoot(),
-            timeoutSeconds: tagTimeoutSeconds(cfg),
-          });
-        })().catch(() => []);
+          if (input.pages.some((p) => /<(input|select|textarea)\b/i.test(p.html))) {
+            const made = await createdFields(src.command, {
+              pdfPath: src.pdf,
+              input,
+              scratchRoot: paths.pdfScratchRoot(),
+              timeoutSeconds: tagTimeoutSeconds(cfg),
+            });
+            created = made.map((f) => ({ ...f, created: true as const }));
+            new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields", { ms: Date.now() - started, created: created.length });
+          }
+          createdCache.set(id, { mtimeMs, fields: created });
+        } catch (e) {
+          code = e instanceof TaggedPdfError ? e.code : "tagger_failed";
+          new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields_failed", { ms: Date.now() - started, code });
+        }
+        res.json({ fields: created });
+        return;
       }
       res.json({ fields });
     } catch (e) {
diff --git a/test/demo-pdf-form.test.ts b/test/demo-pdf-form.test.ts
index 5153d005..8e7a79f4 100644
--- a/test/demo-pdf-form.test.ts
+++ b/test/demo-pdf-form.test.ts
@@ -26,7 +26,7 @@ function extract(name: string): string {
   throw new Error(`unbalanced braces reading ${name} from public/demo.html`);
 }
 
-type Field = { name: string; type: string; options: string[]; required?: boolean; readonly?: boolean; maxlen?: number | null; editable?: boolean; multiSelect?: boolean };
+type Field = { name: string; type: string; options: string[]; created?: boolean; required?: boolean; readonly?: boolean; maxlen?: number | null; editable?: boolean; multiSelect?: boolean };
 const renderFields = new Function(`${extract("renderFields")}; return renderFields;`)() as (doc: Document, list: Element, fields: Field[]) => number;
 const fieldValues = new Function(`${extract("fieldValues")}; return fieldValues;`)() as (list: Element) => Record<string, unknown>;
 const pdfNotes = new Function(`${extract("pdfNotes")}; return pdfNotes;`)() as (report: unknown) => string[];
@@ -63,6 +63,19 @@ test("every settable field gets one labelled control, and the rest get none", as
   assert.deepEqual(lint.violations, []);
 });
 
+test("a field made for a flat form is labelled in words, and sent under its own name", () => {
+  const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
+  const list = doc.getElementById("f")!;
+  renderFields(doc, list, [
+    { name: "home-address-2", type: "text", options: [], created: true },
+    { name: "pay_by", type: "radio", options: ["Cash", "Card"], created: true },
+    { name: "applicant.name-x", type: "text", options: [] },
+  ] as Field[]);
+  assert.deepEqual([...list.querySelectorAll("label, legend")].map((l) => l.textContent).filter((t) => !["Leave as it is", "Cash", "Card"].includes(t!)), ["Home address 2", "Pay by", "applicant.name-x"]);
+  (list.querySelector('[data-field="home-address-2"] input') as HTMLInputElement).value = "x";
+  assert.deepEqual(fieldValues(list), { "home-address-2": "x" });
+});
+
 test("an untouched form sends nothing, so the PDF keeps what it had", () => {
   assert.deepEqual(fieldValues(form().list), {});
 });
diff --git a/test/tagged-pdf.test.ts b/test/tagged-pdf.test.ts
index 923cedff..8bd7f0a9 100644
--- a/test/tagged-pdf.test.ts
+++ b/test/tagged-pdf.test.ts
@@ -4,7 +4,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import express from "express";
 import type { AddressInfo } from "node:net";
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -194,12 +194,28 @@ test("a flat form lists the fields tagging makes from its HTML, and only then ta
       assert.equal(s.tagRuns(), c.runs, `case ${i}`);
       assert.deepEqual((existsSync(s.paths.pdfScratchRoot()) ? readdirSync(s.paths.pdfScratchRoot()) : []).filter((n) => n.startsWith("pdf-")), [], `case ${i}: scratch removed`);
       if (i === 0) {
+        const log = () => readFileSync(s.paths.sessionLog(s.id), "utf8").trim().split("\n").map((l) => JSON.parse(l));
+        assert.deepEqual(log().map((e) => [e.type, e.created]), [["tagged_pdf_fields", 1]]);
+        const listed = (await (await s.fields()).json()).fields;
+        assert.equal(listed[0].created, true, "a created field is marked");
+        assert.equal(s.tagRuns(), 1, "asked again: the list is reused, not re-tagged");
+        // New extracted pages: tagged again.
+        const later = new Date(Date.now() + 5000);
+        utimesSync(s.paths.sessionFinalFragments(s.id), later, later);
+        await names(s);
+        assert.equal(s.tagRuns(), 2, "the pages changed: tagged again");
         // The download fills the created field by that name.
         const res = await s.tag({ values: { "full-name": "Test Person" } });
         assert.equal(res.status, 200);
         const out = JSON.parse(Buffer.from((await res.json()).pdf, "base64").toString().slice(10));
         assert.deepEqual(out.values, { "full-name": "Test Person" });
       }
+      if (i === 4) {
+        const events = readFileSync(s.paths.sessionLog(s.id), "utf8").trim().split("\n").map((l) => JSON.parse(l));
+        assert.deepEqual(events.map((e) => [e.type, e.code]), [["tagged_pdf_fields_failed", "text_lost"]]);
+        await names(s);
+        assert.equal(s.tagRuns(), 2, "a failure is not kept, so it is tried again");
+      }
     } finally {
       s.close();
     }

From 6749ecb9fe11db08e1dd4d6e53b0464477f81416 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:50:52 -0400
Subject: [PATCH 3/4] fix(pdf): keep a failed flat-form tag a minute, share one
 in flight, cap the cache

Review notes on #517 round 2:
- A failure is kept for a minute, so a failing form cannot hold the
  tagger's two slots. Two asks at once share one tag.
- The cache keeps the newest 200 sessions (remember()).
- API.md says how often each event is written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/API.md             |  3 +-
 src/routes/sessions.ts  | 71 +++++++++++++++++++++++++----------------
 test/tagged-pdf.test.ts | 35 ++++++++++++++++++--
 3 files changed, 78 insertions(+), 31 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index adbca242..33ef35e1 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -4396,7 +4396,8 @@ message is left out, because it may quote a value.
 
 `GET /fields` tagged a flat form to list the fields it gets. `ms` is how long it took.
 `tagged_pdf_fields` has `created`, how many fields were made. `tagged_pdf_fields_failed` has the
-tagger's `code`. A list is reused until the extracted pages change, so this is written once per change.
+tagger's `code`. A made list is reused until the extracted pages change. A failure is reused for a
+minute, so a failing form writes about one line a minute while it is asked.
 
 ### `form_fields` / `page_fields` / `page_fields_missing`
 
diff --git a/src/routes/sessions.ts b/src/routes/sessions.ts
index 6c80c793..d11c74a8 100644
--- a/src/routes/sessions.ts
+++ b/src/routes/sessions.ts
@@ -145,6 +145,13 @@ function ownedSession(store: Store, id: string, userId: number): SessionRecord |
   return s;
 }
 
+// Set `key` as the newest entry, and drop the oldest past `max`. A Map keeps insertion order.
+export function remember<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+  map.delete(key);
+  map.set(key, value);
+  while (map.size > max) map.delete(map.keys().next().value!);
+}
+
 // Keep the upload for a tagged PDF later, when this deployment makes them and the upload
 // was one PDF on its own. Then the PDF's page N is the session's page N.
 export function keepSourcePdf(
@@ -630,8 +637,34 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
   }
 
   // A flat form's created fields, per session. The tagger names them the same way on every
-  // run, so the list holds until the extracted pages change.
-  const createdCache = new Map<string, { mtimeMs: number; fields: (PdfField & { created: true })[] }>();
+  // run, so a list holds until the extracted pages change. A failure (null) holds a minute,
+  // so a failing form cannot keep the tagger busy. A run in progress is shared. The oldest
+  // of more than 200 sessions is dropped.
+  type Created = (PdfField & { created: true })[];
+  const createdCache = new Map<string, { mtimeMs: number; until: number; fields: Promise<Created | null> }>();
+  const FAILURE_KEPT_MS = 60_000;
+  const CACHED_SESSIONS = 200;
+
+  async function makeFields(src: { s: SessionRecord; command: string; pdf: string }): Promise<Created | null> {
+    const id = src.s.session_id;
+    const started = Date.now();
+    try {
+      const { input } = tagInput(src.s);
+      if (!input.pages.some((p) => /<(input|select|textarea)\b/i.test(p.html))) return [];
+      const made = await createdFields(src.command, {
+        pdfPath: src.pdf,
+        input,
+        scratchRoot: paths.pdfScratchRoot(),
+        timeoutSeconds: tagTimeoutSeconds(cfg),
+      });
+      new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields", { ms: Date.now() - started, created: made.length });
+      return made.map((f) => ({ ...f, created: true as const }));
+    } catch (e) {
+      const code = e instanceof TaggedPdfError ? e.code : "tagger_failed";
+      new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields_failed", { ms: Date.now() - started, code });
+      return null;
+    }
+  }
 
   // GET /v1/sessions/{id}/fields — the source PDF's form fields, for a fill-in form.
   r.get("/:id/fields", async (req: AuthedRequest, res) => {
@@ -647,32 +680,16 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
       if (!fields.length && readyToTag(src.s)) {
         const id = src.s.session_id;
         const mtimeMs = statSync(paths.sessionFinalFragments(id)).mtimeMs;
-        const hit = createdCache.get(id);
-        if (hit?.mtimeMs === mtimeMs) {
-          res.json({ fields: hit.fields });
-          return;
-        }
-        const started = Date.now();
-        let created: (PdfField & { created: true })[] = [];
-        let code: string | undefined;
-        try {
-          const { input } = tagInput(src.s);
-          if (input.pages.some((p) => /<(input|select|textarea)\b/i.test(p.html))) {
-            const made = await createdFields(src.command, {
-              pdfPath: src.pdf,
-              input,
-              scratchRoot: paths.pdfScratchRoot(),
-              timeoutSeconds: tagTimeoutSeconds(cfg),
-            });
-            created = made.map((f) => ({ ...f, created: true as const }));
-            new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields", { ms: Date.now() - started, created: created.length });
-          }
-          createdCache.set(id, { mtimeMs, fields: created });
-        } catch (e) {
-          code = e instanceof TaggedPdfError ? e.code : "tagger_failed";
-          new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields_failed", { ms: Date.now() - started, code });
+        let hit = createdCache.get(id);
+        if (!hit || hit.mtimeMs !== mtimeMs || Date.now() >= hit.until) {
+          const entry = { mtimeMs, until: Infinity, fields: makeFields(src) };
+          remember(createdCache, id, entry, CACHED_SESSIONS);
+          void entry.fields.then((f) => {
+            if (f === null) entry.until = Date.now() + FAILURE_KEPT_MS;
+          });
+          hit = entry;
         }
-        res.json({ fields: created });
+        res.json({ fields: (await hit.fields) ?? [] });
         return;
       }
       res.json({ fields });
diff --git a/test/tagged-pdf.test.ts b/test/tagged-pdf.test.ts
index 8bd7f0a9..78dad04f 100644
--- a/test/tagged-pdf.test.ts
+++ b/test/tagged-pdf.test.ts
@@ -1,6 +1,6 @@
 // The optional tagged-PDF output (src/util/taggedPdf.ts). `iris-pdf` is a separate
 // project, so these tests run a stand-in for it (test/fixtures/fake-iris-pdf.mjs).
-import { test } from "node:test";
+import { mock, test } from "node:test";
 import assert from "node:assert/strict";
 import express from "express";
 import type { AddressInfo } from "node:net";
@@ -10,7 +10,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { IrisConfig } from "../src/config.ts";
 import type { AuthedRequest } from "../src/auth/middleware.ts";
-import { keepPdfFields, keepSourcePdf, sessionsRouter } from "../src/routes/sessions.ts";
+import { keepPdfFields, keepSourcePdf, remember, sessionsRouter } from "../src/routes/sessions.ts";
 import { enumerateInputs } from "../src/pipeline/orchestrator.ts";
 import { limitsRouter } from "../src/routes/limits.ts";
 import { Store } from "../src/store/db.ts";
@@ -214,7 +214,14 @@ test("a flat form lists the fields tagging makes from its HTML, and only then ta
         const events = readFileSync(s.paths.sessionLog(s.id), "utf8").trim().split("\n").map((l) => JSON.parse(l));
         assert.deepEqual(events.map((e) => [e.type, e.code]), [["tagged_pdf_fields_failed", "text_lost"]]);
         await names(s);
-        assert.equal(s.tagRuns(), 2, "a failure is not kept, so it is tried again");
+        assert.equal(s.tagRuns(), 1, "a failure is kept for a minute");
+        mock.timers.enable({ apis: ["Date"], now: Date.now() + 61_000 });
+        try {
+          await names(s);
+        } finally {
+          mock.timers.reset();
+        }
+        assert.equal(s.tagRuns(), 2, "then tried again");
       }
     } finally {
       s.close();
@@ -222,6 +229,28 @@ test("a flat form lists the fields tagging makes from its HTML, and only then ta
   }
 });
 
+test("two asks at once for a flat form's fields share one tag", async () => {
+  const s = await serve({ source: "%PDF FLAT", page1: '<label>Full name <input type="text"></label>' });
+  try {
+    const both = await Promise.all([s.fields(), s.fields()]);
+    for (const res of both) assert.deepEqual(((await res.json()).fields as { name: string }[]).map((f) => f.name), ["full-name"]);
+    assert.equal(s.tagRuns(), 1);
+  } finally {
+    s.close();
+  }
+});
+
+test("the created-fields cache keeps the newest 200 sessions", () => {
+  const m = new Map<string, number>();
+  for (const k of ["a", "b", "c"]) remember(m, k, 1, 2);
+  assert.deepEqual([...m.keys()], ["b", "c"]);
+  remember(m, "b", 2, 2);
+  assert.deepEqual([...m.entries()], [["c", 1], ["b", 2]], "a set key becomes the newest");
+  const route = readFileSync(join(dirname(FAKE), "..", "..", "src", "routes", "sessions.ts"), "utf8");
+  assert.match(route, /const CACHED_SESSIONS = 200;/);
+  assert.match(route, /remember\(createdCache, id, entry, CACHED_SESSIONS\);/);
+});
+
 test("unreadable extracted pages: /fields lists none, /pdf answers 500", async () => {
   const s = await serve({ source: "%PDF FLAT" });
   try {

From b31cdace02952f6957a01e6137092211dd1754b4 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Tue, 6 Oct 2026 19:07:10 -0400
Subject: [PATCH 4/4] fix(pdf): an unwritable log keeps a flat form's created
 fields

Round 3 notes on #517:
- A log write that throws no longer discards the list just made, so
  makeFields cannot reject.
- The retry after a kept failure expires is now tested with two asks at
  once; they share one tag.
- docs/API.md: the minute counts from when the failure ends.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/API.md             |  2 +-
 src/routes/sessions.ts  | 12 ++++++++++--
 test/tagged-pdf.test.ts | 17 +++++++++++++++--
 3 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index 33ef35e1..62c8e601 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -4397,7 +4397,7 @@ message is left out, because it may quote a value.
 `GET /fields` tagged a flat form to list the fields it gets. `ms` is how long it took.
 `tagged_pdf_fields` has `created`, how many fields were made. `tagged_pdf_fields_failed` has the
 tagger's `code`. A made list is reused until the extracted pages change. A failure is reused for a
-minute, so a failing form writes about one line a minute while it is asked.
+minute after it ends, so a failing form writes at most one line a minute while it is asked.
 
 ### `form_fields` / `page_fields` / `page_fields_missing`
 
diff --git a/src/routes/sessions.ts b/src/routes/sessions.ts
index d11c74a8..d767508a 100644
--- a/src/routes/sessions.ts
+++ b/src/routes/sessions.ts
@@ -648,6 +648,14 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
   async function makeFields(src: { s: SessionRecord; command: string; pdf: string }): Promise<Created | null> {
     const id = src.s.session_id;
     const started = Date.now();
+    // An unwritable log must not cost the list it describes.
+    const note = (write: (log: RunLog) => void) => {
+      try {
+        write(new RunLog(paths.sessionLog(id)));
+      } catch {
+        // the list is the answer; its log line is not
+      }
+    };
     try {
       const { input } = tagInput(src.s);
       if (!input.pages.some((p) => /<(input|select|textarea)\b/i.test(p.html))) return [];
@@ -657,11 +665,11 @@ export function sessionsRouter(cfg: IrisConfig, store: Store): Router {
         scratchRoot: paths.pdfScratchRoot(),
         timeoutSeconds: tagTimeoutSeconds(cfg),
       });
-      new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields", { ms: Date.now() - started, created: made.length });
+      note((log) => log.event("tagged_pdf_fields", { ms: Date.now() - started, created: made.length }));
       return made.map((f) => ({ ...f, created: true as const }));
     } catch (e) {
       const code = e instanceof TaggedPdfError ? e.code : "tagger_failed";
-      new RunLog(paths.sessionLog(id)).event("tagged_pdf_fields_failed", { ms: Date.now() - started, code });
+      note((log) => log.event("tagged_pdf_fields_failed", { ms: Date.now() - started, code }));
       return null;
     }
   }
diff --git a/test/tagged-pdf.test.ts b/test/tagged-pdf.test.ts
index 78dad04f..dc4d3ce3 100644
--- a/test/tagged-pdf.test.ts
+++ b/test/tagged-pdf.test.ts
@@ -217,11 +217,11 @@ test("a flat form lists the fields tagging makes from its HTML, and only then ta
         assert.equal(s.tagRuns(), 1, "a failure is kept for a minute");
         mock.timers.enable({ apis: ["Date"], now: Date.now() + 61_000 });
         try {
-          await names(s);
+          await Promise.all([names(s), names(s)]);
         } finally {
           mock.timers.reset();
         }
-        assert.equal(s.tagRuns(), 2, "then tried again");
+        assert.equal(s.tagRuns(), 2, "then tried again, once for both asks");
       }
     } finally {
       s.close();
@@ -251,6 +251,19 @@ test("the created-fields cache keeps the newest 200 sessions", () => {
   assert.match(route, /remember\(createdCache, id, entry, CACHED_SESSIONS\);/);
 });
 
+test("a session log that cannot be written does not cost the created fields", async () => {
+  const s = await serve({ source: "%PDF FLAT", page1: '<label>Full name <input type="text"></label>' });
+  try {
+    rmSync(s.paths.sessionLog(s.id), { force: true });
+    mkdirSync(s.paths.sessionLog(s.id)); // appending to a directory throws
+    const res = await s.fields();
+    assert.equal(res.status, 200);
+    assert.deepEqual(((await res.json()).fields as { name: string }[]).map((f) => f.name), ["full-name"]);
+  } finally {
+    s.close();
+  }
+});
+
 test("unreadable extracted pages: /fields lists none, /pdf answers 500", async () => {
   const s = await serve({ source: "%PDF FLAT" });
   try {