[AdCodicem]

What this changes

Batch 17 of M02's step 4: numbers a file chooses so that they share a hash table's bucket (ADR 52).

• The index keeps its entries in arrays (PdfXRefTable). Numbers and entries lie in two arrays, in the order the
  table first recorded them, which stays the order it enumerates them in; a number finds its entry in a slot while
  numbers run in order — the slots no longer than twice the entries held or made room for, and 1,024 more —, and past
  them in a map hashed through the process's seed, which gives back its room once the slots have taken most of its
  numbers. 40 bytes an object numbered in order, against 52 to 63: opening 300,000 objects allocates 12.0, 22.5 and
  24.2 MB for a table, a stream and a chain of a thousand sections, against 16.9, 27.4 and 30.6 MB, budgets
  recalibrated.
• A stale /Size keeps bounding the room until an older section numbers past the newer ones. A /Size the
  sections number past stands for one past the highest number they gave; once an older section, or its /XRefStm
  stream, numbers past the newer ones, it bounds nothing, so that the index doubles rather than growing by one entry at
  each section — which, with arrays sized exactly, copied the whole index each time: 3.6 GB in 3.5 s for a thousand
  sections, found by the first review round.
• Every other table keyed by numbers hashes them through the process's seed (SeededComparer). The reader's cache,
  its object streams, its sets and memos keyed by numbers or offsets, the copies it marks and restores, and the
  validator's walks: System.HashCode, drawn once a process as .NET does for strings, both halves of an offset mixed
  in apart.
• PdfObjectId and PdfDiagnostic hash through the seed. A record struct's own hash is a fixed linear combination
  a file inverts; equality stays the record's, and a hash now differs from one process to the next. No signature
  changes.
• Two tests read the code (SeededComparerTests). One reads the compiled library's IL and refuses every hash
  collection over a key a file can steer — a number wider than a byte, a tuple or a pair, a struct keeping .NET's
  default hash, a record's compiler-written hash, a key typed by any interface — unless the comparer of its key, taken
  last, is SeededComparer.Instance handed straight; and always a table keyed by any object, a collection over a type
  parameter, or one built for a type argument over such a key, and every collection that enumerates by hash — concurrent, frozen, immutable, a StringDictionary —, whatever its key
  and comparer, but PdfName's interning table, built once and called on only to find or add a name, so that no order a
  seed sets reaches an output (invariant 6). It takes out the probes code coverage inserts, by their exact shape. The
  other reads the sources and names the file and line.
• The shapes measured are held by ReaderTimingTests, each against the same file numbered in order, and the stale
  /Size's room by DocumentReaderTests on three chains; IndexBenchmarks gains a table of numbers three apart.
• Mutation testing becomes a finite step of every pull request that changes src/ (ADR 53, a line in CLAUDE.md).
  This batch's review swept its guard test with mutants from its twenty-fifth round on, each sweep's catalog finer than
  the last and each survivor counting as a finding, so that no round came back without one. The maintainer bounded it
  on 2026-10-30, then made the rule: a fixed, first-order catalog over the lines of src/ a pull request changes, and
  in a test that reads the library's code over the conditions it adds or changes; a survivor killed by a test, classed
  equivalent or, in such a test, widening, each with its reason, or filed as debt, and never a review finding.

Why

Closes #155

Measured on main at e3e2034, each shape a single cold run against the same file numbered in order: 34,167 one-row
subsections opened in 1.9 s against 0.04 s and validated in 4.0 s against 0.09 s; 36,350 objects and no table rebuilt
in 8.0 s against 0.07 s; a million references to those numbers resolved in 56 s against 0.73 s. No guard bounds it.
Four ways were prototyped and measured; the maintainer settled the four questions as recommended on 2026-10-28: the
index dense and a seeded hash elsewhere, the process's seed, PdfObjectId and PdfDiagnostic seeded, and a test that
reads the code. 32 adversarial review rounds, 286 findings, each put to a refuter; the first round's three
majors fixed with a test that failed before its fix, none after. The last eight rounds swept the guard test with
3,676 mutants, until ADR 53 made the survivors the mutation step's to settle rather than the review's. The journal of
2026-10-28 in docs/status.md lists them.

Filed under M23: #305, the seeded hash the validator's walks pay (see below); #306, the source reading's mutation
survivors, shapes it misses that the compiled reading refuses. Filed under M02: #307, the test of a disposed document's memory, which
failed once in CI's compat (.NET 11) job on d7d3697 (run 836), a commit that changes only SeededComparerTests,
the process letting go of 92 MB between the test's first two measures; run 837, on the next commit, passed it.

Definition of done

The project's definition of done applies to every change:

• Unit tests cover the behavior, including its degenerate and hostile cases — 230 new, 5,343 to 5,573 (7,715 to 7,945 with the remote documents)
• Anything an independent tool should confirm is covered by the integration suite — 3,688 against qpdf, 3,682 passed and 6 skipped, twice, on the library code this ends with
• The build has no new warnings, and any suppression is local and justified
• docs/status.md records the batch: the journal of 2026-10-28 and the figures at a glance
• Public API carries XML documentation, and the site under docs/website matches what now exists — 266 pages built, the site's check clean
• dotnet format has been run

Anything reviewers should look at closely

• What the validator pays. Under a medium job, twice, main and the branch alternated, the rules over 1,000 pages
  already read take 2.9 to 3.2 ms against 2.6 to 2.7, about 15 % more, where the prototype the decision rested on had
  measured 5 to 8 %; opening and validating 7.0 to 7.3 ms against 6.7 to 6.8, about 5 % more, the lighter index paying
  part of it back; the Arlington walk alone 2 to 6 % more; allocation the same. The cost is the seeded hash in the
  validator's thirty sets and maps keyed by object number. The validator's walks pay a seeded hash for every object number they meet: the rules take about 15 % longer since #155 #305 files it under M23, with a set indexed by the index's
  slots as the way to measure first.
• What opening gains. Indexing 1,000 pages 200 to 222 µs and 83 KB against 230 to 242 µs and 123 KB; an index of
  300,000 objects 8 to 13 % faster and 4 to 6 MB lighter; numbers spread far apart, which the map serves, keep 60 to 110
  bytes an object (concepts/lazy-reading.md gives the figures by shape).
• CI was red from 32849ec to 3109cb5 (runs 813 to 819): under coverage, as CI runs the unit suite, the
  instrumentation puts a probe between the comparer's getter and the table's constructor, which the reading of the
  compiled library took for code the source wrote. 3abfe27 reads through the probes, with a test that emits a probed
  method and a truly wedged one; run 820 and the runs after it are green. 8de9e16 fails dotnet format too, an
  endless loop spaced otherwise than the formatter writes it, which dbee093 corrects. CI ran on 49 of the 64 commits
  as each was pushed; no commit was checked alone otherwise, a check the maintainer dropped on 2026-10-29 since batches
  are squashed. A rebase merge would leave those commits failing; a squash would not.
• Coverage: all 191 measurable lines of the patch; src/ 99.43 % (8,224 of 8,271) on the committed corpus.
• Checked:
  • integration twice on 31d0870, whose library code the branch ends with (later commits change comments and tests);
  • the 401 corpus documents on main and the branch, twice each: the same 2,475 lines on all four runs;
  • mutation: the stale /Size flag's assignments and every condition of the compiled reading, each failing a test
    written for it but those judged equivalent; eight sweeps of the compiled reading, 3,676 mutants, every survivor C#
    reaches failing a sample written for it, the others classed equivalent or widening with their reasons; the source
    reading's survivors are held by samples or filed as The source reading of tables keyed by numbers holds some of its own conditions with no sample #306;
  • dotnet format; Remote corpus runs 87, 89, 90 and 93, whole at their first attempt, runs 90 and 93 on the
    library code this ends with.

Merge: squash recommended, as a fix: (no public signature changes; the hashes of PdfObjectId and
PdfDiagnostic change value, which a caller must not have stored).

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!