diff --git a/.changeset/eager-closure-header-retired-figures.md b/.changeset/eager-closure-header-retired-figures.md new file mode 100644 index 0000000000..f45409d3f1 --- /dev/null +++ b/.changeset/eager-closure-header-retired-figures.md @@ -0,0 +1,4 @@ +--- +--- + +Docs-only: the eager-closure gate header stops restating its ceiling and baseline as MiB literals and names the two constants instead, with a pin that refuses a rendered size written back into that note. Internal CI script and its unit test only; nothing published changes. diff --git a/scripts/__tests__/check-eager-closure-budget.test.ts b/scripts/__tests__/check-eager-closure-budget.test.ts index 8204d17c43..b754cdd91b 100644 --- a/scripts/__tests__/check-eager-closure-budget.test.ts +++ b/scripts/__tests__/check-eager-closure-budget.test.ts @@ -2088,3 +2088,84 @@ describe("chunk counts in this gate's prose (objectui#7528)", () => { }, ); }); + +// ── the ceiling note names its constants, and never renders them ───────────── + +/** + * objectui#8964 — the header note that says WHICH constant is which may name + * its two subjects, and may not render either of them as a size. + * + * The note used to do both. It stated the aggregate ceiling and the baseline as + * MiB literals and then explained, correctly and at length, why the two figures + * were consistent with each other. A maintainer-authorised re-baseline moved + * both constants; the prose stayed. For four days and three subsequent edits to + * that file the note rendered the RETIRED pair, explaining the consistency of + * two numbers neither of which was in force, and nothing anywhere went red — + * because nothing fails on a number written in a comment. + * + * ⚠️ This is NOT a widening of the chunk-count pin above into a size pin. That + * trade was weighed there and declined for a reason that still holds: a general + * size pin would have to tell a ceiling's value from the several sizes this + * file's prose legitimately carries, and it cannot. This pin does not try. Its + * population is two named paragraphs which carry no size at all, and its whole + * claim is that they still carry none. The anchored measurements elsewhere in + * the header — the re-baseline records, the incident figures — are outside it + * and stay exactly as they are. + * + * ⚠️ Nor may this docblock quote the retired literals back, for the reason the + * objectui#7528 block gives: the reader cannot tell a quotation from a claim, + * and refusing both is the safe direction. The numbers live in the card. + * + * The region is located by the sentence that opens it and the sentence that + * closes it, both asserted present and unique, so a rewrite that drops either + * one turns this red rather than green — an empty scan here would otherwise be + * indistinguishable from a note that states nothing. + */ +describe('the ceiling note states no rendered size (objectui#8964)', () => { + /** The first words of the note, and the last — the region this pin owns. */ + const OPENS = 'This is a truthful CURRENT-STATE ceiling, not a target.'; + const CLOSES = 'rendered size written back into either paragraph.'; + + /** A size as a person writes one: a numeral, then a byte unit. */ + const RENDERED_SIZE = /\b\d[\d,_]*(?:\.\d+)?\s*(?:[KMGT]i?B)\b/g; + + const renderedSizes = (text: string): string[] => + [...text.matchAll(RENDERED_SIZE)].map((m) => m[0].replace(/\s+/g, ' ').trim()); + + /** The note, as the pin reads it. Throws rather than returning nothing. */ + function ceilingNote(source: string): string { + const start = source.indexOf(OPENS); + const end = source.indexOf(CLOSES); + if (start < 0 || end < 0) throw new Error('the ceiling note is not where this pin looks for it'); + return source.slice(start, end + CLOSES.length); + } + + it('reads a note that is there exactly once, rather than reading nothing', () => { + const source = fs.readFileSync(checkerPath, 'utf8'); + expect(source.split(OPENS).length - 1).toBe(1); + expect(source.split(CLOSES).length - 1).toBe(1); + // A floor, so a note shrunk to its two anchors cannot pass by carrying nothing. + expect(ceilingNote(source).length).toBeGreaterThan(800); + }); + + it('sees a rendered size when one is in front of it', () => { + expect(renderedSizes('a 9.99 MB payload, 512 KiB of it new, over a 7 GB disk')).toEqual([ + '9.99 MB', + '512 KiB', + '7 GB', + ]); + expect(renderedSizes('objectui#8964 names two constants and renders neither')).toEqual([]); + }); + + it('renders neither constant as a size', () => { + const rendered = renderedSizes(ceilingNote(fs.readFileSync(checkerPath, 'utf8'))); + expect( + rendered, + `the note that says which constant is which renders a size (${rendered.join(', ')}). ` + + 'A figure written here is a second copy of a constant that lives a few lines below it, and ' + + 'only one of the two moves when the ceiling is re-baselined — which is how this note came to ' + + 'explain, for four days, why two retired numbers were consistent with each other. Name the ' + + 'constant and let the gate print the reading (objectui#8964).', + ).toEqual([]); + }); +}); diff --git a/scripts/check-eager-closure-budget.mjs b/scripts/check-eager-closure-budget.mjs index 9b5e9a7798..84b9ea7849 100644 --- a/scripts/check-eager-closure-budget.mjs +++ b/scripts/check-eager-closure-budget.mjs @@ -205,20 +205,31 @@ * become an excuse to widen it — a ceiling that rises while the sensitivity * relaxes is a gate quietly retiring itself. * - * This is a truthful CURRENT-STATE ceiling, not a target. 3.07 MB gzipped - * before first render is a bad payload, and the honest long-term line is far - * below it — but lowering the line to a TARGET is a separate decision with its - * own work behind it (objectui#5324 names the candidates), and re-baselining - * onto a fresh measurement is not that. Nothing here should be read as a - * finding that 3.12 MB is acceptable. - * - * The two figures in that paragraph are one constant each, rendered in MiB, and - * not a contradiction: 3.07 MB is {@link BASELINE}'s measured payload and - * 3.12 MB is {@link MAX_EAGER_CLOSURE_GZIP_BYTES}, the ceiling standing over it. - * Saying which is which is the whole of this note — a paragraph that names two - * sizes without naming their subjects reads as one number that changed its mind + * This is a truthful CURRENT-STATE ceiling, not a target. A multi-megabyte + * gzipped payload before first render is a bad payload, and the honest + * long-term line is far below it — but lowering the line to a TARGET is a + * separate decision with its own work behind it (objectui#5324 names the + * candidates), and re-baselining onto a fresh measurement is not that. Nothing + * here should be read as a finding that the ceiling standing over the closure + * today is acceptable. + * + * Which is which: {@link BASELINE} carries the measured payload and + * {@link MAX_EAGER_CLOSURE_GZIP_BYTES} is the ceiling standing over it. Saying + * which is which is the whole of this note — a paragraph that names two sizes + * without naming their subjects reads as one number that changed its mind * (objectui#7528). * + * ⛔ Neither paragraph renders either constant as a size, deliberately. This + * note used to state both of them as MiB literals; a re-baseline moved both + * constants, and four days and three later edits to this file went by with the + * RETIRED pair still written here and nothing red anywhere across that + * distance, because nothing fails on a number written in a comment + * (objectui#8964). The subjects are named and the readings are left to the + * instrument: the two constants below carry them in bytes, each pinned to the + * commit it was measured on, and the gate's verdict line prints the live one on + * every run. `scripts/__tests__/check-eager-closure-budget.test.ts` refuses a + * rendered size written back into either paragraph. + * * ## Per-chunk ceilings (objectui#5490) * * One total over the whole eager closure cannot say WHERE the payload moved, and @@ -255,8 +266,9 @@ * * Re-baselining is legitimate — it is how a ratchet advances — but it is a * DECISION, so make it visible: update the constant, update the measured figure - * in this comment, and say in the PR what the added bytes buy. Silently bumping - * the number to make CI green reproduces the gate this file replaced. + * in the prose attached to it, and say in the PR what the added bytes buy. + * Silently bumping the number to make CI green reproduces the gate this file + * replaced. */ import fs from 'node:fs';