docs(scripts): carry the squash-merge sha beside BASELINE.commit so the provenance resolves with git alone

.changeset/baseline-squash-merge-sha-9355.md

@@ -0,0 +1,26 @@
+---
+---
+
+Build-tooling provenance only; nothing published changes.
+
+`BASELINE` in `scripts/check-eager-closure-budget.mjs` gains a second commit field,
+`squashMerge`, beside the existing `commit`. ⛔ No ceiling, baseline, threshold or
+ratchet moves, and ⛔ what `commit` names is unchanged — the docblock's standing ruling
+that it must name the tree the reading was taken on is left exactly as written.
+
+The thing it buys: `commit` names a branch tip, this repository squash-merges, and the
+object therefore does not exist in any `main` checkout (`git cat-file -t` exits 128 in a
+clone that `git rev-parse --is-shallow-repository` reports as `false`, so the absence is
+genuine). The squash that carried the same branch onto `main` does resolve, and carrying
+it AS DATA drags it under the existing positive pin that holds every commit the
+constant carries to its own attached prose. A prose hash on this constant is guarded by
+nothing; a carried one cannot go stale in silence — and this change was open long enough
+to be shown that rather than argue it. A re-baseline landed on `main` underneath it,
+rewrote the block, and took the prose handle out with it: on `main` today the squash of
+the tree the constant names appears nowhere in the repository, while the field below
+carries it under the pin.
+
+The ledger case in `scripts/__tests__/check-eager-closure-budget.test.ts` that records
+what each baseline carries as data is re-pinned to the exact new pair. It is still
+positional and still exact: it was not widened, and a re-baseline that cannot yet name
+its own squash sha is meant to red there and be re-pinned deliberately.

scripts/__tests__/check-eager-closure-budget.test.ts

@@ -1966,15 +1966,30 @@ describe('the prose attached to the baselines (objectui#7046)', () => {
 
   /**
    * What each baseline carries AS DATA, recorded so the pin above cannot go
-   * vacuous in silence. Measured on `main`: `BASELINE` carries exactly one
-   * commit string; `PER_CHUNK_BASELINE` carries NONE — its per-key provenance
+   * vacuous in silence. Measured on `main`: `BASELINE` carries exactly two
+   * commit strings; `PER_CHUNK_BASELINE` carries NONE — its per-key provenance
    * commits live only in prose, with no exported value to check them against,
    * which is why the pin above says nothing about it and the claim pin below is
    * what guards its block. Add a `commit` field there and this reds, and the pin
    * above starts covering it.
+   *
+   * The second string is objectui#9355's `squashMerge`: the tree the reading
+   * was taken on cannot be resolved from a `main` checkout, so the squash that
+   * landed it is carried beside it as the handle that can. ⭐ Carrying it as
+   * DATA rather than leaving it in prose is the point of the change — a prose
+   * hash is guarded by nothing, while a carried one is dragged under the
+   * positive pin above and cannot go stale in silence, which is the
+   * objectui#6778 defect one column over.
+   *
+   * ⚠️ This case is POSITIONAL and exact on purpose, and ⛔ must not be widened
+   * to tolerate either shape. A re-baseline cannot know its own squash sha —
+   * the sha does not exist until the pull request merges — so the honest value
+   * at that moment is `null`, and `null` reds here. That red is the intended
+   * signal: it is a ledger, it is re-pinned deliberately, and a predicate loose
+   * enough to accept both shapes would stop recording anything.
    */
   it('records what each baseline carries as data, so the pin cannot go vacuous', () => {
-    expect(commitsCarriedBy(BASELINE)).toEqual([BASELINE.commit]);
+    expect(commitsCarriedBy(BASELINE)).toEqual([BASELINE.commit, BASELINE.squashMerge]);
     expect(commitsCarriedBy(PER_CHUNK_BASELINE)).toEqual([]);
   });
 

scripts/check-eager-closure-budget.mjs

@@ -564,6 +564,55 @@ export const BASELINE = Object.freeze({
   chunks: 329,
   totalChunks: 2309,
   commit: 'bbf6b02d9',
+
+  /**
+   * The squash merge that carried that branch onto `main` — recorded here so
+   * the provenance above is checkable with `git` and nothing else
+   * (objectui#9355).
+   *
+   * ⛔ NOT a correction, and ⛔ never a substitute for the field above. The
+   * PROVENANCE paragraph's ruling stands exactly as written: the field above
+   * names the tree the reading was taken on, that is the whole point of the
+   * convention, and no commit on `main` has that tree. This is the OTHER half
+   * — a sha that resolves — so a reader who tries to re-check the measurement
+   * gets a handle rather than the dead end that paragraph describes. Both legs,
+   * taken in a checkout where `git rev-parse --is-shallow-repository` answers
+   * `false`, so the absence is GENUINE and ⛔ not a shallow-clone artefact:
+   *
+   *     git cat-file -t 67485872ed  ->  commit
+   *     git cat-file -t bbf6b02d9   ->  fatal: Not a valid object name
+   *
+   * ⚠️ The two name DIFFERENT TREES, and how far apart is ⛔ NOT established
+   * here. The field above does not resolve, so no checkout can count the
+   * commits between the pair, and the gzipped distance between them would need
+   * a console build of each. ⛔ Do not read that silence as "small":
+   * objectui#9209 measured exactly one such distance, on the pair this field
+   * named before objectui#9251 re-baselined the constant, and that reading is a
+   * fact about the RETIRED pair which says nothing about this one. Carrying the
+   * figure forward is the stale-prose defect this block exists to refuse.
+   *
+   * The value below is RE-DERIVED rather than copied forward: it is the commit
+   * on `main` that introduced the field above into this file, which
+   * `git log origin/main -S <tip> --oneline --reverse --
+   * scripts/check-eager-closure-budget.mjs` returns as its earliest hit, and it
+   * is single-parent — as a squash is — with `(#9399)` in its subject, the pull
+   * request that carried objectui#9251.
+   *
+   * ⚠️ This field can only ever be BACK-FILLED, which is the one thing a future
+   * re-baseline has to know about it. A squash sha does not exist until the
+   * pull request merges, so the change that re-pins the field above ⛔ cannot
+   * write its own here. ⛔ Do not guess one, and ⛔ do not carry this one
+   * forward onto a reading it was not taken with: a wrong sha in this position
+   * is worse than an absent one, because unlike the field above it RESOLVES,
+   * and a reader who builds the wrong tree gets a plausible number instead of
+   * an error. Write `null` and let a follow-up name the merge once it exists.
+   * That reds the ledger case in
+   * `scripts/__tests__/check-eager-closure-budget.test.ts` which records what
+   * this constant carries as data, and redding there is the intended signal —
+   * the ledger is re-pinned deliberately, ⛔ never widened to accept either
+   * shape.
+   */
+  squashMerge: '67485872ed',
 });
 
 /**