docs(cloud-connection): controlPlaneUrl's docblock says '' keeps requests on this origin, not that this runtime is the cloud (#22035)

Fixes #22028
Clause-②: no

## What changed

`controlPlaneUrl: ''` had two meanings in this package's own docs. The
exported `RuntimeConfigPluginConfig.controlPlaneUrl` docblock said `''`
declares "this runtime IS the cloud". The constructor, the README and
the CLI's `Serve.RUNTIME_CONFIG_OPTIONS` docblock say "stay on this
origin". The CLI's cloud-connected `os serve` passes `''` while its
`MarketplaceProxyPlugin` forwards to the control plane
`resolveCloudUrl()` answers, so the first reading is false on the
product path. objectui read the first reading and shipped a wrong
marketplace hint (objectui#11726).

Three comments now say what the constructor does. Comment lines only:

- `packages/cloud-connection/src/runtime-config-plugin.ts`: the exported
`RuntimeConfigPluginConfig.controlPlaneUrl` docblock. `''` keeps
marketplace and install requests on this origin, and that is all it
says. The runtime may serve the catalog itself or proxy a control plane
it does not name, so `''` reads neither as "this runtime is the cloud"
nor as "there is no upstream". One more sentence points a host with no
control plane at the decline spellings (`'off'` / `'none'` / `'local'` /
`'disabled'`), in this option or in `OS_CLOUD_URL`. That is what
`declinesControlPlane()` reads.
- `packages/cloud-connection/src/cloud-url.ts`:
`isControlPlaneDeclined`'s docblock. `''` is how a host says "keep
requests on this origin", and that says where requests go, not who
serves them.
- `packages/cloud-connection/src/runtime-config-telemetry.test.ts`: one
test comment. It also said `resolveCloudUrl()` returns `''` for a host's
empty string. It does not: the resolver maps `''` to the public default,
and the constructor special-cases `''` before calling it. The comment
now names the served `cloudUrl` instead. The test's code and title are
unchanged.
- `.changeset/22028-control-plane-url-docblock.md`:
`@objectstack/cloud-connection` `patch`, because the docblock ships in
the published `.d.ts` (shown below).

The wording matches what objectui PR #11740 (merged `d172f636e2`) landed
for `AppShellRuntimeConfig.cloudUrl` in
`packages/app-shell/src/runtime-config.ts`: "Empty string ⇒ requests
stay on this origin, and that is all it says: the runtime may serve the
catalog itself or proxy a control plane it does not name … read `''`
neither as "this runtime is the cloud" nor as "there is no upstream"."

## Re-grep (H1)

`git grep -n -i "is the cloud"` on `origin/main` `b88c356413` gives 23
hits. Exactly three state the first reading. They are the three sites
above. The other 20 use "is the cloud" in another sense ("the producer
is the cloud control plane", "this is the cloud-deployable path", "the
cloud#1838 turn"). Six of them are released `CHANGELOG.md` entries,
which stay untouched. A wider grep for close spellings ("acts as the
cloud", "its own control plane", "serves the catalog itself",
"same-origin for marketplace", "IS the control plane",
"controlPlaneUrl.*empty string") found no other comment stating the
first reading. Already consistent and left alone:
`runtime-config-plugin.ts:14` ("'' = same origin"), the constructor
comment, `README.md:53`, and `serve.ts:1706`.

After the change, the only "is the cloud" text left in
`packages/cloud-connection/src` is the two new negations ("read `''`
neither as "this runtime is the cloud" …"). The changeset quotes the old
phrase once and the negation once. Repo-wide count after: 24.

## The docblock ships, and only the docblock moved (H3, H4)

`pnpm turbo run build --filter=@objectstack/cloud-connection` was run at
`b88c356413` (before), then `pnpm --filter @objectstack/cloud-connection
build` at `658eba9a` (after).

Before, `dist/index.d.ts` lines 1652–1658 (`index.d.cts` is the same):

```text
    /**
     * Upstream cloud base URL. Falls back to `resolveCloudUrl()` (reads
     * `OS_CLOUD_URL` / built-in default) when omitted. Pass an explicit
     * empty string to declare "this runtime IS the cloud" (same-origin
     * for marketplace + install).
     */
    controlPlaneUrl?: string;
```

After, `dist/index.d.ts` lines 1652–1666 (`index.d.cts` is
byte-identical):

```text
    /**
     * Upstream cloud base URL. Falls back to `resolveCloudUrl()` (reads
     * `OS_CLOUD_URL` / built-in default) when omitted. Pass an explicit
     * empty string to keep marketplace and install requests on this origin:
     * the constructor serves `cloudUrl: ''` without calling the resolver, and
     * that is all `''` says. The runtime may serve the catalog itself or
     * proxy a control plane it does not name — the CLI's cloud-connected
     * `os serve` passes `''` while its marketplace proxy forwards to the
     * control plane `resolveCloudUrl()` answers (objectui#11726) — so read
     * `''` neither as "this runtime is the cloud" nor as "there is no
     * upstream". A runtime with no control plane says so with a decline
     * spelling (`'off'` / `'none'` / `'local'` / `'disabled'`), here or in
     * `OS_CLOUD_URL`.
     */
    controlPlaneUrl?: string;
```

`grep -c "IS the cloud"` on `dist/index.d.ts` gives 1 before and 0
after. `isControlPlaneDeclined` is not exported from `src/index.ts`, so
its docblock appears in no `dist/` file (0 hits before and after). Only
the `controlPlaneUrl` docblock is published.

No behaviour moved:

- sha256 of the built JS is the same before and after: `dist/index.js`
`4086b9fa3c44…` and `dist/index.cjs` `b038ae248df8…`. Only
`dist/index.d.ts` / `index.d.cts` changed (`84a224f2a433…` →
`a14155bd55a7…`).
- `git diff b88c356...HEAD -- '*.ts'` changes 25 lines (+19 / −6).
Every one matches a comment-line pattern (a line starting with `*` or
`//` after `+` / `-` and whitespace). A grep for any changed line
outside that pattern returns nothing (exit 1).
- `pnpm --filter @objectstack/cloud-connection test`: `Test Files 41
passed (41)`, `Tests 505 passed (505)`.
- `pnpm --filter @objectstack/cloud-connection typecheck` (`tsc --noEmit
&& tsc --noEmit -p tsconfig.test.json`): exit 0. `--listFiles` shows
`runtime-config-telemetry.test.ts` in the test program.

## Gates

All on `658eba9a` (`git rev-parse --short HEAD`), the final commit:

- `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--commands` derived 62 commands from the actual change set (4 paths vs
merge base `b88c35641`). That list is identical to the dispatch's list.
Each command's exit code was recorded as it ran. `--ran` reconciles to
"62 derived famil(ies) accounted for — 62 run, 0 NOT-MEASURED (a DERIVED
zero — all 62 recorded an exit code and none of them is 3)".
- First pass: `pnpm check:dual-build-cjs-loads` exited 3 (`PREREQUISITE
NOT MET`: packages without `dist/`). After `pnpm turbo run build
--filter=!@objectstack/docs --concurrency=2` (72 tasks, exit 0) it
re-ran green: "106 published require entry point(s) across 66 package(s)
load". The other 61 exited 0 on the first pass.
- `pnpm lint` (the full `eslint . --no-inline-config`): exit 0, no
output.
- Verdict lines include: `check-nul-bytes: OK (scanned 10035 text
file(s) … no raw ASCII control bytes)`; `check-issue-citations: every
citation this change adds resolves (or is a declared cross-repo
reference)` (the one added citation, `objectui#11726`, is cross-repo);
`check-adr-0087-registration: this PR adds no declared-breaking
changeset`; `This diff introduces no major bump`; `No empty-frontmatter
changeset introduced by this diff`.
- Package suite and typecheck: see the section above.

## Acceptance notes

- Out of scope and unchanged: whether the runtime config should name the
upstream plane. objectui#11726's grade ruled out a new key. This PR adds
none.
- The test comment's next sentence ("Reading the posture off that would
silence the hosted console — the one deployment that legitimately
configures a sink.") is left as written. It does not state the first
reading.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01RWZbGvPFcRKvUqASZtunCU)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/22028-control-plane-url-docblock.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/cloud-connection": patch
+---
+
+`RuntimeConfigPluginConfig.controlPlaneUrl`'s published docblock no longer says that an empty string declares "this runtime IS the cloud". It now says what the constructor does: `''` keeps marketplace and install requests on this origin, and that is all it says.
+
+Clause-②: no
+
+- The runtime that passes `''` may serve the catalog itself or proxy a control plane it does not name. The CLI's cloud-connected `os serve` passes `''` while its marketplace proxy forwards to the control plane `resolveCloudUrl()` answers. So `''` reads neither as "this runtime is the cloud" nor as "there is no upstream". This matches the `AppShellRuntimeConfig.cloudUrl` doc in `@object-ui/app-shell`.
+- A runtime with no control plane says so with a decline spelling (`'off'` / `'none'` / `'local'` / `'disabled'`), in `controlPlaneUrl` or in `OS_CLOUD_URL`. The docblock now says this too.
+- ⛔ No code, type, export or default change. The served `cloudUrl` and the telemetry posture do not change.

packages/cloud-connection/src/cloud-url.ts

@@ -52,9 +52,12 @@ export function resolveCloudUrl(explicit?: string | null): string {
  *
  * That test conflates two opposite deployments, and the conflation is not
  * theoretical — it is what every CLI-served runtime looks like. `''` is also
- * how a host says **"this runtime IS the cloud"** (same origin), which
+ * how a host says **"keep requests on this origin"**, which
  * `RuntimeConfigPlugin`'s constructor special-cases before it ever calls the
- * resolver. Measured on `main`: `Serve.RUNTIME_CONFIG_OPTIONS` passes
+ * resolver. That says where requests go, not who serves them: the runtime may
+ * serve the catalog itself or proxy a control plane it does not name, so `''`
+ * reads neither as "this runtime is the cloud" nor as "there is no upstream".
+ * Measured on `main`: `Serve.RUNTIME_CONFIG_OPTIONS` passes
  * `controlPlaneUrl: ''` on **both** the cloud-connected arm and the air-gapped
  * arm of the CLI's marketplace wiring, so the resolved URL carries no posture
  * information whatsoever on the product path. A posture read built on it would

packages/cloud-connection/src/runtime-config-plugin.ts

@@ -501,8 +501,16 @@ export interface RuntimeConfigPluginConfig {
     /**
      * Upstream cloud base URL. Falls back to `resolveCloudUrl()` (reads
      * `OS_CLOUD_URL` / built-in default) when omitted. Pass an explicit
-     * empty string to declare "this runtime IS the cloud" (same-origin
-     * for marketplace + install).
+     * empty string to keep marketplace and install requests on this origin:
+     * the constructor serves `cloudUrl: ''` without calling the resolver, and
+     * that is all `''` says. The runtime may serve the catalog itself or
+     * proxy a control plane it does not name — the CLI's cloud-connected
+     * `os serve` passes `''` while its marketplace proxy forwards to the
+     * control plane `resolveCloudUrl()` answers (objectui#11726) — so read
+     * `''` neither as "this runtime is the cloud" nor as "there is no
+     * upstream". A runtime with no control plane says so with a decline
+     * spelling (`'off'` / `'none'` / `'local'` / `'disabled'`), here or in
+     * `OS_CLOUD_URL`.
      */
     controlPlaneUrl?: string;
     /**

packages/cloud-connection/src/runtime-config-telemetry.test.ts

@@ -197,8 +197,10 @@ describe('RuntimeConfigPlugin — telemetry.errorReporting (#12681)', () => {
         });
 
         it('a same-origin runtime (controlPlaneUrl: "") is NOT a declined control plane', async () => {
-            // The conflation this must not inherit: `resolveCloudUrl()` returns
-            // '' both for "this runtime IS the cloud" and for `OS_CLOUD_URL=off`.
+            // The conflation this must not inherit: the served `cloudUrl` is ''
+            // both for "keep requests on this origin" (`controlPlaneUrl: ''`,
+            // which the CLI's cloud-connected arm passes while proxying a
+            // control plane) and for `OS_CLOUD_URL=off`.
             // Reading the posture off that would silence the hosted console —
             // the one deployment that legitimately configures a sink.
             process.env[CLIENT_ERROR_REPORTING_DSN_ENV] = DSN;