docs(metadata-protocol): add the #8957 fourth decline bullet to migrateStoredMetadata's JSDoc (#9270)

* docs(metadata-protocol): add the #8957 fourth decline bullet to migrateStoredMetadata'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(metadata-protocol): narrow the scope lead-in sentence, per PM review

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

---------

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

Author: os-zhuang

packages/metadata-protocol/src/protocol.ts

@@ -13090,6 +13090,14 @@ export class ObjectStackProtocolImplementation implements
      *
      * ## What it declines to touch, and says so
      *
+     * This section documents the function's internal surface, which is not
+     * always identical to what an operator running the CLI can observe:
+     * `os migrate meta --stored` always passes its own automation engine
+     * (see `canonicalizeFlow` above), so the first bullet below is never
+     * observed from that door. That does not by itself account for every
+     * difference between this list and `content/docs/deployment/cli.mdx`'s
+     * decline table — see #9271.
+     *
      * - **`flow` rows with no reachable automation engine.** Flow-node
      *   conversions carry ADR-0078's open-namespace conflict guard, which
      *   needs the engine's live executor registry. When one is reachable —
@@ -13120,6 +13128,17 @@ export class ObjectStackProtocolImplementation implements
      *   body is a genuine contract violation, not chain-owned history. They
      *   surface as `failed` with the validation message, keep reading through
      *   the chain, and stay fixable in Studio.
+     * - **Rows stored under a non-canonical metadata type spelling** (#8957,
+     *   {@link isNonCanonicalStoredType}). This pass canonicalizes BODIES;
+     *   rewriting a stored type spelling is an identity move — a new
+     *   `(org, type, name, package_id)` key, not an edit — so it is out of
+     *   its reach. Nothing on the canonical type can see such a row — no
+     *   registry read, no compliance query — and the batch publish refuses
+     *   it for the same reason (`STORED_TYPE_NOT_CANONICAL`). Reported
+     *   `skipped`, not `failed`: nothing is broken about this pass, the row
+     *   is simply outside its reach. Re-author the item under the canonical
+     *   type (`PUT /meta/<canonical>/<name>`) and drop the non-canonical
+     *   row.
      */
     async migrateStoredMetadata(request: {
         /** Write. Omitted / false = preview: reports what it would do, writes nothing. */