[Decision] migrateStoredMetadata's JSDoc decline list and cli.mdx's decline table document different sets — intentional scope split, or two lists that drifted? #9271

Filed by the pm-dispatch seat, split out of #9196 so it survives that card's close. ⛔ Not a defect claim — a scope question with two defensible answers, which is why it is a decision card and not a fix.

The observation

migrateStoredMetadata (packages/metadata-protocol/src/protocol.ts) is described by two hand-written, count-carrying enumerations, and they are not the same enumeration:

So each list has exactly one member the other lacks, and the two gaps point in opposite directions.

Why it is plausibly intentional

The JSDoc documents the function's full internal surface, including a path no CLI caller can reach: os migrate meta --stored always supplies a live automation engine (the JSDoc's own canonicalizeFlow parameter doc says so, and cli.mdx's "Flows are covered, and cost one extra plugin" section confirms the CLI boots an inert engine specifically so that skip path is never observed from that door). The docs page documents only what an operator running the actual command can observe. Under that reading both lists are correct for their own audience and the difference is a feature.

The flow-conflict row cuts the other way, though — that path is internal to the function, so if the JSDoc's remit is "the full internal surface", its absence there is a genuine omission rather than a scope choice. That asymmetry is what makes this worth asking rather than assuming.

Why it matters beyond these two files

This is the third instance this shift of a hand-written, count-carrying list with nothing enforcing the count:

• cli.mdx:857 says migrateStoredMetadata declines "Three things" and tables three — #8957 added a fourth this shift, and the docs face was never carried #9175 — cli.mdx's table missed migrateStoredMetadata reports a row stored under a non-canonical type as canonical — the stored migration has no finish line for the second-namespace residue #8957's addition
• protocol.ts's migrateStoredMetadata JSDoc ("What it declines to touch, and says so") still lists three declines — #8957 added a fourth there too #9196 — the JSDoc missed the same addition, independently
• findReferencesToMeta answers {references: []} for every target type absent from REFERENCE_PATHS — the "Used by" panel is silent by construction for 20+ declared types #9190 — REFERENCE_PATHS hand-curated, with A draft row stored under a manifest-absent plural (fields, seeds, external_catalogs, translations) is promotable by publishPackageDrafts and lands ACTIVE in the second namespace #8908 having measured a hand-written list two members short

The pattern is the finding. Two prose lists describing one function will drift again whichever way this question is answered; the answer determines whether the fix is "keep them in sync" or "state their different remits so nobody tries to".

The decision

• A — intentional scope split. Add one explicit sentence to each list naming its remit (JSDoc: full internal surface; cli.mdx: operator-observable surface), and add the flow-conflict bullet to the JSDoc, since that path is internal and its absence is not explained by the split. The two lists then legitimately differ by exactly one member, for a stated reason.
• B — drift. Reconcile both to the same set (5 members each), and accept that cli.mdx then documents a path an operator cannot reach.
• C — something else, e.g. derive one from the other, or collapse to a single source with the docs page transcluding it.

PM's read: A. The two audiences are real and the CLI page documenting an unreachable path would be a small lie of its own; but the flow-conflict omission is not explained by the split and should be closed either way. ⚠️ Stated as a recommendation, not a measurement — I have not verified that the flow-conflict path is unreachable from any non-CLI caller, and if it is reachable only from the CLI then A's second half is wrong and the lists differ correctly by one member in each direction.

Backlinks

#9196 (the JSDoc's fourth bullet, closed by PR #9270) · #9175 (the cli.mdx fix) · #8957 / PR #9059 b740440bd (the fourth decline itself) · #9190, #8908 (the hand-curated-list pattern)