docs(cli): the ⛔ notes over ORGANIZATIONS_RUNTIME_PKG state the reason that survives the resolver hop

packages/cli/src/commands/doctor-organizations-message-spelling.test.ts

@@ -27,14 +27,18 @@
  * is the load-bearing one (see below).
  *
  * ⚠️ The literal is still declared three times, not two: the roster key, the
- * shared module this file now reads, and `Serve.ORGANIZATIONS_RUNTIME_PKG`,
- * which must stay a string LITERAL in `serve.ts` or the host-anchoring sweep in
- * `serve-cluster-host-resolution.test.ts` can no longer resolve which package
- * that command's `import()` names. What changed is that no copy can drift in
- * silence any more: the serve↔shared pair is pinned equal by site 8 of
+ * shared module this file now reads, and `Serve.ORGANIZATIONS_RUNTIME_PKG` in
+ * `serve.ts`. ⛔ That third copy is no longer REQUIRED, and this paragraph is
+ * the fourth place that said it was. It used to read: it must stay a string
+ * LITERAL or the host-anchoring sweep in `serve-cluster-host-resolution.test.ts`
+ * can no longer resolve which package that command's `import()` names. ⭐ That
+ * died at `1ca763b60` (#12533), which taught the sweep to follow an import alias
+ * into a sibling module; whether to end the duplication is now an open,
+ * maintainer-facing decision at #12579. ⛔ None of it changes what THIS file
+ * measures. What holds either way is that no copy can drift in silence: the
+ * serve↔shared pair is pinned equal by site 8 of
  * `serve-organizations-message-spelling.test.ts`, and each copy is separately
- * pinned as a roster key. Ending the duplication needs that sweep's resolver to
- * follow one more hop — a file this card does not own.
+ * pinned as a roster key.
  *
  * ── Three legs, and the second is the point ──────────────────────────────
  *

packages/cli/src/commands/serve-organizations-message-spelling.test.ts

@@ -49,14 +49,21 @@
  * nothing at either command ever read.
  *
  * **Site 8** covers what the shared table could NOT absorb.
- * `Serve.ORGANIZATIONS_RUNTIME_PKG` deliberately stays a string LITERAL in
- * `serve.ts` (its docblock says why: `serve-cluster-host-resolution.test.ts`
- * resolves the organizations `import()` through that static and needs the
- * literal in that file, or the load drops out of the host-anchoring sweep
- * silently). So the spelling is declared twice inside `packages/cli`, and site 8
- * is what keeps that duplication CHECKED instead of silent — it asserts the two
- * declarations are equal. Each is separately pinned as a roster key, here via
+ * `Serve.ORGANIZATIONS_RUNTIME_PKG` is still a string LITERAL in `serve.ts`, so
+ * the spelling is declared twice inside `packages/cli`, and site 8 is what keeps
+ * that duplication CHECKED instead of silent — it asserts the two declarations
+ * are equal. Each is separately pinned as a roster key, here via
  * `test/serve-capability-vocabulary.test.ts` and there via doctor's leg (ii).
+ *
+ * ⚠️ This paragraph used to say the literal HAD to stay, because
+ * `serve-cluster-host-resolution.test.ts` resolved the organizations `import()`
+ * through that static and needed the literal in that file or the load dropped
+ * out of the host-anchoring sweep silently. ⭐ That reason died at `1ca763b60`
+ * (#12533): the sweep now follows an import alias into a sibling module. Site 8
+ * never rested on it — while there are two declarations the pin has a subject,
+ * whichever way the open decision at #12579 goes — so ⛔ do not delete site 8 to
+ * "finish" that decision. It falls with its subject or not at all. The reading
+ * of what survives the hop is on `Serve.ORGANIZATIONS_RUNTIME_PKG`'s docblock.
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';

packages/cli/src/commands/serve.ts

@@ -516,30 +516,55 @@ export default class Serve extends Command {
  * Exposed as a static for the same reason ALWAYS_ON_CAPABILITIES above is:
  * one declaration, two readers — the boot path and the pin.
  *
- * ⛔ This MUST stay a string LITERAL in this file — do not turn it into a
- * re-export of `../utils/tenancy-posture-hints.ts`, however tempting that is
- * now that the posture hints live there (#12492).
+ * ── A ⛔ stood here, and the constraint it named no longer exists ─────────
  *
- * `serve-cluster-host-resolution.test.ts` sweeps this file for every dynamic
- * `import()` and proves each app-declarable one is host-anchored. To do that
- * it must know WHICH package a load site names, and the organizations load is
- * spelled `const organizationsPkg = Serve.ORGANIZATIONS_RUNTIME_PKG;` — so the
- * sweep resolves the identifier one hop, to this static, and then reads the
- * literal. Written as `= SOME_IMPORTED_CONST`, the literal is no longer in
- * this file, the specifier becomes unresolvable, and that load drops OUT of
- * the swept population rather than failing inside it. That is the exact
- * silent-vacuity failure #11614 already paid for once; the named half of that
- * sweep's vacuity guard is what catches it, and it does (measured on this
- * card, which tried the re-export and was refused by it).
+ * ⚠️ Until #12579 this read: MUST stay a string LITERAL in this file, because
+ * `serve-cluster-host-resolution.test.ts` sweeps `serve.ts` for every dynamic
+ * `import()`, resolves the organizations load — spelled
+ * `const organizationsPkg = Serve.ORGANIZATIONS_RUNTIME_PKG;` — one hop to
+ * this static and then reads the literal. Written as `= SOME_IMPORTED_CONST`
+ * the specifier stopped resolving and that load dropped OUT of the swept
+ * population rather than failing inside it: the silent-vacuity failure #11614
+ * paid for once. That was not reasoned, it was MEASURED — #12492 tried exactly
+ * that rewrite and the named half of the sweep's vacuity guard refused it, by
+ * name.
  *
- * The consequence is that the spelling is declared twice inside this package
- * — here, and in the shared hints module `os doctor` also reads. That
- * duplication is CHECKED, not silent: `serve-organizations-message-spelling.test.ts`
- * asserts the two are equal, and each is independently pinned as a key of the
- * spec-owned roster (here via `test/serve-capability-vocabulary.test.ts`,
- * there via `doctor-organizations-message-spelling.test.ts`). Single-sourcing
- * it properly needs that sweep's resolver to follow one more hop, into a
- * sibling module — an edit to a file this card does not own.
+ * ⭐ It stopped being true at `1ca763b60` (#12533, PR #12582), which taught
+ * `resolveIdentifier()` a third hop: an import alias to a literal in a sibling
+ * module of the SAME package. `= SOME_IMPORTED_CONST` is now a shape it
+ * resolves, and that is pinned rather than inferred — against the REAL
+ * `../utils/tenancy-posture-hints.ts` read through this file's own scan
+ * context, in the case named "resolves an alias to a literal in a REAL sibling
+ * module of packages/cli", and again in "resolves `static readonly MEMBER =
+ * <alias>` — the shape the refactor writes".
+ *
+ * ⛔ Both halves are recorded rather than the whole note deleted, because a
+ * reader who meets neither re-derives the dead constraint from the duplication
+ * and puts the ⛔ back. ⛔ Nor is that hop dead code for having no live caller:
+ * delete it and this file is one refactor away from emptying the sweep again.
+ *
+ * ── What holds today, which is less than a prohibition ───────────────────
+ *
+ * The spelling is declared twice inside this package — here, and in the shared
+ * hints module `os doctor` also reads. That duplication is CHECKED, not
+ * silent: `serve-organizations-message-spelling.test.ts` site 8 asserts the two
+ * are EQUAL, and each is independently pinned as a key of the spec-owned
+ * roster (here via `test/serve-capability-vocabulary.test.ts`, there via
+ * `doctor-organizations-message-spelling.test.ts`). All three read this
+ * static's VALUE, never this file's source text, so none of them is a reason
+ * for the literal — and #12579 measured that the sweep was the only thing in
+ * the tree that ever read this file's source for a package spelling.
+ *
+ * ⚠️ So the honest state is that nothing forbids single-sourcing this any
+ * more, and ⛔ that is still not a licence to do it in passing. PR #12532
+ * shipped the duplication deliberately with the reasoning at both ends, which
+ * makes ending it a maintainer-facing decision — open at #12579, where what
+ * would have to move together is written down. Two things outlive that
+ * decision either way: this static keeps its NAME (the roster pins address
+ * `Serve.ORGANIZATIONS_RUNTIME_PKG`, and only a spelling may move), and the
+ * gap is ⛔ never closed in the other direction — see the ⛔ on
+ * `ORGANIZATIONS_RUNTIME_PKG` in `../utils/tenancy-posture-hints.ts`, whose
+ * reason (#12464) the hop did not touch.
  *
  * This single-sources the SPELLING and nothing else. Which postures load the
  * runtime, and what each of the two failure stages means, stay exactly where

packages/cli/src/utils/tenancy-posture-hints.ts

@@ -59,16 +59,19 @@
  * The `plugins[]`-wired multi-org runtime both commands NAME in their posture
  * advice, spelled once FOR THIS TABLE (#11614 → #12464 → #12492).
  *
- * ⚠️ This is not the only declaration of the literal inside `packages/cli`, and
- * that is a measured constraint rather than an oversight. `serve.ts` keeps its
- * own `Serve.ORGANIZATIONS_RUNTIME_PKG` literal because
- * `serve-cluster-host-resolution.test.ts` sweeps `serve.ts` for every dynamic
- * `import()` and resolves the organizations load site through that static to a
- * LITERAL IN THAT FILE. Rewrite the static as a re-export of this const and the
- * specifier stops resolving, so that load drops OUT of the host-anchoring sweep
- * instead of failing inside it — the silent-vacuity mode #11614 already paid
- * for. This card tried exactly that and the sweep's named vacuity guard refused
- * it, by name, which is the guard working.
+ * ⚠️ This is not the only declaration of the literal inside `packages/cli`:
+ * `serve.ts` keeps its own `Serve.ORGANIZATIONS_RUNTIME_PKG` literal. ⛔ Do not
+ * read that as a live constraint on this file. It WAS one — the host-anchoring
+ * sweep in `serve-cluster-host-resolution.test.ts` resolved the organizations
+ * load site through that static to a LITERAL IN THAT FILE, so rewriting the
+ * static as a re-export of this const stopped the specifier resolving and
+ * dropped that load OUT of the sweep instead of failing inside it (#11614's
+ * silent-vacuity mode; #12492 tried it and the sweep's named vacuity guard
+ * refused it, by name). ⭐ That reason died at `1ca763b60` (#12533, PR #12582):
+ * the sweep now follows an import alias into a sibling module of the same
+ * package, and it pins that hop against THIS FILE by name. The full reading
+ * lives on `Serve.ORGANIZATIONS_RUNTIME_PKG`; ⛔ do not restate it here — it is
+ * one reason, and #12579 exists because it had four copies.
  *
  * ⭐ So the spelling is declared twice in this package, and both copies are
  * CHECKED rather than silent — a duplicate that can drift unnoticed and one
@@ -79,12 +82,12 @@
  * (`doctor-organizations-message-spelling.test.ts`, leg (ii)).
  * · serve's is a key of the same roster (`test/serve-capability-vocabulary.test.ts`).
  *
- * Ending the duplication for real needs that sweep's `resolveIdentifier()` to
- * follow one further hop — an import alias into a sibling module — which is an
- * edit to a file #12492 does not own, and which was in flight elsewhere when
- * this landed. It is a two-line change to a resolver whose own docblock records
- * that resolving one hop further "strictly WIDENS what the sweep judges; it can
- * never excuse a load".
+ * Ending the duplication for real is now POSSIBLE — the further hop it was
+ * waiting on landed, and single-sourcing the spelling into this module is the
+ * only live consumer it would have. ⛔ Possible is not decided: PR #12532
+ * shipped this duplication deliberately with the reasoning at both ends, so
+ * reversing it is a maintainer-facing call. It is open at #12579, which carries
+ * the list of what would have to move in one diff.
  *
  * ⛔ Do NOT close the gap by importing `Serve.ORGANIZATIONS_RUNTIME_PKG` here
  * instead: this module is read by `os doctor`, and a diagnostic command taking a