From 40ce969b1c0e6937a40aaffb1eb37fa0114c278b Mon Sep 17 00:00:00 2001 From: os-litant Date: Thu, 27 Aug 2026 02:01:09 +0000 Subject: [PATCH] =?UTF-8?q?docs(cli):=20retire=20the=20sweep-vacuity=20rea?= =?UTF-8?q?son=20from=20all=20four=20=E2=9B=94=20notes=20over=20ORGANIZATI?= =?UTF-8?q?ONS=5FRUNTIME=5FPKG?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The organizations package spelling is declared twice inside `packages/cli`, and four docblocks explained why with the same reason: the host-anchoring sweep in `serve-cluster-host-resolution.test.ts` resolved the load through `Serve.ORGANIZATIONS_RUNTIME_PKG` and needed a LITERAL in `serve.ts`, or the load dropped out of the swept population silently. That reason died at `1ca763b60` (#12533, PR #12582), which taught `resolveIdentifier()` to follow an import alias into a sibling module of the same package. A true prohibition carrying a false explanation is worse than no note: the next author reads it as arbitrary and steps over it. Comment-only. Each note now records the constraint, the commit that retired it, and what actually survives — the duplication is CHECKED rather than required, and whether to end it is an open maintainer-facing decision (#12579). The ⛔ in `tenancy-posture-hints.ts` against importing `Serve.ORGANIZATIONS_RUNTIME_PKG` into the shared module is untouched: its reason is #12464's coupling ruling, not the sweep. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd --- ...tor-organizations-message-spelling.test.ts | 18 +++-- ...rve-organizations-message-spelling.test.ts | 21 ++++-- packages/cli/src/commands/serve.ts | 69 +++++++++++++------ .../cli/src/utils/tenancy-posture-hints.ts | 35 +++++----- 4 files changed, 91 insertions(+), 52 deletions(-) diff --git a/packages/cli/src/commands/doctor-organizations-message-spelling.test.ts b/packages/cli/src/commands/doctor-organizations-message-spelling.test.ts index aa8d0384b3..4555c41ce3 100644 --- a/packages/cli/src/commands/doctor-organizations-message-spelling.test.ts +++ b/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 ────────────────────────────── * diff --git a/packages/cli/src/commands/serve-organizations-message-spelling.test.ts b/packages/cli/src/commands/serve-organizations-message-spelling.test.ts index 68b66e502d..d63be1fb6b 100644 --- a/packages/cli/src/commands/serve-organizations-message-spelling.test.ts +++ b/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'; diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts index 12f79c1f6b..906eaf46db 100644 --- a/packages/cli/src/commands/serve.ts +++ b/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 = + * ` — 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 diff --git a/packages/cli/src/utils/tenancy-posture-hints.ts b/packages/cli/src/utils/tenancy-posture-hints.ts index eb4b32afee..0038ea3170 100644 --- a/packages/cli/src/utils/tenancy-posture-hints.ts +++ b/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