docs(cloud-connection): re-anchor the dead tracker citations in packages/cloud-connection/src to the commits that decided them (#20735)

Part of #20594
Clause-②: no

## What changed

This is stage 9 of the `domain:cli` lane of the dead-citation sweep:
`packages/cloud-connection/src`. Every comment site there that cited a
tracker number answering 404 now cites, in ruling C+D's form C (comment
5749154545 on #19123), the commit in this repository's history that
decided what the line describes, and keeps saying in its own words what
that commit decided. PR #20533 is the method, and stages 1 to 8 of this
card (PR #20624, PR #20632, PR #20656, PR #20673, PR #20689, PR #20703,
PR #20713, PR #20723) are the precedents. The card stays open for the
lane's remaining packages, so this PR says `Part of`.

That is **10 sites on 10 lines in 3 files, covering 3 numbers**,
rewritten to **3 distinct commits**:
- the census's **5 sites**, all in
`src/marketplace-install-local-plugin.ts` (3 numbers);
- **5 test-file comment sites** in 2 test files (the census defers
`*.test.ts`; stages 1 to 8 took test comments too).

Only comments changed: **10 lines out, 10 in**, and every touched file
keeps its line count (1,969 / 377 / 308), so no line citation into these
files moves. **No citation number is added**: over the 10 line pairs,
added-minus-removed numbers is empty, and no PR number stands on an
added line. No ADR or ruling-record file in `docs/adr/` or
`scripts/adr-anchors/` records any of these 3 decisions (a grep for the
3 numbers there reads 0 hits, with a control number from the same tree,
`#7329`, reading 1), so every anchor is a commit.

A **`patch` changeset** for `@objectstack/cloud-connection` rides along,
because the rewritten docblocks reach `dist` (measured below). That is
stage 6's case (PR #20703), not stages 5 and 7's.

## Census: `packages/cloud-connection`, before and after

**Instrument.** The gate's own `node scripts/check-issue-citations.mjs
--census --json`, read-only and unchanged, run under `with-fleet.sh
--read` for the token. The count is its `allocated-but-absent` findings
under `packages/cloud-connection/`. Both runs enumerated the whole
board.

| reading | tree | board | whole-repo `allocated-but-absent` |
`packages/cloud-connection` sites | lines | numbers | files |
|---|---|---|---|---|---|---|---|
| before | base `b291fcdae9`, run 2026-09-29T22:34:12Z to 22:38:18Z |
enumerated, 186 pages, frontier #20731, 18,558 numbers | 1,153 | **5** |
5 | 3 | 1 |
| after | `4a1f38a4e6`, run 22:44:08Z to 22:47:58Z | enumerated, 186
pages, frontier #20731, 18,558 numbers | 1,148 | **0** | 0 | 0 | 0 |

The whole-repo drop of 5 is exactly these sites: a site-by-site diff of
the two JSON outputs has 5 findings gone, all in
`packages/cloud-connection/src/marketplace-install-local-plugin.ts`, and
none added. The other three tallies (`resolves` 32,994,
`resolves-as-pull-request` 1,984, `cross-repo-unjudged` 995) are equal
in both runs. `packages/cloud-connection/src` is byte-identical at
`4a1f38a4e6` and at the head.

**Supplementary scan (test files included).** The gate's exported
`extractCitations` and `classifyCitation` over all 44 `.ts` files under
`src/`, with the board from the gate's own `probeBoard`: 301 citations
and 14 dead before (src comments 5, test comments 5, src strings 1, test
strings 3), 291 and 4 after (0, 0, 1, 3). Its before list of src comment
sites is identical to the census's. The 4 left are strings, the form-D
stage (see Acceptance notes).

## Per-site table

`git blame` at the base ties each line to the commit that wrote it, and
each anchor was read in its message, changeset or diff, not only its
subject.

| number | sites (base line) | anchor: what it decided |
|---|---|---|
| `#9011` | `marketplace-install-local-plugin.ts:35`, `:1001`, `:1821`;
`marketplace-install-local-capability-enumeration.test.ts:50`, `:303`;
`marketplace-install-local-list-posture.test.ts:4`, `:302` |
`01074e551`: the install-local listing requires an authenticated
principal (anonymous gets 401) and serves `installedBy` / `storageDir`
only to a `manage_metadata` holder, the maintainer's 2026-08-16 "Option
3" that `:1008` still names; it also extracts the one
`refuseUnauthenticated` 401 envelope that `:1821` describes. All seven
lines blame to it. The PR that landed it (PR #9256, which answers 200)
names #9011 on its first line. `list-posture.test.ts:302` now reads "The
wire shape before commit 01074e5" for "The pre-(number) wire shape". |
| `#8919` | `marketplace-install-local-plugin.ts:98`;
`marketplace-install-local-capability-enumeration.test.ts:40` |
`b5378550e`: gates the `/meta` publish and rollback promotion verbs on
`manage_metadata` and adds
`meta-write-door-capability-enumeration.test.ts`, the enumeration pin
`:40` names as its precedent. Both lines blame to `e0695b582`, the
commit that gated the four mutating install-local doors for #8976 (which
answers 200), whose message cites this gate as the precedent. Stages 2
and 5 gave the number this anchor. The PR that landed `b5378550e`
answers 404 too. |
| `#13279` | `marketplace-install-local-plugin.ts:1813` | `6a180e42d`: a
failed permission-store read raises `AuthzStoreUnavailableError` instead
of resolving as an unauthenticated or capability-less principal, and
each fail-closed transport `catch` re-raises it. The line blames to it;
PR #13475 names #13279. Stages 1, 2 and 4 gave the number this anchor. |

**Anchor checks.** Every cited sha matches exactly one object (`git
rev-parse --disambiguate`, count 1 for each of the 3), is a commit, has
one parent, and is an ancestor of `main` (`merge-base --is-ancestor`
against `36d043be17`, exit 0 for all 3). The checkout is not shallow.
The control leg `818fcafda` (2026-08-16, the parent of the oldest anchor
`b5378550e` of 2026-08-16) exits 0, and the negative control, this
branch's own `16a88d69b2`, exits 1. Two anchors reuse the landed stages'
(`b5378550e`, `6a180e42d`), so each number carries one anchor across the
tree; one is new (`01074e551`).

**Numbers.** All 3 dropped numbers answer 404 by REST (probed
2026-09-29T22:40:35Z). The numbers kept near the changed lines (`#8976`,
`#15353`) answer 200. Three slash-joined groups stand in
`packages/cloud-connection/src`, whose later halves the citation grammar
does not read (`#6603/#7020`, `#4127/#4251` twice); every half answers
200, so none is dead.

## Mechanical guard: no code token moves

**H2 holds on the comment-stripped reading; the emitted `dist` is NOT
byte-identical, because the docblocks ship.**

**Token guard.** It compares the TypeScript parser's leaf tokens
(TypeScript 6.0.3, JSDoc nodes excluded) of the 3 touched files at base
`b291fcdae9` and at `4a1f38a4e6`. Controls mutate the head text in
memory only.
- Real run: 12,349 base tokens (8,351 / 2,246 / 1,752), 0 differing
(exit 0 for each file).
- Comment-insertion control: 0 differing (exit 0).
- Code-insertion control: all 3 files differ (exit 1).
- String control (`'Authentication required.'` to `'Authentication
requireD.'` in `refuseUnauthenticated`): exactly 1 differing
`StringLiteral`, at token 7,973 of `marketplace-install-local-plugin.ts`
(exit 1).

**Emitted `dist`.** `pnpm --filter @objectstack/cloud-connection build`
at the head, then at base (the base tree of
`packages/cloud-connection/src` restored in place under a trap-armed
restore; an on-disk probe read `[#13279]` 1 and `commit 6a180e4` 0
before that build; afterwards every touched blob equals its HEAD blob
and `git diff HEAD` is empty), with the same dependency builds:
- `index.cjs`, `index.js`, `index.d.ts` and `index.d.cts` differ;
`index.cjs.map` and `index.js.map` are equal.
- The same parser comparison over the four differing `dist` files reads
0 differing tokens (19,465 / 18,741 / 16,868 / 16,868), so the whole
`dist` delta is comment text. Its code control (a code line appended
after a newline) reads COUNT DIFFERS in each.
- The new wording is in `dist`: "commit 01074e5" appears 2 times in
`index.js` and `index.cjs` and 3 times in each declaration file, where
the base build carries `#9011` in the same places.
- Code-mutation control (`scripts/ablation-replace.mjs`, anchor
`'Authentication required.'` hit 1 to 0, planted marker 0 to 1, blob
`2ef0f0ae8bac` to `77c3cef6324b`; `scripts/ablation-dist-preflight.mjs`
found the marker in `dist`): `index.cjs`, `index.js` and both `.map`
files differ from the head build. The blob was restored to HEAD
`2ef0f0ae8bac` with `git diff HEAD` empty, `dist` was rebuilt, its six
sha256 values equal the first head build, and the preflight in
`--absent` mode reads the marker absent from all 6 files with a clean
tree.

A raw scan of the 4 changed files for control bytes finds none (a
positive probe on a scratch file matched).

## Changeset

**`patch` for `@objectstack/cloud-connection`**
(`.changeset/cloud-connection-provenance-anchors.md`), in PR #20632's
form. `@objectstack/cloud-connection`'s `files[]` is `dist`, `README.md`
and `CHANGELOG.md`, and the build above emits different `index.js` /
`index.cjs` / `index.d.ts` / `index.d.cts` at base and head, so this
diff publishes. `check-changeset-no-major`, `check-empty-changeset`,
`check-adr-0087-registration` and `check-changeset-fixed` all exit 0.

## Gates (head `16a88d69b2`)

This host has no `flock`, so `os-verify-lock.sh` ran in its declared
unlocked mode. Its disclosure, verbatim, from each run (the closure
build at `4a1f38a4e6`, whose `packages/cloud-connection` and dependency
closure are byte-identical to this head; the whole-workspace build, the
tests and the typecheck at this head; the three `dist` builds at
`4a1f38a4e6`, whose `packages/cloud-connection/src` is byte-identical to
this head):

```text
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 59s · declare it in the PR body · pnpm --workspace-concurrency=2 --filter '@objectstack/cloud-connection...' build
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 118s (1m58s) · declare it in the PR body · pnpm turbo run build --filter='./packages/*' --filter='./packages/*/*' --concurrency=2
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 11s · declare it in the PR body · pnpm --filter @objectstack/cloud-connection exec vitest run --maxWorkers=2
os-verify-lock: VERDICT command-exit 2 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 2s · declare it in the PR body · pnpm exec tsc --noEmit -p tsconfig.json --listFiles
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 3s · declare it in the PR body · pnpm --filter @objectstack/cloud-connection build
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 3s · declare it in the PR body · pnpm --filter @objectstack/cloud-connection build
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 3s · declare it in the PR body · pnpm --filter @objectstack/cloud-connection build
```

- **Build:** `@objectstack/cloud-connection` with its closure (33 of 81
workspace projects), then the whole workspace, `turbo run build
--filter='./packages/*' --filter='./packages/*/*'`, 71 of 71 tasks,
after the merge. The tree was clean after both, and the package's six
`dist` files after the whole build equal the first head build by sha256.
- **Tests:** `vitest run`: 30 files, 397 tests passed (every `*.test.ts`
under `src/`), at this head and before the merge.
- **Typecheck:** `@objectstack/cloud-connection` has no `typecheck`
script; it is a `DEBT` entry in `scripts/check-type-check-coverage.mjs`
(13 errors: 11 TS2493, 2 config-tier). `tsc --noEmit -p tsconfig.json`
exits 2 with exactly those 13 (11 TS2493, 2 TS2550), all in three test
files this PR does not touch (`cloud-connection-plugin.test.ts` 4,
`connection-credential-store.test.ts` 7,
`marketplace-install-local-bundle.test.ts` 2). `--listFiles` compiles
all three touched files and all 30 test files. `check:type-check-debt`
and `check:type-check-coverage` exit 0, and the `dist` build's DTS step,
this package's type gate, succeeds.
- **Lint:** the repo-wide `pnpm lint` (`eslint . --no-inline-config`)
exits 0 at this head (2026-09-29T23:01:12Z to 23:01:39Z).
- **Citation judging:** after merging `origin/main` (`36d043be17`),
`node scripts/check-issue-citations.mjs --base origin/main` reports "no
issue citations added against 36d043b (1 file(s) read)" (exit 0);
pinned `--base 36d043b` reads the same.
- **Derived gates:** `node scripts/pm/dispatch-gates.mjs --repo
objectstack-ai/objectstack --commands` derived 61 families. All 61 exit
0, and `--ran` with the exit-coded record reads "61 derived, 61 run, 0
NOT-MEASURED, 0 UNRUN" (a derived zero). Among them:
`check:issue-citations`, `check:doc-authoring`, `check:nul-bytes`,
`check:published-files`, `check:type-check-debt`,
`check-adr-0087-registration`, `check-empty-changeset`.
- **Artifact rosters:** 36 of the 39 non-self-test roster rows exit 0,
including the four the derivation marks as keeping their roster under
one of this diff's paths (`check-changeset-fixed`,
`check:authz-resolver`, `check:error-code-casing`,
`check:filter-alias-parity`). The other three need a pull request's
context; they are run against this PR once it exists and reported on the
card. The 18 self-test-only rows grade their checkers' fixtures and
cannot judge this diff.

## Hypotheses (measured first)

- **H0 holds.** At base `b291fcdae9` the filtered census answers 5 sites
on 5 lines, 3 numbers, all in `src/marketplace-install-local-plugin.ts`,
as on the seat's `0be898499f`. The whole-repo count is 1,153.
- **H1 holds.** After the rewrite, the filtered census answers 0 for
`packages/cloud-connection`. No site was left for an open PR (the file
lists of all 10 open PRs were read at 2026-09-29T22:41:18Z: only the
Version Packages PR #20639 touches `packages/cloud-connection`, in
`CHANGELOG.md` and `package.json`) or for an unfound anchor.
- **H2 holds on the token reading, not on the `dist` reading.** The
parser leaf-token diff of all 3 touched files is empty with its controls
firing. The emitted `dist` differs, and the difference is comment text
only (token-identical `dist` with a code control). That is why the
changeset ships.

## Acceptance notes

- **Strings, the form-D stage.** 4 dead numbers remain in string
literals in `packages/cloud-connection/src`: `#9011` in the three
`describe` titles of `marketplace-install-local-list-posture.test.ts`
(`:206`, `:247`, `:287`, no assertion text), and `#9011` in the `note`
string of the `GET /api/v1/marketplace/install-local` row of
`cloud-connection-route-ledger.ts` (`:215`), a runtime string already
recorded in `scripts/doc-authoring-prose-id.baseline.json`. They stay on
the card for its form-D stage; no string moved here.
- **Outside `src/**`, a later stage of the card:**
`packages/cloud-connection/vitest.config.ts:64` cites `#16917` (404).
The other citations in `packages/cloud-connection` outside `src/**`
(`CHANGELOG.md` excluded) answer 200: `README.md:108` (`#10805`,
`#12681`) and `vitest.config.ts` (`#10374`, `#11480`, `#7668/#7778`,
`#7955`, `#10374/#13522`).
- **Card-word residue, cited nowhere.** A few docblocks still say "this
card's ruling" or "That ruling has since landed" a paragraph away from a
rewritten line
(`marketplace-install-local-capability-enumeration.test.ts:48`,
`marketplace-install-local-list-posture.test.ts:12`). They cite no
number, so they were left, as the landed stages left theirs.
- **The moving `origin/main`.** The branch merged `origin/main` once
(`16a88d69b2`, merging `36d043be17`: `service-automation` and two
changesets, nothing in `packages/cloud-connection` or its dependency
closure).

## Deviations

- **The first token-guard run was void.** It looped over the touched
files in a zsh shell, which does not word-split an unquoted variable, so
each invocation received all three paths as one argument and read
nothing; it was rerun under bash before any reading was used.
- **Commit trailers** are AGENTS.md's model-free pair (`Claude-Session`
plus `Co-authored-by: Claude`), and the pre-push trailer check passed on
every push. The harness's attribution reminder asked for a model-named
trailer and a different PR footer, and AGENTS.md overrides it. The merge
commit carries git's default message.

---
_Generated by [Claude
Code](https://claude.ai/code/session_local_1d2a197c-c20e-4e90-9be8-413d4d432289)_

---------

Co-authored-by: Jack Zhuang <50353452+hotlong@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

.changeset/cloud-connection-provenance-anchors.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/cloud-connection': patch
+---
+
+Provenance comments in `@objectstack/cloud-connection` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the commit in this repository's history that
+decided the matter, and say in their own words what was decided. Comments
+only: no route, error code, refusal text, type, export or runtime behaviour
+changes.

packages/cloud-connection/src/marketplace-install-local-capability-enumeration.test.ts

@@ -37,7 +37,7 @@
  *
  * ## Why an enumeration and not four more assertions
  *
- * The same reason as the `/meta` precedent (#8919,
+ * The same reason as the `/meta` precedent (commit b5378550e,
  * `meta-write-door-capability-enumeration.test.ts`): a gate held by repetition
  * drifts the moment someone adds a fifth route by copying whichever neighbour
  * was nearest. `derives every mutating route the plugin mounts` builds the door
@@ -47,7 +47,7 @@
  * ⚠️ The `GET` listing is deliberately NOT in this family. It is a read, and
  * this card's ruling is about the four mutating doors; silently folding it in
  * here would have decided its posture by accident. That posture has since been
- * ruled on separately (#9011: authenticated floor, with `installedBy` and
+ * ruled on separately (commit 01074e551: authenticated floor, with `installedBy` and
  * `storageDir` narrowed to `manage_metadata` holders) and is pinned in
  * `marketplace-install-local-list-posture.test.ts` — so the filter below still
  * means "not this family", never "ungated".
@@ -300,7 +300,7 @@ describe('#8976 — the mutating install-local doors are enumerated, not recited
         // Without this, a refactor that stopped mounting the GET would leave the
         // assertion above passing while silently proving less than it claims.
         // The listing's OWN posture lives in
-        // `marketplace-install-local-list-posture.test.ts` (#9011); ⛔ the fix
+        // `marketplace-install-local-list-posture.test.ts` (commit 01074e551); ⛔ the fix
         // for an unauthorized read there is a refusal, never an unmounted route
         // — cloud#1287 made this mount unconditional so air-gapped boxes stop
         // 404ing, and this assertion is what keeps that true.

packages/cloud-connection/src/marketplace-install-local-list-posture.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * [#9011] `GET /api/v1/marketplace/install-local` — the read door's posture.
+ * [commit 01074e551] `GET /api/v1/marketplace/install-local` — the read door's posture.
  *
  * ## THIS is the file that answers "is the installed-apps LISTING gated?"
  *
@@ -299,7 +299,7 @@ describe('#9011 — a `manage_metadata` holder still gets the full payload', ()
         expect(res.payload.data.storageDir).toBe(new LocalManifestSource(dir).dir);
         const [item] = res.payload.data.items;
         expect(item.installedBy).toBe('usr_operator');
-        // The pre-#9011 wire shape, intact for the caller who is entitled to it.
+        // The wire shape before commit 01074e551, intact for the caller who is entitled to it.
         expect(Object.keys(item).sort()).toEqual(
             ['installedAt', 'installedBy', 'manifestId', 'packageId', 'version', 'versionId', 'withSampleData'],
         );

packages/cloud-connection/src/marketplace-install-local-plugin.ts

@@ -32,7 +32,7 @@
  *          → lists currently installed marketplace packages. Requires an
  *            authenticated principal (anonymous → 401); `installedBy` and
  *            `storageDir` are served only to a `manage_metadata` holder
- *            (#9011). The four routes above require `manage_metadata`
+ *            (commit 01074e551). The four routes above require `manage_metadata`
  *            outright (#8976).
  *
  *   DELETE /api/v1/marketplace/install-local/:manifestId
@@ -95,7 +95,7 @@ const ROUTE_BASE = '/api/v1/marketplace/install-local';
  *
  * `manage_metadata` is ADR-0066 D1's authoring capability and the SAME key the
  * platform's other metadata-write doors already require — `PUT`/`DELETE`
- * `/api/v1/meta/:type/:name`, `POST /meta/_migrate-stored`, and since #8919 the
+ * `/api/v1/meta/:type/:name`, `POST /meta/_migrate-stored`, and since commit b5378550e the
  * publish/rollback promotion verbs. These four routes are a metadata-write door
  * by every measure that matters: `POST` hot-registers an inline manifest's
  * objects into the shared registry and then runs `syncSchemas()` against the
@@ -998,7 +998,7 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
      * short list was served with `success: true` and nobody, anywhere, could
      * have known.
      *
-     * ## [#9011] Authenticated floor + field narrowing — the posture, ruled
+     * ## [commit 01074e551] Authenticated floor + field narrowing — the posture, ruled
      *
      * #8976 gated the four MUTATING doors and left this read as the only
      * anonymous door on the surface: `handleList` opened on `this.readAll()`,
@@ -1810,15 +1810,15 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
                 systemPermissions: Array.isArray(authz.systemPermissions) ? authz.systemPermissions : [],
             };
         } catch (err) {
-            // [#13279] `null` here means "nobody is authenticated", which is
+            // [commit 6a180e42d] `null` here means "nobody is authenticated", which is
             // not what a permission-store outage established. Re-raised.
             if (isAuthzStoreUnavailableError(err)) throw err;
             return null;
         }
     };
 
     /**
-     * [#9011] The ONE `401` this plugin issues — every door, one literal.
+     * [commit 01074e551] The ONE `401` this plugin issues — every door, one literal.
      *
      * The five routes now share an authenticated floor but NOT a capability
      * requirement (the four writes demand `manage_metadata`; the read narrows