bantamkit-mcp 0.29.1 → 0.30.0

package/dist/docread.js

@@ -40,6 +40,7 @@ import { BantamError } from './errors.js';
 import { CODEC_ALIASES, CODEC_MODULES, MULTI_BYTE_SINGLES, SINGLE_BYTE_TABLES } from './charsets.js';
 import { HTML5_ENTITIES } from './htmlentities.js';
 import { PyOSError, pyJoin, pyName, pySuffix as pyPathSuffix } from './memory/pyfs.js';
+import { cmpCodepoint, PY_WS_CLASS, pyRepr, pyStrip } from './pysem.js';
 export const NS_S = '{http://schemas.openxmlformats.org/spreadsheetml/2006/main}';
 export const NS_W = '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}';
 export const NS_R = '{http://schemas.openxmlformats.org/officeDocument/2006/relationships}';
@@ -58,27 +59,50 @@ export const OMIT_NUMBER_FORMAT = 'number-format';
 export const OMIT_UNREAD_PAGE = 'unread-page';
 export const OMIT_UNMAPPED = 'unmapped-text';
 export const OMIT_UNREAD_TAIL = 'unread-tail';
+// What a ceiling THIS READER imposes kept out of the rows. Not a property of the file, which
+// is exactly why it is declared as a count instead of applied in silence. Three ceilings carry
+// it here, and each one names its own number in `what`: bytes past `TEXT_MAX_BYTES` for a
+// plain-text file and for the markup of an `.html`/`.mhtml` (the same constant, because "how
+// much of a file this reader reads" is one number and not one per container), and rows past
+// `XLSX_MAX_TEXT_BYTES` for a workbook, where the thing that runs away is the RENDERING rather
+// than the file. The reference has a FOURTH — `textutil`'s output for a `.doc` or an `.rtf` —
+// which this side cannot have and does not owe, because it does not read those two kinds at
+// all (docs/porting.md, "pdf, doc and rtf on Node").
+//
+// The principle overclaimed until review round 5 (H3), and the correction is worth stating
+// because the sentence is what stopped anyone looking: `.docx` had no ceiling of any kind, and
+// on the reference `.doc` and `.rtf` had none either. MEASURED here 2026-09-06 before the
+// member ceiling existed: a 41,254-byte `.docx` rendered 40,000,099 bytes of text in 306 ms —
+// 2.38x `TEXT_MAX_BYTES` — with `doc.omissions` and `part.omissions` both empty.
+//
+// `ZIP_MEMBER_MAX_BYTES` is deliberately NOT one of these, and that is the honest amendment
+// rather than a fifth token: it refuses instead of disclosing, because half an XML member is
+// not a smaller XML member. So an OOXML container is bounded by what this reader will PARSE
+// and says so by refusing; every other container is bounded by what it will READ and says so
+// by counting. `.docx` needs no rendering budget on top of that: the text a `<w:t>` walk
+// produces can never exceed the bytes of the part it walked.
 export const OMIT_SIZE_CAP = 'size-cap';
 // A worksheet cell whose own `r` reference could not place it: not letters-then-digits, or a
 // column past the last one the format has. The cell's TEXT is in the rows, at its XML
 // position; what the rows do not carry is the column the file asked for. Counted per reason,
 // with the columns it landed in, exactly as `number-format` is counted per format code.
 export const OMIT_UNPLACED_CELL = 'unplaced-cell';
+// A worksheet cell a LATER cell in the same row and column replaced. Last-wins is what both
+// runtimes do and what a writer's own second cell means, so the reading is kept; what was not
+// kept was the disclosure. Counted with the columns it happened in, like every other cell this
+// reader could not put in the rows.
+export const OMIT_DUPLICATE_CELL = 'duplicate-cell';
 /** Extraction failed. The message names what was seen, never just the format's own error. */
 export class DocumentReadError extends BantamError {
 }
 // ------------------------------------------------------------------ Python string semantics
-/** The characters `str.isspace()` is true for — what `strip()` and `split()` consume. */
-const PY_WS = '\t\n\x0b\x0c\r\x1c\x1d\x1e\x1f \x85\xa0            

  　';
-const PY_WS_CLASS = `[${PY_WS.replace(/[\]\\^-]/g, '\\$&')}]`;
+// The whitespace class, `str.strip()`, `sorted()`'s order and `repr(str)` are `pysem.ts`'s
+// (entry (n)): \x85\xa0            

  　';they were ported here AND under `memory/`, and the pairs were diffed before
+// they were merged. The names stay exported from here, so nothing that imports them moves.
 const PY_WS_RUN = new RegExp(`${PY_WS_CLASS}+`, 'g');
-const PY_STRIP = new RegExp(`^${PY_WS_CLASS}+|${PY_WS_CLASS}+$`, 'g');
 const PY_LSTRIP = new RegExp(`^${PY_WS_CLASS}+`);
 const PY_RSTRIP = new RegExp(`${PY_WS_CLASS}+$`);
-/** `str.strip()` with no argument. */
-export function pyStrip(s) {
-    return s.replace(PY_STRIP, '');
-}
+export { cmpCodepoint, pyRepr, pyStrip };
 function pyRstrip(s) {
     return s.replace(PY_RSTRIP, '');
 }
@@ -182,60 +206,12 @@ function pyIndex(list, index) {
     const i = index < 0 ? list.length + index : index;
     return i >= 0 && i < list.length ? list[i] : undefined;
 }
-/** `sorted()` on strings: by code point, which is not what `Array.sort` does above U+FFFF. */
-export function cmpCodepoint(a, b) {
-    const ia = a[Symbol.iterator]();
-    const ib = b[Symbol.iterator]();
-    for (;;) {
-        const x = ia.next();
-        const y = ib.next();
-        if (x.done && y.done)
-            return 0;
-        if (x.done)
-            return -1;
-        if (y.done)
-            return 1;
-        const cx = x.value.codePointAt(0);
-        const cy = y.value.codePointAt(0);
-        if (cx !== cy)
-            return cx - cy;
-    }
-}
 function pySorted(items) {
     return [...items].sort(cmpCodepoint);
 }
-// `str.isprintable()` is false for these categories (space itself excepted).
-const NONPRINTABLE = /[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/u;
 function quoteFor(s) {
     return s.includes("'") && !s.includes('"') ? '"' : "'";
 }
-/** `repr(str)`. */
-export function pyRepr(s) {
-    const quote = quoteFor(s);
-    let out = quote;
-    for (const ch of s) {
-        const code = ch.codePointAt(0);
-        if (ch === quote || ch === '\\')
-            out += '\\' + ch;
-        else if (ch === '\t')
-            out += '\\t';
-        else if (ch === '\n')
-            out += '\\n';
-        else if (ch === '\r')
-            out += '\\r';
-        else if (ch !== ' ' && NONPRINTABLE.test(ch)) {
-            if (code < 0x100)
-                out += '\\x' + code.toString(16).padStart(2, '0');
-            else if (code < 0x10000)
-                out += '\\u' + code.toString(16).padStart(4, '0');
-            else
-                out += '\\U' + code.toString(16).padStart(8, '0');
-        }
-        else
-            out += ch;
-    }
-    return out + quote;
-}
 /** `repr(bytes)`. */
 export function bytesRepr(buf) {
     const text = Buffer.from(buf).toString('latin1');
@@ -841,12 +817,21 @@ function startsWith(head, magic) {
             return false;
     return true;
 }
+/**
+ * What a `PK`-headed file IS, **and the reader it took to find out** (entries (a)/(j)).
+ *
+ * The reader is handed back rather than dropped because `extract` needs the same bytes one
+ * call later: before this, `sniff` read the whole archive off disk to list its members and the
+ * extractor read it again, two whole-file `readFileSync` per `extract`. `null` for a zip this
+ * could not open — the kinds that answer `null` are the ones no extractor is reached for.
+ */
 function zipKind(path, head) {
     const named = pyPathSuffix(path).toLowerCase().replace(/^\.+/, '');
     let names;
     let mimetype = '';
+    let zf;
     try {
-        const zf = ZipReader.open(path);
+        zf = ZipReader.open(path);
         names = zf.namelist();
         // `readMember`, not `zf.read`: an encrypted `mimetype` is the encrypted sentence naming
         // that member, never "damaged" (review round 3 measured the latter on an .odt), and a
@@ -856,20 +841,23 @@ function zipKind(path, head) {
     }
     catch (err) {
         if (err instanceof BadZipFile || isOsError(err)) {
-            return new Container('zip', `a truncated or damaged zip archive (it starts with ${bytesRepr(head.subarray(0, 8))})`, named);
+            return [
+                new Container('zip', `a truncated or damaged zip archive (it starts with ${bytesRepr(head.subarray(0, 8))})`, named),
+                null,
+            ];
         }
         throw err;
     }
     const members = new Set(names);
     for (const [member, kind] of ZIP_MEMBERS) {
         if (members.has(member))
-            return new Container(kind, `an OOXML package holding ${member}`, named);
+            return [new Container(kind, `an OOXML package holding ${member}`, named), zf];
     }
     if (mimetype.startsWith('application/vnd.oasis.opendocument')) {
-        return new Container('odf', `an OpenDocument package (${mimetype})`, named);
+        return [new Container('odf', `an OpenDocument package (${mimetype})`, named), zf];
     }
     const sample = pySorted(members).slice(0, 5).join(', ') || '(empty archive)';
-    return new Container('zip', `a zip archive that is no OOXML package; it holds: ${sample}`, named);
+    return [new Container('zip', `a zip archive that is no OOXML package; it holds: ${sample}`, named), zf];
 }
 /** `dict.get(key)`: own keys only, so `constructor` is not a hit. */
 function lookup(rec, key) {
@@ -984,6 +972,22 @@ function readPrefix(path, n) {
 }
 /** What `path` IS. Magic bytes, then a zip's member list. The suffix is never consulted. */
 export function sniff(path) {
+    return sniffOpen(path)[0];
+}
+/**
+ * `sniff`, plus the `ZipReader` it had to open — the one caller that can reuse it is `extract`.
+ *
+ * Entries (a)/(j): deciding a `PK`-headed file is an OOXML package means reading the archive,
+ * and the extractor then read it again, so ONE `extract` of a `.xlsx` cost two whole-file
+ * `readFileSync` (MEASURED at 2 before this change, 1 after, by wrapping `node:fs` in a child
+ * process). Public `sniff` still drops the reader, which is what it always did.
+ *
+ * The reader is a RETURN VALUE and never module state: its lifetime is the caller's, so it
+ * cannot answer for a file that has changed on disk since. The single-entry document cache one
+ * layer up is the thing that is allowed to remember, and it is keyed on (realpath, size,
+ * mtime_ns) for exactly that reason.
+ */
+function sniffOpen(path) {
     const st = statPath(path);
     if (st.isDir)
         throw new DocumentReadError(`${pyPathStr(path)} is a directory, not a document`);
@@ -992,26 +996,32 @@ export function sniff(path) {
     const named = pyPathSuffix(path).toLowerCase().replace(/^\.+/, '');
     const head = readPrefix(path, HEAD_BYTES);
     if (head.length === 0)
-        return new Container('empty', 'an empty file (0 bytes)', named);
+        return [new Container('empty', 'an empty file (0 bytes)', named), null];
     if (head[0] === 0x50 && head[1] === 0x4b)
         return zipKind(path, head);
     for (const [magic, kind] of MAGIC) {
         if (startsWith(head, magic)) {
             if (kind === 'pdf') {
                 const version = pyStrip(head.subarray(1, 8).toString('latin1'));
-                return new Container('pdf', `a PDF document (${version})`, named);
+                return [new Container('pdf', `a PDF document (${version})`, named), null];
             }
-            return new Container(kind, lookup(WHAT, kind) ?? `a ${kind} file`, named);
+            return [new Container(kind, lookup(WHAT, kind) ?? `a ${kind} file`, named), null];
         }
     }
     if (head.subarray(4, 8).toString('latin1') === 'ftyp') {
         const brand = pyStrip(head.subarray(8, 12).toString('latin1')) || '?';
-        return new Container('isobmff', `an ISO base-media container, brand ${pyRepr(brand)} (video/audio)`, named);
+        return [
+            new Container('isobmff', `an ISO base-media container, brand ${pyRepr(brand)} (video/audio)`, named),
+            null,
+        ];
     }
     const guessed = textKind(head, named);
     if (guessed !== null)
-        return guessed;
-    return new Container('unknown', `not a recognised container; it starts with ${bytesRepr(head.subarray(0, 12))}`, named);
+        return [guessed, null];
+    return [
+        new Container('unknown', `not a recognised container; it starts with ${bytesRepr(head.subarray(0, 12))}`, named),
+        null,
+    ];
 }
 /** The one refusal sentence, and it names the CONTENT before it names anything else. */
 function refuse(path, container, remedy) {
@@ -1061,6 +1071,35 @@ function decodeZipName(raw, flags) {
         out += b < 0x80 ? String.fromCharCode(b) : CP437_HIGH[b - 0x80];
     return out;
 }
+/**
+ * How much ONE MEMBER of a zip this reader will decompress and parse. The ceiling on the
+ * PARSE, which is a different door from `XLSX_MAX_TEXT_BYTES`: that one bounds the text a
+ * workbook renders, and it never stands in front of this, because `readMember` decompresses
+ * the member whole and `parsePart` builds a tree from it before the first row is rendered.
+ *
+ * MEASURED 2026-09-06 on this machine, through `docread.extract` on THIS runtime at the
+ * shipped constants, on a sheet of N `<row><c t="inlineStr"><is><t>x</t></is></c></row>`
+ * deflated by `deflateRawSync`, peak RSS from `process.resourceUsage().maxRSS`:
+ * 400,000 rows are 58,378 bytes on disk, declare 19,600,112, and took RSS from 102.2 MB to
+ * 1,039.3 MB in 1,019 ms with NO omission; 1,000,000 rows are 143,939 bytes, declare
+ * 49,000,112, and took it from 158.6 MB to 2,290.8 MB in 2,667 ms. Linear and unbounded —
+ * the memory is the `XmlElement` tree, not the text, so a budget over the rendering could
+ * not see it. The reference measured the same shape at 342.2 MB and 838.8 MB through
+ * `tracemalloc`; the numbers are not comparable (one counts a Python allocator, the other a
+ * whole process) and the SHAPE is what both of them state.
+ *
+ * 16 MiB, the number `TEXT_MAX_BYTES` states, because "how much of a file this reader reads"
+ * is one number — but under its OWN NAME, because it bounds a member of a container and not a
+ * file on a disk, and a bar that varies one must not be varying the other. The reference
+ * measured the corpus behind the figure: 25 OOXML/ODF packages under the goal's roots, the
+ * largest single XML member among them 4,283,286 bytes, 3.9x under this.
+ *
+ * A REFUSAL and not a truncation, which is the one place this module departs from
+ * "disclose, never truncate": half an XML document is not a smaller XML document, and a tree
+ * built from a severed member would carry text that is not what the file says. So the reader
+ * stops and names the member, the number the file declares and its own ceiling.
+ */
+export const ZIP_MEMBER_MAX_BYTES = 16 * 1024 * 1024;
 /** `zipfile.ZipFile` read-only: the central directory, and `read(name)` with a CRC check. */
 export class ZipReader {
     data;
@@ -1175,6 +1214,13 @@ export class ZipReader {
     has(name) {
         return this.byName.has(name);
     }
+    /** `getinfo(name).file_size`: what the central directory DECLARES, before any inflate. */
+    declaredSize(name) {
+        const entry = this.byName.get(name);
+        if (entry === undefined)
+            throw new RangeError(`There is no item named ${pyRepr(name)} in the archive`);
+        return entry.fileSize;
+    }
     /** `ZipFile.read(name)`; a missing member is a `KeyError` — here `RangeError`, see `readMember`. */
     read(name) {
         const entry = this.byName.get(name);
@@ -1203,10 +1249,25 @@ export class ZipReader {
         const start = at + 30 + nameLen + extraLen;
         const raw = data.subarray(start, start + entry.compressedSize);
         let out;
+        // THE CLAMP THE REFERENCE GETS FOR FREE, review round 5 (H1). `zipfile.ZipExtFile` stops
+        // at `ZipInfo.file_size` and CRCs what it produced, so on the reference a member that
+        // declares 10 bytes and holds 100,000 yields 10 bytes and `Bad CRC-32`. That is CPython's
+        // and not the format's, and this reader is hand-written: MEASURED before this line
+        // existed, a forged central directory declaring 10 bytes over a 19,600,112-byte deflate
+        // stream inflated all 19,600,112, passed the CRC (which covers the real content), and
+        // `extract` rendered 400,000 rows. So `readMember`'s ceiling on the DECLARED size was
+        // walked past by one 4-byte edit, and the property it exists for held on the reference
+        // and not here.
+        //
+        // `maxOutputLength` is the same clamp with a hard stop instead of a truncation: nothing
+        // past `file_size` is ever allocated. A member that overruns its declaration is what
+        // `ZipExtFile` would have handed to the CRC check as a short prefix, and a prefix of a
+        // longer stream is not what the checksum covers, so the refusal is that check's own
+        // sentence rather than a new one — the same words the reference prints for the same file.
         if (entry.method === 0)
-            out = Buffer.from(raw);
+            out = Buffer.from(raw.subarray(0, entry.fileSize));
         else if (entry.method === 8)
-            out = inflateRaw(raw);
+            out = entry.fileSize === 0 ? Buffer.alloc(0) : inflateRaw(raw, entry.fileSize, name);
         else if (entry.method === 12 || entry.method === 14) {
             // DELIBERATE DIVERGENCE (docs/porting.md, "bzip2 and lzma zip members on Node"): the
             // reference's `zipfile` decompresses methods 12 and 14 through the stdlib `bz2` and
@@ -1276,22 +1337,41 @@ export class ZipMemberUnreadable extends Error {
  * stream that merely ENDS early is not an error to `decompressobj` — it hands back what it
  * has, and `ZipExtFile` then fails the CRC — so `Z_BUF_ERROR` is retried with a sync flush
  * for the same partial bytes, and the CRC check in `read` refuses them the way it does there.
+ *
+ * `limit` is `ZipInfo.file_size` and it is `ZipExtFile`'s `_left`, not a budget of this
+ * reader's own: nothing past what the archive DECLARES the member holds is allocated, so an
+ * overrun costs the limit and never the stream. Node reports it as `ERR_BUFFER_TOO_LARGE`,
+ * a `RangeError` with no `errno`, which the arm below rethrows untouched for the outer catch.
+ *
+ * The one input where this and `ZipExtFile` could answer differently is a member whose
+ * declared CRC is the CRC of the first `file_size` bytes of a LONGER stream: the reference
+ * would hand back that prefix and this refuses it. Forging that costs the attacker a second
+ * field, it is not reachable from any file a writer produces, and closing it would mean
+ * materialising the overrun to checksum a prefix of it — which is the hole this closes.
  */
-function inflateRaw(raw) {
+function inflateRaw(raw, limit, member) {
     try {
-        return inflateRawSync(raw);
+        try {
+            return inflateRawSync(raw, { maxOutputLength: limit });
+        }
+        catch (err) {
+            const e = err;
+            if (!(err instanceof Error) || typeof e.errno !== 'number')
+                throw err;
+            if (e.code === 'Z_BUF_ERROR') {
+                return inflateRawSync(raw, { maxOutputLength: limit, finishFlush: zlibConstants.Z_SYNC_FLUSH });
+            }
+            const out = new Error(`Error ${e.errno} while decompressing data: ${e.message}`);
+            // `type(zlib.error).__name__` is `error` — the class is `zlib.error`, and `error` is what
+            // the reference records for it (`tools/conformance/ref/docread_ref.py`, `_error`).
+            out.name = 'error';
+            throw out;
+        }
     }
     catch (err) {
-        const e = err;
-        if (!(err instanceof Error) || typeof e.errno !== 'number')
+        if (err.code !== 'ERR_BUFFER_TOO_LARGE')
             throw err;
-        if (e.code === 'Z_BUF_ERROR')
-            return inflateRawSync(raw, { finishFlush: zlibConstants.Z_SYNC_FLUSH });
-        const out = new Error(`Error ${e.errno} while decompressing data: ${e.message}`);
-        // `type(zlib.error).__name__` is `error` — the class is `zlib.error`, and `error` is what
-        // the reference records for it (`tools/conformance/ref/docread_ref.py`, `_error`).
-        out.name = 'error';
-        throw out;
+        throw new BadZipFile(`Bad CRC-32 for file ${pyRepr(member)}`);
     }
 }
 function openZip(path) {
@@ -1332,6 +1412,17 @@ function readMember(zf, name, path) {
         const sample = pySorted(zf.namelist()).slice(0, 8).join(', ') || '(empty archive)';
         throw new DocumentReadError(`${pyPathName(path)} is a zip but has no ${name}; it contains: ${sample}`);
     }
+    // The fifth arm, and it is not zipfile's: a member that decompresses past
+    // `ZIP_MEMBER_MAX_BYTES`. The gate is the UNCOMPRESSED SIZE the central directory declares,
+    // read before anything is decompressed, and it is deliberately the cheapest possible check —
+    // a member that says it is 46 MB costs no inflate at all to refuse. Those are the attacker's
+    // bytes, so declaring LOW is answered one layer down, in `ZipReader.read`: the clamp there
+    // is what makes this gate a ceiling rather than a suggestion.
+    const declared = zf.declaredSize(name);
+    if (declared > ZIP_MEMBER_MAX_BYTES) {
+        throw new DocumentReadError(`${pyPathName(path)} is a zip but its ${name} declares ${declared} bytes uncompressed, ` +
+            `past the ${ZIP_MEMBER_MAX_BYTES} bytes this reader parses, so this reader cannot parse it`);
+    }
     try {
         return zf.read(name);
     }
@@ -2168,6 +2259,35 @@ const MAX_COLUMN_LETTERS = 3;
  */
 export const UNPLACED_SHAPE = 'the column of a cell whose reference is not letters then digits';
 export const UNPLACED_RANGE = 'the column of a cell past XFD, the last column the format has';
+// What a cell loses when a later cell in the same row claims its column. Fixed for the same
+// reason the two above are: the reference is the file's bytes and the column letter is this
+// reader's own, so only the letter travels — in `where`, bounded by `XLSX_MAX_COLUMNS`.
+export const DUPLICATE_CELL = 'the text of a cell a later cell in the same row and column replaced';
+/**
+ * How much text ONE WORKBOOK may materialise, all sheets together. `XLSX_MAX_COLUMNS` bounds a
+ * ROW and nothing bounded the document, which is a ceiling with a hole in it: the width is
+ * bought a row at a time. MEASURED 2026-09-06 on both runtimes: 20,000 rows each holding one
+ * `XFD1` cell deflate to 53,967 bytes and materialise 327,680,000 bytes in ~9 s — 6,072x, out
+ * of a file small enough to mail.
+ *
+ * 16 MiB, the same figure `TEXT_MAX_BYTES` carries and for the same kind of reason, but under
+ * its OWN NAME because the two bound different things: bytes read off a disk there, bytes
+ * rendered out of a container here, and a bar that varies one must not be varying the other.
+ * MEASURED 2026-09-06 over the goal's roots: 15 `.xlsx`, the largest 8,664,227 bytes on disk,
+ * and the largest RENDERING among them 754,520 bytes — 22x under this budget, so no real
+ * workbook on this machine meets it.
+ *
+ * It bounds the RENDERING and nothing else. The sentence that stood here said it bounded the
+ * rendering "because the file is already bounded", and that was FALSE for the whole life of
+ * this constant: `readMember` decompressed a member whole and `parsePart` built a tree from
+ * it, both before the first row was rendered and both outside this budget, so 58,378 bytes on
+ * disk took RSS to 1,039.3 MB with no omission and this ceiling never saw it (review round 5,
+ * H1). What bounds the file is `ZIP_MEMBER_MAX_BYTES`, one door earlier; this bounds what
+ * comes out of it. The shortfall is disclosed as `OMIT_SIZE_CAP` counting the rows no sheet
+ * rendered: a row is what a caller addresses, and a byte count of text that was never built
+ * would be a number this reader cannot honestly produce.
+ */
+export const XLSX_MAX_TEXT_BYTES = 16 * 1024 * 1024;
 /**
  * `B7` -> `[1, '']`. The cell's own reference decides its column; XML order is a fallback.
  *
@@ -2214,7 +2334,11 @@ function sharedStrings(zf, path) {
     if (!zf.has('xl/sharedStrings.xml'))
         return [];
     const out = [];
-    for (const si of parsePart(zf.read('xl/sharedStrings.xml'), 'xl/sharedStrings.xml', path).children) {
+    // `readMember` and not `zf.read`, as `_shared_strings` calls `_read` and not `zf.read`: the
+    // string table is a part this reader cannot do without, so a damaged or encrypted one owes
+    // the reader's own sentence — and it is the member ceiling's door one call before any
+    // worksheet reaches it, which is where a workbook's biggest part actually is.
+    for (const si of parsePart(readMember(zf, 'xl/sharedStrings.xml', path), 'xl/sharedStrings.xml', path).children) {
         const runs = [];
         for (const child of si.children) {
             if (child.tag === NS_S + 't')
@@ -2255,12 +2379,42 @@ function cellText(cell, shared) {
         return raw === '1' ? 'TRUE' : 'FALSE';
     return raw;
 }
-function sheetRows(root, shared, dateStyles = []) {
+/**
+ * The rendered rows of one sheet, and a count of what the rendering did not carry.
+ *
+ * The omissions are gathered in the same pass that renders, never by a second scan: a count
+ * derived from a different walk of the XML can disagree with the rows it claims to describe,
+ * and a disclosure that disagrees with the thing it discloses is worse than none.
+ *
+ * A cell `columnIndex` cannot place is one of those omissions and NOT a refusal (review round
+ * 4, M2): it keeps its text at its XML position and loses only the column the file asked for.
+ * Counted per reason and rendered after the format codes, so the order of this array is blank
+ * rows, then number formats by code, then unplaced cells by reason, then the cells a later
+ * cell in the same row and column replaced.
+ *
+ * A DUPLICATE is a cell whose column already holds text from a cell earlier in the same row.
+ * Last-wins is kept — it is what both runtimes do and what a writer's own second cell means —
+ * and the earlier cell's text is disclosed rather than dropped in silence, which is the only
+ * part of that behaviour nobody chose (entry (w)).
+ *
+ * `budget` is the DOCUMENT's, not this sheet's: the width of one row is already bounded by
+ * `XLSX_MAX_COLUMNS` and the height of a workbook was not, so the row is where the ceiling has
+ * to bite (entry (v)). A row is skipped whole rather than cut in half — half a row is a row
+ * this reader cannot vouch for, which is the same rule `extractText` follows at its own cap —
+ * so the overshoot is at most one row, itself bounded at `XLSX_MAX_COLUMNS` fields.
+ */
+function sheetRows(root, shared, dateStyles = [], budget = { remaining: XLSX_MAX_TEXT_BYTES, total: 0, dropped: 0 }) {
     const rows = [];
     let blank = 0;
     const dated = new Map();
     const unplaced = new Map();
+    const duplicated = new Map();
     for (const row of root.iter(NS_S + 'row')) {
+        budget.total += 1;
+        if (budget.remaining <= 0) {
+            budget.dropped += 1;
+            continue;
+        }
         const cells = new Map();
         let position = 0;
         for (const cell of row.iter(NS_S + 'c')) {
@@ -2270,6 +2424,8 @@ function sheetRows(root, shared, dateStyles = []) {
             if (!text)
                 continue;
             const [column, unplaceable] = columnIndex(cell.get('r'), at);
+            if (cells.has(column))
+                duplicated.set(column, (duplicated.get(column) ?? 0) + 1);
             cells.set(column, text);
             if (unplaceable) {
                 let seen = unplaced.get(unplaceable);
@@ -2303,6 +2459,7 @@ function sheetRows(root, shared, dateStyles = []) {
         for (let k = 0; k < width; k += 1)
             fields.push(cells.get(k) ?? '');
         const line = fields.join('\t');
+        budget.remaining -= utf8Length(line);
         if (!line)
             blank += 1;
         rows.push(line);
@@ -2324,6 +2481,12 @@ function sheetRows(root, shared, dateStyles = []) {
         const sortedColumns = [...columns.keys()].sort((a, b) => a - b);
         omissions.push(new Omission(OMIT_UNPLACED_CELL, [...columns.values()].reduce((a, b) => a + b, 0), 0, sortedColumns.map(columnLetter), reason));
     }
+    // Then the duplicates: ONE omission for the sheet, columns in column order, the same shape
+    // `number-format` and `unplaced-cell` use so that a caller rendering one renders this one.
+    if (duplicated.size) {
+        const columns = [...duplicated.keys()].sort((a, b) => a - b);
+        omissions.push(new Omission(OMIT_DUPLICATE_CELL, [...duplicated.values()].reduce((a, b) => a + b, 0), 0, columns.map(columnLetter), DUPLICATE_CELL));
+    }
     return [rows, omissions];
 }
 function worksheetTargets(zf, path) {
@@ -2359,8 +2522,23 @@ function mediaOmission(media) {
         size += bytes;
     return [new Omission(OMIT_MEDIA, media.size, size, [], pySorted(kinds).join(', '))];
 }
-export function extractXlsx(path) {
-    const zf = openZip(path);
+/**
+ * Every declared sheet, under ONE `XLSX_MAX_TEXT_BYTES` budget for the whole workbook.
+ *
+ * The budget is the document's, so it is made here and not in `sheetRows`, and the shortfall
+ * is disclosed at the document's grain for the same reason — it is not a fact about the sheet
+ * the budget happened to run out on. The cap is stated BEFORE the media tally, because the
+ * media a reader met is a count of what it met underneath the cap.
+ *
+ * `opened` is the reader `sniff` already had to build to decide this file is an OOXML package
+ * (entries (a)/(j)): before it was handed down, one `extract` read the whole archive off disk
+ * TWICE. It is a parameter and never a field, so its lifetime is this call — a reader kept
+ * across calls would answer from bytes no longer on disk, which is exactly what the document
+ * cache one layer up is keyed on (realpath, size, mtime_ns) to avoid.
+ */
+export function extractXlsx(path, opened = null) {
+    const zf = opened ?? openZip(path);
+    const budget = { remaining: XLSX_MAX_TEXT_BYTES, total: 0, dropped: 0 };
     const shared = sharedStrings(zf, path);
     const dateStyles = dateFormats(zf);
     const media = mediaIndex(zf);
@@ -2371,15 +2549,19 @@ export function extractXlsx(path) {
             throw new DocumentReadError(`sheet ${pyRepr(name)} has no resolvable worksheet part`);
         }
         const sheet = parsePart(readMember(zf, target, path), target, path);
-        const [rows, sheetOmissions] = sheetRows(sheet, shared, dateStyles);
+        const [rows, sheetOmissions] = sheetRows(sheet, shared, dateStyles, budget);
         const omissions = [...mediaOmission(anchoredMedia(zf, target, media)), ...sheetOmissions];
         parts.push(new Part(name, index, rows, omissions));
         index += 1;
     }
-    return new Document('xlsx', parts, mediaOmission(media));
+    const capped = [];
+    if (budget.dropped) {
+        capped.push(new Omission(OMIT_SIZE_CAP, budget.dropped, 0, [], `${budget.total} rows in this workbook; this reader renders ${XLSX_MAX_TEXT_BYTES} bytes of cell text`));
+    }
+    return new Document('xlsx', parts, [...capped, ...mediaOmission(media)]);
 }
-export function extractDocx(path) {
-    const zf = openZip(path);
+export function extractDocx(path, opened = null) {
+    const zf = opened ?? openZip(path);
     const root = parsePart(readMember(zf, 'word/document.xml', path), 'word/document.xml', path);
     const media = mediaIndex(zf);
     const anchored = mediaOmission(anchoredMedia(zf, 'word/document.xml', media));
@@ -3157,8 +3339,35 @@ function decodedBody(part) {
         return '';
     return decodeCharset(payload, contentCharset(part) ?? 'utf-8');
 }
+/**
+ * A file's bytes up to `TEXT_MAX_BYTES`, and the `OMIT_SIZE_CAP` for what is past it.
+ *
+ * ONE ceiling and one sentence for every container that holds markup, because "how much of a
+ * file this reader reads" is a fact about the reader and not about the suffix: a 1 GB `.txt`
+ * stopped at `TEXT_MAX_BYTES` and counted the rest while a 1 GB `.html` was held whole
+ * (`docs/roadmap-toolbox.md` row 8, entry (k)). The sentence is `extractText`'s, to the byte,
+ * so a caller cannot tell from it which reader hit the cap.
+ *
+ * Where `extractText` also cuts back to the last line break, this does not: markup is not a
+ * line-oriented format, a half-open tag is not a claim about content the way half a line is,
+ * and the parsers close what the file left open without inventing text for it.
+ */
+function readToCeiling(path) {
+    const size = statSync(pyPathStr(path)).size;
+    const raw = readPrefix(path, TEXT_MAX_BYTES + 1);
+    if (raw.length <= TEXT_MAX_BYTES)
+        return [raw, []];
+    const dropped = size - TEXT_MAX_BYTES;
+    const what = `${size} bytes on disk; this reader reads ${TEXT_MAX_BYTES}`;
+    return [raw.subarray(0, TEXT_MAX_BYTES), [new Omission(OMIT_SIZE_CAP, dropped, dropped, [], what)]];
+}
 export function extractMhtml(path) {
-    const message = parseMessage(splitLines(readFileSync(pyPathStr(path)).toString('latin1')), 'text/plain');
+    // BOUNDED, entry (k): the whole file went into the MIME parser, so a 1 GB `.mht` was held
+    // whole — the same hole `extractHtml` had, in its own spelling. The message is parsed from
+    // the bytes this reader will admit to having read; a truncated MIME message is one the
+    // parser still walks, and what it could not see is COUNTED.
+    const [raw, capped] = readToCeiling(path);
+    const message = parseMessage(splitLines(raw.toString('latin1')), 'text/plain');
     const bodies = [];
     const skipped = new Map();
     let skippedBytes = 0;
@@ -3190,12 +3399,20 @@ export function extractMhtml(path) {
             count += c;
         omissions = [new Omission(OMIT_MEDIA, count, skippedBytes, [], pySorted(skipped.keys()).join(', '))];
     }
-    return nonempty(new Document('mhtml', parts, omissions), path, 'no text/html or text/plain part carried any text');
+    // The cap first: the media tally counts what this reader met UNDERNEATH it, so a caller who
+    // reads that number without the cap above it has read a lower bound as a total.
+    return nonempty(new Document('mhtml', parts, [...capped, ...omissions]), path, 'no text/html or text/plain part carried any text');
 }
+/**
+ * Markup to rows, up to `TEXT_MAX_BYTES` of it, saying how much it did not read.
+ *
+ * BOUNDED, entry (k): this did `readFileSync(path)`, so a 1 GB `.html` was materialised whole
+ * where a 1 GB `.txt` had stopped at the cap and counted the rest since J10.
+ */
 export function extractHtml(path) {
-    const raw = readFileSync(pyPathStr(path));
+    const [raw, capped] = readToCeiling(path);
     const markup = new TextDecoder('utf-8', { fatal: false, ignoreBOM: true }).decode(raw);
-    const doc = new Document('html', [new Part('document', 0, htmlRows(markup))]);
+    const doc = new Document('html', [new Part('document', 0, htmlRows(markup))], capped);
     return nonempty(doc, path, 'its markup carried no text outside script and style');
 }
 function plainRows(text) {
@@ -3203,11 +3420,43 @@ function plainRows(text) {
         .map((raw) => pyStrip(clean(raw)))
         .filter((line) => line);
 }
+/**
+ * THE REFUSAL CARRIES THE OMISSIONS, review round 5 (H2). `extractHtml` and `extractMhtml`
+ * build the `Document` with `capped` in `omissions` and hand it here, and here it raised: the
+ * refusal kept the reader's verdict about the content and threw away the ceiling that
+ * produced that verdict. MEASURED on a 16,777,291-byte `.html` whose 16 MiB `<script>` comment
+ * is followed by one visible sentence — `its markup carried no text outside script and style
+ * ... it is not an empty document`, about a document that carries text, from a read that
+ * stopped 75 bytes short of it. The same on a `.mht` past the ceiling, where the media tally
+ * went with it.
+ *
+ * A reader is allowed to refuse. It is not allowed to state a false fact about a file, and
+ * `why` is a fact about the file only when the whole file was read. Under a cap it is scoped
+ * to the part that was read and the unread bytes are named, so a caller who would have stopped
+ * looking has the one number that tells it not to.
+ */
 function nonempty(doc, path, why) {
     if (doc.parts.some((part) => part.rows.length))
         return doc;
-    throw new DocumentReadError(`cannot read ${pyPathName(path)}: it is a ${doc.kind} container but ${why}, so this reader has ` +
-        'no text for it — it is not an empty document');
+    const capped = doc.omissions.find((o) => o.subject === OMIT_SIZE_CAP);
+    const media = doc.omissions.find((o) => o.subject === OMIT_MEDIA);
+    let said;
+    if (capped === undefined) {
+        said =
+            `cannot read ${pyPathName(path)}: it is a ${doc.kind} container but ${why}, so this reader has ` +
+                'no text for it — it is not an empty document';
+    }
+    else {
+        // The cap's own `what` is quoted rather than rebuilt, so the sentence and the omission can
+        // never state different numbers, and so the clause says whose bytes were counted.
+        said =
+            `cannot read ${pyPathName(path)}: it is a ${doc.kind} container but ${why} in the part ` +
+                `this reader read (${capped.what}) — the ${capped.count} bytes it did not read may carry text`;
+    }
+    if (media !== undefined) {
+        said += `, and it holds ${media.count} embedded part(s) (${media.what}) this reader renders no text for`;
+    }
+    throw new DocumentReadError(said);
 }
 // --------------------------------------------------------------- plain text, in no container
 function textRows(text) {
@@ -3276,10 +3525,13 @@ const EXTRACTORS = {
 const NODE_REFUSED = new Set(['pdf', 'doc', 'rtf']);
 /** Dispatch on what the file IS. Anything unreadable raises, naming the container. */
 export function extract(path) {
-    const container = sniff(path);
+    // `sniffOpen` and not `sniff`: an OOXML container's reader is already built by the time the
+    // kind is known, and handing it to the extractor is the whole of entries (a)/(j). It goes no
+    // further than this call.
+    const [container, opened] = sniffOpen(path);
     const reader = lookup(EXTRACTORS, container.kind);
     if (reader !== undefined)
-        return reader(path);
+        return reader(path, opened);
     if (NODE_REFUSED.has(container.kind))
         throw refuse(path, container, nodeRefusal(container.kind));
     throw refuse(path, container, unsupportedRemedy());