From ab09610dbcdcbd11ea476ed9b800b886ba828ba1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 01:00:50 +0000 Subject: [PATCH] docs(cli): migrateStoredMetadata declines four things, not three The "Three things it deliberately declines" table predates #8957 (PR #9059, b740440bd), which added a fourth decline path in migrateStoredMetadata: a row stored under a non-canonical metadata type (a plural/alias spelling) is reported outcome: 'skipped' rather than rewritten, because rewriting a stored type spelling is an identity move (a new (org, type, name, package_id) key), out of this pass's reach. Verified by reading migrateStoredMetadata directly on origin/main (packages/metadata-protocol/src/protocol.ts) and enumerating every `record({ outcome: 'skipped' | 'failed', ... })` call site, then cross-checking against the function's own "## What it declines to touch, and says so" JSDoc. The lead-in sentence is reworded to drop the hard-coded count ("Three things" -> "What") so the table stays the single source of truth and a future fifth decline cannot leave stale prose behind it the same way. Fixes #9175 --- content/docs/deployment/cli.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx index e7d038d9f0..3d2fd4ed93 100644 --- a/content/docs/deployment/cli.mdx +++ b/content/docs/deployment/cli.mdx @@ -855,11 +855,12 @@ mutation projectors, exactly like an author's save. The history entry's source is `migrate-stored`, so a later diff shows which changes were an upgrade and which were somebody's edit. -Three things it deliberately declines, and names in the report rather than +What it deliberately declines, and names in the report rather than counting as done: | Not rewritten | Why | | :--- | :--- | +| A row stored under a non-canonical metadata type (a plural or alias spelling, e.g. `fields`) | Canonicalizing bodies is an edit; rewriting a stored *type* spelling is an identity move — a new `(org, type, name, package_id)` key — which this pass is not ruled to make. Re-author the item under its canonical type and drop the old row | | Types with no repository write path (`agent`) | Their write path records no history and would force a draft live — a half-write is worse than leaving the row to the read path | | Rows that still fail the current schema after conversion | That is a genuine contract violation, not chain-owned history. The write path's rejection is correct; fix the row in Studio | | A flow whose rename the conflict guard refused | The old node-type token is a live name something else owns here. Rewriting would clobber that owner, so the row fails loudly naming the token — never a silent skip |