Guard test: derived Ѹ ceiling for MAX_SAFE_USAGE_CHUNK_CHARS is unenforced — column-width or font-size drift silently stales the accepted 34-char overage

[steilerDev]

Type: tech-debt (test-only guard)
Priority: Could Have
Source: product-architect round-3 review of PR #1948 (comment, section 2)
Blocked by: #1939 (the comment this guards lands in PR #1948)

Problem

#1939 records a quantified accepted risk in client/src/lib/reportPdf/overviewPdf.ts: MAX_SAFE_USAGE_CHUNK_CHARS (650) sits 34 characters / 3 lines / 33.6pt over its derived Ѹ (U+0478, Cyrillic letter Uk, 1.1611em at 8pt) ceiling of 616.

That ceiling is derived, not measured. The two recorded №-fill ceilings are each an exact multiple of their own per-line character count — 704 = 44 × 16 (492.8pt) and 546 = 39 × 14 (491.4pt) — and two independent exact multiples landing on the same ~492pt budget means those real renders pinned a line budget, which is font-size-driven rather than glyph-driven. Substituting Ѹ's narrower per-line counts (14 at 8pt, 13 at 9pt) gives derived ceilings of 44 × 14 = 616 and 39 × 13 = 507. MAX_SAFE_SMALL_CHUNK_CHARS (450) is safe at 11.2% under 507; the usage cap is not.

The gap is that nothing enforces this. The derived 616 depends on USAGE_WIDTH_7COL, TABLE_BODY_FONT_SIZE, and DEFAULT_LINE_HEIGHT. Widen the Usage column, change a font size, or add a locale with a wider script, and 616 moves — nothing in the tree fails, and the only record of the exceedance is a comment a refactor can delete. The existing assertions in overviewPdf.test.ts pin MEASURED_TRUE_CEILING as re-typed literals (704, 546) that do not reference any geometry constant, so they stay green while the real ceiling shifts underneath them.

Scope: this issue owns the guard; the comment owns the rationale

Explicitly ruled by the architect, and important — neither replaces the other:

Keep it in the code. The decision belongs with the constant: anyone changing 650, the column width, or a font size reads that comment; they will not find an issue. Moving it out would recreate exactly the provenance loss that produced this whole issue.

So the rationale comment stays authoritative and untouched. This issue adds only the test that makes the comment's numbers fail loudly instead of going stale.

Why a tracked issue rather than just the comment — the architect drew a distinction worth preserving:

markerText is unbounded with an estimated break-even, whereas this is a bounded constant provably 34 characters past a derived ceiling. A quantified exceedance is a standing accepted risk with a number on it and deserves a tracked owner.

This is not a request to change 650. The architect is comfortable with the risk itself: 650 characters of unbroken archaic Church Slavonic Uk in one Usage cell is not a credible input, and the alternative is worse — a Ѹ-safe value must sit in [600, 616], collapsing AC12's margin above its 600-character floor from 8.3% to ~2.7%.

Acceptance Criteria

1. Derived-ceiling guard

• 1.1 A unit test recomputes both derived Ѹ ceilings from USAGE_WIDTH_7COL, TABLE_BODY_FONT_SIZE, TABLE_SMALL_FONT_SIZE, DEFAULT_LINE_HEIGHT, and Ѹ's per-em advance — the ceilings under test are computed, never re-typed as 616 / 507 literals.
• 1.2 The test asserts the recomputed ceilings currently equal 616 (usage, 8pt) and 507 (small, 9pt), pinning today's constants.
• 1.3 The test asserts MAX_SAFE_USAGE_CHUNK_CHARS exceeds its derived ceiling by exactly 34 characters. Movement in either direction fails: growth widens an accepted risk, and shrinkage makes the comment's recorded figure wrong.
• 1.4 The test also asserts the overage expressed in lines (3) and points (33.6), since the comment quantifies all three and all three must stay true together.
• 1.5 The test asserts MAX_SAFE_SMALL_CHUNK_CHARS (450) is strictly below its derived 507 ceiling, retaining at least the recorded ~11.2% margin. Unlike 1.3, this is a genuine safety assertion, not only a staleness pin.
• 1.6 The measured line budgets (44 lines at 8pt / 39 at 9pt, equivalently ~492.8pt / ~491.4pt) are the only pinned literals, and are labelled in-test as real-render measurements that cannot be recomputed from constants.
• 1.7 The test fails if any of USAGE_WIDTH_7COL, TABLE_BODY_FONT_SIZE, TABLE_SMALL_FONT_SIZE, or DEFAULT_LINE_HEIGHT changes. Demonstrated by temporarily mutating each during development and observing a failure; the mutations are not committed.
• 1.8 The failure message names the constant that moved and points to MAX_SAFE_USAGE_CHUNK_CHARS's doc comment, so whoever trips it finds the rationale rather than only a failed number.

2. The comment stays authoritative

• 2.1 The rationale comments on WORST_CASE_CHAR_ADVANCE_EM, MAX_SAFE_USAGE_CHUNK_CHARS, and MAX_SAFE_SMALL_CHUNK_CHARS are not moved, shortened, summarised, or replaced by a pointer to this issue.
• 2.2 The new test cites this issue number and refers to those comments as the authoritative rationale.
• 2.3 No production value changes: MAX_SAFE_USAGE_CHUNK_CHARS (650), MAX_SAFE_SMALL_CHUNK_CHARS (450), WORST_CASE_CHAR_ADVANCE_EM (1.04), all column widths, and all font sizes are byte-identical.

3. Existing assertions

• 3.1 The existing 704 / 546 MEASURED_TRUE_CEILING assertions are either kept or superseded by the new computed form. If superseded, the №-fill ceiling relationship and AC12's 600-character floor remain asserted — no net loss of coverage.

Verification

Given the report PDF geometry constants are unchanged
When the guard test runs
Then it passes, reporting a derived usage ceiling of 616 and an accepted overage of 34 characters / 3 lines / 33.6pt.

Given a developer widens USAGE_WIDTH_7COL (or changes TABLE_BODY_FONT_SIZE / TABLE_SMALL_FONT_SIZE / DEFAULT_LINE_HEIGHT)
When the test suite runs
Then the guard test fails and names the changed constant, instead of the derived ceiling silently moving while the doc comment keeps asserting 616.

Given a developer raises MAX_SAFE_USAGE_CHUNK_CHARS above 650
When the test suite runs
Then the guard test fails, because the accepted overage is no longer the 34 characters that was reviewed and accepted.

Non-goals

• The 3,919-codepoint glyph sweep artifact is out of scope. The architect was explicit that re-running the sweep is not what matters here and downgraded it from the original ask:

  the thing worth landing was never the 3,919-codepoint sweep. It's a guard test. […] The sweep itself becomes an optional opt-in extra, not the deliverable.

  It is left out deliberately rather than carried as an optional criterion, so this issue has exactly one binary deliverable. If a checked-in sweep harness is ever wanted, file it separately.

• Changing MAX_SAFE_USAGE_CHUNK_CHARS, or re-measuring any ceiling against a fresh real render.

• The Ѹ-vs-ceiling question itself, which reportPdf geometry hygiene: bounds that name their own scope (HEADER_ROW_HEIGHT_MAX, char-advance scope, channel enumeration, PDF_STYLES relocation) #1939 closed completely: the derivation is reproducible from constants in the file, so no render is needed, ever.

Notes

• Test-only, no user-facing behaviour, guarding a risk the architect has already accepted — hence Could Have. It earns a tracked issue because the exceedance is quantified, which makes it a standing accepted risk with an owner rather than an unbounded channel documented in passing.
• Related: reportPdf geometry hygiene: bounds that name their own scope (HEADER_ROW_HEIGHT_MAX, char-advance scope, channel enumeration, PDF_STYLES relocation) #1939 (parent hygiene issue, lands the comment), Report PDF continuation rows read as broken: runt trailing chunks and no continuation signal #1940, Report wizard: editable override fields (attachmentsNote et al.) have no length limit #1941 (attachmentsNote has no maxLength — a real bound there would reduce, though not remove, reachability pressure on MAX_SAFE_SMALL_CHUNK_CHARS).
• Sizing: S. One test block in client/src/lib/reportPdf/overviewPdf.test.ts; owned by qa-integration-tester.