From 0d3ea23920ad76033fabb7e39632ef3cfd85292b Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 09:30:07 +0000 Subject: [PATCH] docs(metadata-protocol): name each decline list's remit and close the JSDoc's flow-conflict gap (#9271) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `migrateStoredMetadata` is described by two hand-written decline lists that were not the same enumeration, and nothing enforced either count. - `protocol.ts` JSDoc: add the missing "a flow whose rename the conflict guard refused" bullet. That path is internal to the function and reachable from every door, so its absence was a real omission rather than a scope choice. - `protocol.ts` JSDoc: the remit sentence PR #9270 landed closed with "that does not by itself account for every difference ... see #9271". With the bullet above added, it now does, so the clause is restated as the finished fact it has become. - `cli.mdx`: name the decline table's remit — the operator-observable surface — and say which single member the JSDoc carries that it does not, and why no operator door can reach it. The two lists now differ by exactly one member, in one direction, for a stated reason. Prose only; no behaviour change. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_017qYPmkKEsfbWY1yVg83p8F --- content/docs/deployment/cli.mdx | 7 ++++++- packages/metadata-protocol/src/protocol.ts | 21 ++++++++++++++++----- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx index b182aa1e91..897b353ab0 100644 --- a/content/docs/deployment/cli.mdx +++ b/content/docs/deployment/cli.mdx @@ -856,7 +856,12 @@ is `migrate-stored`, so a later diff shows which changes were an upgrade and which were somebody's edit. What it deliberately declines, and names in the report rather than -counting as done: +counting as done. This table is the **operator-observable** surface — what a +run can actually report, from the command above or the route below. The +function's own JSDoc in `packages/metadata-protocol/src/protocol.ts` documents +its full internal surface instead, and so lists one decline more: flow rows +skipped for want of a reachable automation engine, which neither operator door +can produce, because both supply a live one. | Not rewritten | Why | | :--- | :--- | diff --git a/packages/metadata-protocol/src/protocol.ts b/packages/metadata-protocol/src/protocol.ts index f2a5c9f5fb..8b582ed815 100644 --- a/packages/metadata-protocol/src/protocol.ts +++ b/packages/metadata-protocol/src/protocol.ts @@ -13183,13 +13183,15 @@ 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: + * This section documents the function's FULL 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. + * observed from that door. That is now the only difference between this + * list and `content/docs/deployment/cli.mdx`'s decline table, which + * documents the operator-observable surface and so carries the other + * four. #9271 ruled that split intentional: keep each list correct for + * its own audience rather than reconciling them. * * - **`flow` rows with no reachable automation engine.** Flow-node * conversions carry ADR-0078's open-namespace conflict guard, which @@ -13197,6 +13199,15 @@ export class ObjectStackProtocolImplementation implements * passed as `canonicalizeFlow`, or resolved from the services registry * (#4498) — flows are migrated like anything else (#4454); when none is, * they are reported `skipped` with that reason, never counted done. + * - **A flow whose rename that guard refused.** With an engine reachable, + * the same open-namespace check can still find the old node-type token + * is a LIVE name something else owns here. The conversion is refused and + * the row reported `failed`, naming the token and its path: rewriting + * would clobber that owner, and a quiet skip would hide it. Unlike the + * bullet above this one IS reachable from every door — the CLI boots an + * inert engine to hold the registry, and `POST /meta/_migrate-stored` + * resolves a live one from the services registry — so + * `content/docs/deployment/cli.mdx` carries it too. * - **Types with no repository write path** (neither `allowOrgOverride` nor * `allowRuntimeCreate`). This pass declines them, and since #5086 it * would have no choice: `saveMetaItem` refuses a code-only type with