docs(console-pin): the injection gate's header and remedy, and release.yml's key comment, say the two dist keys now differ (#20765)

ci.yml's console dist key hashes a superset of release.yml's since the
previous commit, so three pieces of prose went false: the header of
scripts/check-console-injection.mjs restated the old key and said
packages/spec was out of the console filter, its remedy() fallback printed
that key as the one to delete, and release.yml asked the two keys to stay
in step. The header and the fallback now point at each workflow's restore
step instead of carrying a third copy of the key, and release.yml's comment
says its narrower key is deliberate. No key, step or env changes.

Claude-Session: https://claude.ai/code/session_017VaLJnYwhPsanVCe9dMCJU
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.github/workflows/ci.yml

@@ -2438,8 +2438,8 @@ jobs:
       #
       # ⚠️ release.yml's restore step still keys on the pin and the build script
       # alone, so the two workflows no longer share dist entries: each builds its
-      # own on a miss. That file's comment asks for the two to stay in step; which
-      # way to reconcile them is recorded on #20765.
+      # own on a miss. The narrower release key is deliberate, and that file's
+      # comment says why (#20765).
       #
       # Split restore/save where release.yml uses the combined action, because the
       # combined form's post-step saves even when the job FAILED. build-console.sh

.github/workflows/release.yml

@@ -1378,9 +1378,13 @@ jobs:
       - name: Build
         run: pnpm run build
 
-      # ci.yml's Console Pin Gate (#4290) uses this exact key, so the pin bump's
-      # PR run and this job share one build — keep the two in step if either
-      # input set changes.
+      # This key hashes the pin and the build script. ci.yml's Console Pin Gate
+      # (#4290) hashes a SUPERSET: those two, the probe scripts and the spec's
+      # entry layout (#20765). So the two workflows no longer share dist entries,
+      # and each one builds its own on a miss. Keeping this key narrower is
+      # deliberate. Following ci.yml would rebuild the console on every Version
+      # Packages merge, and publishing a cached console whose spec content lags
+      # is the existing cache design.
       #
       # Split restore/save, matching ci.yml, and not the combined actions/cache
       # action: the combined form's post-step saves even when the job FAILED,

scripts/check-console-injection.mjs

@@ -7,20 +7,23 @@
  *
  * ## The hole this closes (objectstack#9667)
  *
- * The vendored Console SPA is cached under
- *
- *     ${{ runner.os }}-console-dist-${{ hashFiles('.objectui-sha', 'scripts/build-console.sh') }}
- *
- * spelled identically in ci.yml (twice: restore + save) and release.yml. The key
- * does NOT include packages/spec, so a dist built while spec was at state X is
- * restored and reused after spec moves on — and because
+ * The vendored Console SPA is cached under a key each workflow spells in its
+ * own restore step: ci.yml's `console-pin` job and release.yml's publish job.
+ * The key is deliberately not restated here, because a copy in a comment is one
+ * that nothing holds in step (scripts/check-ci-filter-parity.mjs holds ci.yml's
+ * spellings to its `console` filter). The two keys no longer match
+ * (objectstack#20765): release.yml hashes the pin and the build script, and
+ * ci.yml hashes those plus the probe scripts and the spec's ENTRY LAYOUT
+ * (package.json, tsup.config.ts). Neither includes the spec's CONTENT, so a dist
+ * built while spec was at state X is restored and reused after spec moves on,
+ * and because
  * scripts/assert-console-spec-injection.mjs runs INSIDE build-console.sh, a
  * cache hit skips the entire build step and therefore skips the assertion too.
  * The injection fixed resolution; the cache could still serve a console whose
  * bundled spec is not the one this build proved.
  *
- * Adding packages/spec to the cache key was considered and REJECTED: it busts
- * the key on every spec change and forces a full cold console rebuild (~20 min,
+ * Adding the whole of packages/spec to the cache key was considered and
+ * REJECTED: it busts the key on every spec change and forces a full cold console rebuild (~20 min,
  * measured) on a repo doing ~18 merges a day. The cache's economics — including
  * ci.yml's deliberate split restore/save, which exists so a failed build never
  * poisons the entry — are kept exactly as they are. Only the silent half is
@@ -48,21 +51,27 @@
  * the stamped detector is STILL ABSENT from this tree's spec. Once the published
  * spec catches up, the stamp is expired and says so instead of passing.
  *
- * ## Why packages/spec is NOT in ci.yml's console filter (objectstack#9710)
+ * ## Why the rest of packages/spec is NOT in ci.yml's console filter (objectstack#9710)
  *
- * That filter lists the pin, the build script and this gate's own sources — not
- * packages/spec — so a spec-only PR never schedules Console Pin Gate and never
- * reaches this check. Adding it is the obvious next thought; it was measured and
+ * That filter lists the pin, the build and probe scripts and this gate's own
+ * sources, and since objectstack#20765 also the spec's ENTRY LAYOUT
+ * (package.json's exports map and tsup.config.ts). ci.yml's dist key hashes
+ * each of those build inputs too, so a head that moves the entry layout MISSES
+ * the cache, rebuilds, and assert-console-spec-injection.mjs judges it; a
+ * cache hit could not have, as the paragraphs below explain. The rest of
+ * packages/spec is its CONTENT, which is in neither the filter nor the key, so
+ * a content-only spec PR never schedules Console Pin Gate and never reaches
+ * this check. Adding the content is the obvious next thought; it was measured and
  * DECLINED, and the reason is not cost, which is why it is recorded here rather
  * than left on a card: the job it would schedule is vacuous, not expensive.
  *
  * Count what this gate can fail on. Of its six failure verdicts, FIVE are pure
  * functions of the RESTORED DIST and its stamp — a missing dist, unreadable
  * assets or a malformed stamp, a missing stamp, the published-only detector
  * present in the bundle, the stamp's own fresh witness missing from it. A
- * spec-only diff cannot move any of those: the cache key is the one spelled at
- * the top of this header — the pin and the build script, nothing else — and
- * entries under it are IMMUTABLE, so all five replay what the last
+ * content-only spec diff cannot move any of those: it does not move the cache
+ * key (see the top of this header for what each key hashes), and entries under
+ * a key are IMMUTABLE, so all five replay what the last
  * console-filtered run already saw. Exactly ONE verdict reads this tree, the
  * expiry re-check, and it needs packages/spec/dist because readSpecBlob resolves
  * the package's exports map. So the restore-only job proposed there — no
@@ -214,13 +223,17 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
  * How an operator clears a cached dist this gate refused.
  *
  * ⛔ The `gh cache delete` line is MAINTAINER-ONLY — it needs repo write scope,
- * and it deletes an entry shared by ci.yml and release.yml. It is named anyway
- * because ruling out a remedy an operator cannot discover is how a red becomes
- * noise; a contributor who cannot run it should hand this message to a
- * maintainer rather than guess.
+ * and it deletes an entry every later run of that workflow under the same key
+ * would restore. It is named anyway because ruling out a remedy an operator
+ * cannot discover is how a red becomes noise; a contributor who cannot run it
+ * should hand this message to a maintainer rather than guess.
+ *
+ * The key comes from the CI step (`CONSOLE_DIST_CACHE_KEY`). Without it (a local
+ * run) the line names WHERE each workflow spells its key instead of restating
+ * one: ci.yml's and release.yml's keys differ (objectstack#20765), and a copy
+ * here would be a third spelling nothing holds in step.
  */
 function remedy(cacheKey) {
-  const key = cacheKey || '${{ runner.os }}-console-dist-${{ hashFiles(\'.objectui-sha\', \'scripts/build-console.sh\') }}';
   return [
     '  How to clear this:',
     '',
@@ -231,7 +244,14 @@ function remedy(cacheKey) {
     '    • In CI — the restored artifact is a CACHE ENTRY, not anything in this PR.',
     "      Nothing in the diff can fix it; the entry has to go. ⛔ MAINTAINER-ONLY:",
     '',
-    `          gh cache delete "${key}"`,
+    `          gh cache delete "${cacheKey || 'KEY'}"`,
+    ...(cacheKey
+      ? []
+      : [
+          '',
+          "      KEY is the key the failing job's restore step printed. ci.yml's",
+          "      `console-pin` job and release.yml's publish job each spell their own.",
+        ]),
     '',
     '      then re-run the Console Pin Gate job. The next run misses, rebuilds,',
     '      and re-stamps.',