From 6d952880ee49ff59de3aedbcb9e3987d850c8d5b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 08:51:19 +0000 Subject: [PATCH 1/2] docs(metadata-protocol): add the #8957 fourth decline bullet to migrateStoredMetadata's JSDoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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, b740440bd) 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 --- packages/metadata-protocol/src/protocol.ts | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/packages/metadata-protocol/src/protocol.ts b/packages/metadata-protocol/src/protocol.ts index 6617594ed9..0ac243887b 100644 --- a/packages/metadata-protocol/src/protocol.ts +++ b/packages/metadata-protocol/src/protocol.ts @@ -13090,6 +13090,11 @@ export class ObjectStackProtocolImplementation implements * * ## What it declines to touch, and says so * + * This section documents the function's full internal surface, including + * paths no CLI caller can reach: `os migrate meta --stored` always passes + * its own automation engine (see `canonicalizeFlow` above), so the first + * bullet below is never observed from that door. + * * - **`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 +13125,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//`) and drop the non-canonical + * row. */ async migrateStoredMetadata(request: { /** Write. Omitted / false = preview: reports what it would do, writes nothing. */ From 937f982aa79ec9c1c2f2c8454cf31b9871192cfb Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 09:14:11 +0000 Subject: [PATCH 2/2] 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 --- packages/metadata-protocol/src/protocol.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/metadata-protocol/src/protocol.ts b/packages/metadata-protocol/src/protocol.ts index 0ac243887b..bbfc144559 100644 --- a/packages/metadata-protocol/src/protocol.ts +++ b/packages/metadata-protocol/src/protocol.ts @@ -13090,10 +13090,13 @@ export class ObjectStackProtocolImplementation implements * * ## What it declines to touch, and says so * - * This section documents the function's full internal surface, including - * paths no CLI caller can reach: `os migrate meta --stored` always passes - * its own automation engine (see `canonicalizeFlow` above), so the first - * bullet below is never observed from that door. + * 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