docs(cloud-connection): re-anchor the dead tracker citations in packages/cloud-connection/src to the commits that decided them - #20735
Conversation
…ges/cloud-connection/src to the commits that decided them Ten comment sites (five in marketplace-install-local-plugin.ts, five in two test files) cited three tracker numbers that no longer resolve. Each now cites the commit that decided what the line describes, in ruling C+D's form C: 01074e5 for the install-local listing's authenticated floor and field narrowing, b537855 for the /meta promotion verbs' manage_metadata gate, and 6a180e4 for re-raising a permission-store outage instead of reading it as "nobody is authenticated". Comment prose only: ten lines out, ten in, every file keeps its line count. Claude-Session: https://claude.ai/code/session_local_1d2a197c-c20e-4e90-9be8-413d4d432289 Co-authored-by: Claude <noreply@anthropic.com>
…written docblocks reach dist Built at base and at head, index.js, index.cjs, index.d.ts and index.d.cts differ, and the difference is comment text only (parser tokens identical). Claude-Session: https://claude.ai/code/session_local_1d2a197c-c20e-4e90-9be8-413d4d432289 Co-authored-by: Claude <noreply@anthropic.com>
📓 Docs Drift CheckThis PR changes 1 package(s): 16 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: ⛔ 5 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails. What this run could not see
Coarse fallback — 3 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): Which tree this was computed onThis run read A worktree cut from an older # while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 8858ee03fecffe7e30ec0a005f5fadb086da7ad7 && git checkout 8858ee03fecffe7e30ec0a005f5fadb086da7ad7
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 36d043be171971aae42d923281c262f910eecd8a 16a88d69b265a3cea7095230123125e80adf8ca7 && git checkout -B drift-repro 36d043be171971aae42d923281c262f910eecd8a && git merge --no-ff 16a88d69b265a3cea7095230123125e80adf8ca7
node scripts/docs-audit/affected-docs.mjs --json 36d043be171971aae42d923281c262f910eecd8a
|
Contract reviewServed-tier: PR #20735 (stage 9 of card #20594, What was read and sampled. The file list is one page of 4 entries (page 2 answers 0). The net diff (119 lines) and the per-file patches were read in full. The change has 10 rewritten sites on 10 lines in 3 files; the brief's sample floor (12 sites, 6 files) is above the population, so the sample is the whole population: all 10 sites, all 3 files, including both test files, and the whole of ① Derived judgmentsAccept-set and public-surface changes the diff implies: none. No route, error code, refusal text, type, export, identifier or test assertion moves. The one public consequence is the changeset: a (1) Comment-only: yes. A line diff of each touched file at base and head (both fetched by REST) shows exactly 10 changed line pairs (5 / 3 / 2) and every changed line is a docblock (2) Anchors, all 10 sites checked, no wrong or unsupported anchor:
(3) Numbers. Removed lines carry only #9011 (7), #8919 (2) and #13279 (1); each answers 404 by REST (probed by exit code, with #8976 as the 200 control). No number answering 200 was removed or rewritten: #8976 on the neighbouring (4) Line counts. The file list reads additions equal to deletions per source file (3/3, 2/2, 5/5), and the fetched files measure 1,969 / 377 / 308 lines at both base and head. The changeset is a new 11-line file. Right. (6) ② Semver level
③ Boundary flags
Implemented-by: VERDICT: PASS |
Part of #20594
Clause-②: no
What changed
This is stage 9 of the
domain:clilane 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 saysPart of.That is 10 sites on 10 lines in 3 files, covering 3 numbers, rewritten to 3 distinct commits:
src/marketplace-install-local-plugin.ts(3 numbers);*.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/orscripts/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
patchchangeset for@objectstack/cloud-connectionrides along, because the rewritten docblocks reachdist(measured below). That is stage 6's case (PR #20703), not stages 5 and 7's.Census:
packages/cloud-connection, before and afterInstrument. The gate's own
node scripts/check-issue-citations.mjs --census --json, read-only and unchanged, run underwith-fleet.sh --readfor the token. The count is itsallocated-but-absentfindings underpackages/cloud-connection/. Both runs enumerated the whole board.allocated-but-absentpackages/cloud-connectionsitesb291fcdae9, run 2026-09-29T22:34:12Z to 22:38:18Z4a1f38a4e6, run 22:44:08Z to 22:47:58ZThe 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 (resolves32,994,resolves-as-pull-request1,984,cross-repo-unjudged995) are equal in both runs.packages/cloud-connection/srcis byte-identical at4a1f38a4e6and at the head.Supplementary scan (test files included). The gate's exported
extractCitationsandclassifyCitationover all 44.tsfiles undersrc/, with the board from the gate's ownprobeBoard: 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 blameat 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.#9011marketplace-install-local-plugin.ts:35,:1001,:1821;marketplace-install-local-capability-enumeration.test.ts:50,:303;marketplace-install-local-list-posture.test.ts:4,:30201074e551: the install-local listing requires an authenticated principal (anonymous gets 401) and servesinstalledBy/storageDironly to amanage_metadataholder, the maintainer's 2026-08-16 "Option 3" that:1008still names; it also extracts the onerefuseUnauthenticated401 envelope that:1821describes. 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:302now reads "The wire shape before commit 01074e5" for "The pre-(number) wire shape".#8919marketplace-install-local-plugin.ts:98;marketplace-install-local-capability-enumeration.test.ts:40b5378550e: gates the/metapublish and rollback promotion verbs onmanage_metadataand addsmeta-write-door-capability-enumeration.test.ts, the enumeration pin:40names as its precedent. Both lines blame toe0695b582, 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 landedb5378550eanswers 404 too.#13279marketplace-install-local-plugin.ts:18136a180e42d: a failed permission-store read raisesAuthzStoreUnavailableErrorinstead of resolving as an unauthenticated or capability-less principal, and each fail-closed transportcatchre-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 ofmain(merge-base --is-ancestoragainst36d043be17, exit 0 for all 3). The checkout is not shallow. The control leg818fcafda(2026-08-16, the parent of the oldest anchorb5378550eof 2026-08-16) exits 0, and the negative control, this branch's own16a88d69b2, 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 inpackages/cloud-connection/src, whose later halves the citation grammar does not read (#6603/#7020,#4127/#4251twice); every half answers 200, so none is dead.Mechanical guard: no code token moves
H2 holds on the comment-stripped reading; the emitted
distis 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
b291fcdae9and at4a1f38a4e6. Controls mutate the head text in memory only.'Authentication required.'to'Authentication requireD.'inrefuseUnauthenticated): exactly 1 differingStringLiteral, at token 7,973 ofmarketplace-install-local-plugin.ts(exit 1).Emitted
dist.pnpm --filter @objectstack/cloud-connection buildat the head, then at base (the base tree ofpackages/cloud-connection/srcrestored in place under a trap-armed restore; an on-disk probe read[#13279]1 andcommit 6a180e42d0 before that build; afterwards every touched blob equals its HEAD blob andgit diff HEADis empty), with the same dependency builds:index.cjs,index.js,index.d.tsandindex.d.ctsdiffer;index.cjs.mapandindex.js.mapare equal.distfiles reads 0 differing tokens (19,465 / 18,741 / 16,868 / 16,868), so the wholedistdelta is comment text. Its code control (a code line appended after a newline) reads COUNT DIFFERS in each.dist: "commit 01074e5" appears 2 times inindex.jsandindex.cjsand 3 times in each declaration file, where the base build carries#9011in the same places.scripts/ablation-replace.mjs, anchor'Authentication required.'hit 1 to 0, planted marker 0 to 1, blob2ef0f0ae8bacto77c3cef6324b;scripts/ablation-dist-preflight.mjsfound the marker indist):index.cjs,index.jsand both.mapfiles differ from the head build. The blob was restored to HEAD2ef0f0ae8bacwithgit diff HEADempty,distwas rebuilt, its six sha256 values equal the first head build, and the preflight in--absentmode 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
patchfor@objectstack/cloud-connection(.changeset/cloud-connection-provenance-anchors.md), in PR #20632's form.@objectstack/cloud-connection'sfiles[]isdist,README.mdandCHANGELOG.md, and the build above emits differentindex.js/index.cjs/index.d.ts/index.d.ctsat base and head, so this diff publishes.check-changeset-no-major,check-empty-changeset,check-adr-0087-registrationandcheck-changeset-fixedall exit 0.Gates (head
16a88d69b2)This host has no
flock, soos-verify-lock.shran in its declared unlocked mode. Its disclosure, verbatim, from each run (the closure build at4a1f38a4e6, whosepackages/cloud-connectionand dependency closure are byte-identical to this head; the whole-workspace build, the tests and the typecheck at this head; the threedistbuilds at4a1f38a4e6, whosepackages/cloud-connection/srcis byte-identical to this head):@objectstack/cloud-connectionwith 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 sixdistfiles after the whole build equal the first head build by sha256.vitest run: 30 files, 397 tests passed (every*.test.tsundersrc/), at this head and before the merge.@objectstack/cloud-connectionhas notypecheckscript; it is aDEBTentry inscripts/check-type-check-coverage.mjs(13 errors: 11 TS2493, 2 config-tier).tsc --noEmit -p tsconfig.jsonexits 2 with exactly those 13 (11 TS2493, 2 TS2550), all in three test files this PR does not touch (cloud-connection-plugin.test.ts4,connection-credential-store.test.ts7,marketplace-install-local-bundle.test.ts2).--listFilescompiles all three touched files and all 30 test files.check:type-check-debtandcheck:type-check-coverageexit 0, and thedistbuild's DTS step, this package's type gate, succeeds.pnpm lint(eslint . --no-inline-config) exits 0 at this head (2026-09-29T23:01:12Z to 23:01:39Z).origin/main(36d043be17),node scripts/check-issue-citations.mjs --base origin/mainreports "no issue citations added against 36d043b (1 file(s) read)" (exit 0); pinned--base 36d043be17reads the same.node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commandsderived 61 families. All 61 exit 0, and--ranwith 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.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)
b291fcdae9the filtered census answers 5 sites on 5 lines, 3 numbers, all insrc/marketplace-install-local-plugin.ts, as on the seat's0be898499f. The whole-repo count is 1,153.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 chore: version packages #20639 touchespackages/cloud-connection, inCHANGELOG.mdandpackage.json) or for an unfound anchor.distreading. The parser leaf-token diff of all 3 touched files is empty with its controls firing. The emitteddistdiffers, and the difference is comment text only (token-identicaldistwith a code control). That is why the changeset ships.Acceptance notes
packages/cloud-connection/src:#9011in the threedescribetitles ofmarketplace-install-local-list-posture.test.ts(:206,:247,:287, no assertion text), and#9011in thenotestring of theGET /api/v1/marketplace/install-localrow ofcloud-connection-route-ledger.ts(:215), a runtime string already recorded inscripts/doc-authoring-prose-id.baseline.json. They stay on the card for its form-D stage; no string moved here.src/**, a later stage of the card:packages/cloud-connection/vitest.config.ts:64cites#16917(404). The other citations inpackages/cloud-connectionoutsidesrc/**(CHANGELOG.mdexcluded) answer 200:README.md:108(#10805,#12681) andvitest.config.ts(#10374,#11480,#7668/#7778,#7955,#10374/#13522).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.origin/main. The branch mergedorigin/mainonce (16a88d69b2, merging36d043be17:service-automationand two changesets, nothing inpackages/cloud-connectionor its dependency closure).Deviations
Claude-SessionplusCo-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