Uh oh!
There was an error while loading. Please reload this page.
docs(metadata-protocol): add the #8957 fourth decline bullet to migrateStoredMetadata's JSDoc - #9270
Conversation
…teStoredMetadata's JSDoc `migrateStoredMetadata`'s "What it declines to touch, and says so" JSDoc section listed three decline paths and never picked up the fourth one #8957 (PR #9059, b740440) added: a row stored under a non-canonical metadata type, reported `outcome: 'skipped'`. Mirrors the wording already written at the `isNonCanonicalStoredType` call site's own inline comment. Also adds one lead-in sentence naming the scope this JSDoc section documents (the function's full internal surface, including the no-reachable-automation-engine path no CLI caller can reach, since `os migrate meta --stored` always supplies its own engine) — measured true against this same JSDoc's own `canonicalizeFlow` parameter doc and against cli.mdx. Does not add or remove any bullet to reconcile the JSDoc's three (now four) items with cli.mdx's four items; that scope split is a maintainer question, tracked on #9196. Fixes#9196
📓 Docs Drift CheckThis PR changes 1 package(s): 1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:
⛔ 2 release-owned page(s) also name something this change touched. These are read-only:
What this run could not seeCoarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop):
|
…view The lead-in sentence added in the previous commit said the section documents the function's "full internal surface" -- overclaiming: the JSDoc is also missing cli.mdx's flow-conflict-refused row, which IS internal to the function (not CLI-caller-dependent), so "full" did not hold. Narrowed the claim to what is actually demonstrated (the flow-no-engine bullet specifically), and pointed the residual scope-split question at the follow-up decision card (#9271) the PM filed for it, rather than implying this sentence explains every gap between the two lists. Fixes#9196
⛔ merge queue 构建失败 — 先分诊，再决定要不要重排队列构建 32017635668 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集）， 失败的 job（日志抽取，best effort）：
历史信号：
分诊清单：
Generated by Claude Code · merge-queue-triage workflow (#4859) |
Fixes#9196
What
migrateStoredMetadata's own JSDoc header (packages/metadata-protocol/src/protocol.ts, immediately above the method signature, ~L13052–13142) has a "## What it declines to touch, and says so" section. Measured at HEAD (739fe5b79, before this branch): it still listed exactly three decline paths, and had never picked up the fourth #8957 (PR #9059,b740440bd) added — a row stored under a non-canonical metadata type, reportedoutcome: 'skipped'.This PR adds that fourth bullet, mirroring the wording already written at the
isNonCanonicalStoredType(rawType)branch's own inline comment (same file, ~L13254–13268) and itsreason:string.It also adds a short lead-in note to the section:
os migrate meta --storedalways passes its own automation engine (per this same JSDoc'scanonicalizeFlowparameter doc a few lines above, and percontent/docs/deployment/cli.mdx's "Flows are covered, and cost one extra plugin" section, which confirms the CLI boots an inert engine specifically for this), so the JSDoc's "flowrows with no reachable automation engine" bullet is never observed from the CLI door — that is whycli.mdx's decline table has no row for it. The note is deliberately narrow: it explains only that one direction of the discrepancy, not the reverse one (the JSDoc lackingcli.mdx's "flow whose rename the conflict guard refused" row, which is internal to the function and so isn't accounted for by a CLI-reachability argument). No bullets were added or removed to reconcile the two lists.Scope fence — not resolved here (by design)
The two lists' gaps run in opposite directions and are not both explained by the same reasoning (see the note above). That is a maintainer question, tracked separately as #9271 ("[Decision]
migrateStoredMetadata's JSDoc decline list andcli.mdx's decline table document different sets — intentional scope split, or two lists that drifted?"). This PR does not resolve it — no bullets were added or removed to make the two lists agree.Region-level surface
Only the JSDoc header immediately above
migrateStoredMetadatawas touched — two additive hunks, no reflow or reformatting elsewhere inprotocol.ts(the repo's hottest file, with PR #9173 in flight againsthydrateOverlayIntoRegistryat a different region).Tests
At commit
937f982aa(current HEAD of this branch):node scripts/check-nul-bytes.mjs— OK.pnpm check:filter-alias-parity— OK (self-test + real run green).pnpm check:durability-log-level— OK (self-test 35/35, real run green).pnpm check:cross-package-test-inputs— OK (self-test 33/33, real run green).pnpm --filter '@objectstack/metadata-protocol^...' buildthenpnpm --filter @objectstack/metadata-protocol build— clean (DTS build succeeds, JSDoc is well-formed).pnpm --filter @objectstack/metadata-protocol exec vitest run --maxWorkers=2— 116 test files / 1606 tests passed (run at the prior commit6d952880e; this commit is comment-only within the same block, re-verified via the clean rebuild above).Gate families re-derived against the actual changed path via
node scripts/pm/dispatch-gates.mjs packages/metadata-protocol/src/protocol.ts: the three above, plus a docs-drift-check advisory (content/docs/concepts/metadata-lifecycle.mdx, via theObjectStackProtocolImplementationsymbol) — checked and clean: that page mentionsmigrateStoredMetadataonce (thejobtype's skip behavior) but does not restate the decline list or any count, so it is not stale.No gate enforces the JSDoc's bullet count — the artifact is the evidence; the full block is quoted verbatim in the linked issue's dev report.
Changeset
None. This is a comment-only change (no accept/reject behaviour, no exported symbol, no runtime effect) —
skip-changesetlabel applied.Generated by Claude Code