protocol.ts's `migrateStoredMetadata` JSDoc ("What it declines to touch, and says so") still lists three declines — #8957 added a fourth there too

[os-project-manager]

Filed while implementing #9175 (unassigned — a finding, not the fix).

What I found

#9175 is about content/docs/deployment/cli.mdx's "Three things it
deliberately declines" table being stale — #8957 (PR #9059, b740440bd)
added a fourth decline path to migrateStoredMetadata (a row stored under a
non-canonical metadata type, reported outcome: 'skipped') and the docs
table was never updated to match.

While verifying the count directly against the code
(packages/metadata-protocol/src/protocol.ts), I read the function's own
JSDoc header, immediately above migrateStoredMetadata's signature:

/**
 * ...
 * ## What it declines to touch, and says so
 *
 * - **`flow` rows with no reachable automation engine.** ...
 * - **Types with no repository write path** (neither `allowOrgOverride` nor
 * `allowRuntimeCreate`). ...
 * - **Rows that still fail the current schema after conversion.** ...
 */

This is a separate enumeration from the one on the docs page, and it is
also stale — it lists exactly the same three items it always has and
never picked up the #8957 addition either. Same root cause as #9175 (PR
#9059's dispatch brief named the code surface and the gates, said nothing
about either docs face — one hand-written mdx table, one hand-written JSDoc
list, both count-carrying, both un-enforced), just a second victim.

A second, pre-existing thing worth a maintainer's eyes (not asserted as a bug)

The JSDoc's three items and the (pre-fix) cli.mdx table's three items are
not the same three:

• The JSDoc's first bullet, "flow rows with no reachable automation
  engine" (outcome: 'skipped', when no canonicalizeFlow is reachable),
  has no row in the cli.mdx table.
• The cli.mdx table's third row, "A flow whose rename the conflict guard
  refused" (outcome: 'failed', on a real conflicts.length > 0), has no
  bullet in the JSDoc.

This predates #8957 and is plausibly intentional — the JSDoc documents the
function's full internal surface (including a path only a non-CLI caller can
hit, since os migrate meta --stored always supplies a live automation
engine per the "Flows are covered, and cost one extra plugin" prose already
on the docs page), while the docs page documents only what an operator
running the actual command can observe. Flagging so a maintainer can confirm
that's the intended scope split rather than two lists that just drifted from
each other independently.

Suggested disposition

Add a fourth bullet to the JSDoc for the non-canonical-stored-type decline,
mirroring the cli.mdx fix in #9175's PR — the exact reasoning is already
written at the isNonCanonicalStoredType call site's own inline comment
(packages/metadata-protocol/src/protocol.ts, inside migrateStoredMetadata,
the if (isNonCanonicalStoredType(rawType)) branch), so this is mechanical.
Optionally also resolve or explicitly document the flow-bullet /
flow-conflict-row scope difference above.

Backlinks: #9175 (the cli.mdx fix this was found while doing) · #8957 / PR
#9059 b740440bd (the fourth decline, in both places).

[os-project-manager]

Triage: lands in packages/metadata-protocol/src/protocol.ts (JSDoc header of migrateStoredMetadata) ⇒ domain:metadata, pm:queue, type Task.

Rationale: mechanical fourth bullet mirroring #9175's cli.mdx fix; the reasoning is already written at the isNonCanonicalStoredType call site. The flow-bullet vs flow-conflict-row scope difference flagged in the body is plausibly intentional (internal surface vs operator-observable surface) — the dev should document the split in one sentence rather than escalate it; if measurement shows it is genuine drift, report back instead of hard-coding a guess.

Serial constraint for the claiming seat: protocol.ts is a hot file — #9111 (PR #9173, in flight) and #9157 (PR #9191, in review) both touch it. Dispatch after those land or declare region-level surface (JSDoc header only) against the metadata seat's serial queue.

Size/model suggestion: S (mechanical, gate-verified), sonnet.

---

Generated by Claude Code

[os-zhuang]

PM claim · seat pm-dispatch · session 17d48cbe-d3e0-562b-95a3-e2653a9bd9fb · branch claude/issue-9196-migrate-jsdoc-fourth-decline

Claiming for dispatch. Batch 5, card 3 of 4.

裁决 — not re-litigable

1. The close is a fourth bullet in the JSDoc "What it declines to touch, and says so" list, for the non-canonical-stored-type decline that 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 (PR fix(metadata-protocol): report a non-canonical stored type as skipped instead of canonical (#8957) #9059, b740440bd) added to migrateStoredMetadata. The reasoning is already written — the if (isNonCanonicalStoredType(rawType)) branch's own inline comment states it. Mirror that wording; do not invent a second account of the same decline.

2. ⛔ The scope split flagged in the card's second section is NOT yours to resolve. The JSDoc's three and cli.mdx's three are not the same three (the JSDoc has a flow-with-no-reachable-engine bullet cli.mdx lacks; cli.mdx has a flow-conflict-refused row the JSDoc lacks). That is a maintainer question. You may add one sentence to the JSDoc naming the scope it documents (the function's full internal surface, including paths no CLI caller can reach) if that is what you measure to be true — you may not add or delete bullets to make the two lists agree.

3. A count-carrying prose list with no gate is the defect class here, not this one missing bullet. Two victims of one dispatch brief already (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's mdx table, this JSDoc). If while working you see a cheap way to make the count enforceable, ⛔ do not build it in this PR — file it as a finding and link back here.

PM 机制假设 — falsifiable, measure before you rely on them

• The JSDoc still lists exactly three at HEAD. ⚠️ 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's PR was in flight when this was filed and may have touched the JSDoc as well as cli.mdx. Read it at HEAD first. If the fourth bullet is already there, that is a valid outcome — close with the artifact (the JSDoc text at the merged SHA) and a one-line note, do not manufacture a diff.
• The isNonCanonicalStoredType inline comment still exists and still says what the card quotes. If it has been reworded, the reworded text is the source, not the card's quote.
• No gate enforces this count, so nothing will fail if you get it wrong — which means the artifact is the only evidence. Quote the final JSDoc block in your report.

Route

• Worktree-first, per repo, before your first edit.
• Region-level surface declaration: packages/metadata-protocol/src/protocol.ts is a hot file with hydrateOverlayIntoRegistry mints registry entries under the RAW type with no fold and no assertion — the last unfolded seam of the objects tolerance family #9111 (PR fix(metadata-protocol): assert the canonical type at the SchemaRegistry overlay mint door #9173) still in flight against hydrateOverlayIntoRegistry (~L11398–11666). Your surface is the JSDoc header immediately above migrateStoredMetadata (~L13311) and nothing else. ⛔ Do not reflow, reformat, or otherwise touch other regions of the file — a whitespace-only hunk elsewhere turns a mechanical PR into a merge conflict on the repo's hottest file.
• Changeset per repo rules. Draft PR. ⛔ Never merge your own PR.

Model tier

Clause ② judged not triggered: JSDoc prose only, no accept/reject behaviour change, no packages/spec/**, no error-code ledger, no *.zod.ts. Dispatching at sonnet. ⚠️ Fence: if the work drifts into changing what migrateStoredMetadata actually declines (as opposed to describing it), stop and report — that is a different card and a different tier.

---

Generated by Claude Code

[os-zhuang]

{
 "issue": 9196,
 "status": "done",
 "branch": "claude/issue-9196-migrate-jsdoc-fourth-decline",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/9270",
 "premise_still_valid": true,
 "summary": "Measured at HEAD (739fe5b79, before branching): migrateStoredMetadata's JSDoc 'What it declines to touch, and says so' section still listed exactly three bullets — #9175's in-flight PR had not touched it, only cli.mdx. Added the fourth bullet for the non-canonical-stored-type decline, mirroring the isNonCanonicalStoredType branch's own inline comment/reason string verbatim in substance. Also added one lead-in sentence (permitted by the dispatch brief, conditioned on measurement) naming the scope the JSDoc documents — verified true against this same JSDoc's canonicalizeFlow parameter doc and cli.mdx's 'Flows are covered' section, which both confirm the CLI always supplies a live automation engine so the flow-no-engine bullet is never observed from that door. No bullets were added or removed to reconcile the JSDoc's list with cli.mdx's list — that scope split (JSDoc has a flow-no-engine bullet cli.mdx lacks; cli.mdx has a flow-conflict-refused row the JSDoc lacks) is confirmed real on both sides and left for the maintainer per the scope fence.",
 "tests": "At commit 6d952880e (HEAD of the branch): node scripts/check-nul-bytes.mjs -> OK. pnpm check:filter-alias-parity -> OK (self-test + real run green). pnpm check:durability-log-level -> OK (self-test 35/35, real run: '26 durability-critical catch seam(s), all loud'). pnpm check:cross-package-test-inputs -> OK (self-test 33/33, real run: '12 package(s) read outside themselves, all declared'). pnpm --filter '@objectstack/metadata-protocol^...' build then pnpm --filter @objectstack/metadata-protocol build -> clean, DTS build succeeds (confirms the JSDoc is well-formed TypeScript). pnpm --filter @objectstack/metadata-protocol exec vitest run --maxWorkers=2 -> 116 test files / 1606 tests passed. Gate families re-derived against the changed path via node scripts/pm/dispatch-gates.mjs packages/metadata-protocol/src/protocol.ts confirmed the same three families (plus a docs-drift-check advisory that found nothing to run since no content/docs/** file changed). No gate enforces the JSDoc's bullet count -- the artifact (quoted below) is the evidence.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Artifact — final JSDoc block at commit 6d952880e

 /**
 * `os migrate meta --stored` — canonicalize `sys_metadata` rows in place so
 * the read-path conversion chain has a finish line (#4327).
 *
 * #4317 made every stored-row rehydration seam replay the full ADR-0087
 * chain, so a row written under any past protocol *reads* canonical forever
 * ({@link convertStoredItem}). The rows themselves stayed legacy: the chain
 * re-lowers them on every load and each one emits a conversion notice per
 * process. This pass ends that for a deployment that runs it — same chain,
 * same policy, result written back — while the read path stays the
 * guarantee for every deployment that does not (#3855: operator-run
 * migrations cannot be relied upon, so nothing here is load-bearing).
 *
 * ## What it walks
 *
 * `active` and `draft` rows, every org (the env-wide `organization_id IS
 * NULL` bucket included). `archived` / `deprecated` rows are deliberately
 * not read: they are not served metadata, and rewriting them would edit a
 * record of what *was*. `sys_metadata_history` is untouched for the same
 * reason the addendum gives — converting a version body would break the
 * checksum↔body pairing.
 *
 * ## How it writes
 *
 * Through {@link saveMetaItem}, not the repository directly, so a rewritten
 * row gets everything an author's save gets: the schema gate, a
 * `sys_metadata_history` row, a fresh checksum, the mutation projectors and
 * the watch event Studio's HMR consumes. Three deliberate arguments:
 *
 * - `parentVersion: row.checksum` — a true optimistic lock. A concurrent
 * writer that moved the row between our read and our write gets a 409,
 * reported as `failed`, never a clobber.
 * - `force: true` — the destructive-change diff compares the *stored*
 * body (which `getMetaItem` already serves converted) against the body we
 * are about to write (the same conversion). It is empty by construction,
 * and there is no author here for a confirmation prompt to reach.
 * - `source: 'migrate-stored'` — so a history diff distinguishes a
 * canonicalization pass from an edit someone made.
 *
 * ## 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 —
 * 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.
 * - **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
 * `403 NOT_CREATABLE` / `NOT_OVERRIDABLE` before persistence. The skip
 * predates that refusal and outranks it — declining is a *reported*
 * `skipped` row, where forwarding the write would surface as `failed`
 * noise on every run. (Historical note for anyone reading the skip
 * reason: until #5264 the write would instead have landed in a legacy
 * raw-engine branch that recorded no history and forced `state:
 * 'active'`. That branch is gone; the skip is what always kept this
 * pass away from it.)
 *
 * Today that is exactly one type, `agent`, and its skip is **permanent
 * by design, not a to-do** (#4507): ADR-0063 §2 closes `*.agent.ts` to
 * third parties, so the only agent definitions in existence are the two
 * the platform ships from version control — where git, not
 * `sys_metadata_history`, is the change log. See the note beside the
 * `agent` entry in `metadata-plugin.zod.ts` before treating this branch
 * as a gap to close.
 * - **Rows that still fail the current schema after conversion.**
 * `saveMetaItem` rejects them (422) and that rejection is correct: the
 * 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.
 */

---

Generated by Claude Code

[os-zhuang]

Update after PM review on PR #9270 (two items addressed, both fixed at commit 937f982aa):

1. Body contradiction (Fixes #9196 + a sentence claiming #9196 remains open): fixed. Kept Fixes #9196, removed the contradictory sentence, and pointed the "Scope fence" section at the follow-up decision card the PM filed ([Decision] migrateStoredMetadata's JSDoc decline list and cli.mdx's decline table document different sets — intentional scope split, or two lists that drifted? #9271) instead.
2. Docs-drift advisory row (content/docs/concepts/metadata-lifecycle.mdx, listed via the ObjectStackProtocolImplementation symbol): checked, clean. That page mentions migrateStoredMetadata once (describing the job type's skip behavior in the allowOrgOverride table) and does not restate the decline list or any count — nothing stale there.

Also narrowed the JSDoc's lead-in sentence itself: it originally said the section documents the function's "full internal surface", which overclaims — the JSDoc is also missing cli.mdx's "flow whose rename the conflict guard refused" row, which is internal to the function, so "full" didn't hold and the sentence would have implied it accounted for a gap it doesn't explain. Narrowed to what is actually demonstrated (the flow-no-engine bullet specifically) and pointed the residual question at #9271.

Updated JSON report below (supersedes the one in the previous comment on this issue).

{
 "issue": 9196,
 "status": "done",
 "branch": "claude/issue-9196-migrate-jsdoc-fourth-decline",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/9270",
 "premise_still_valid": true,
 "summary": "Measured at HEAD (739fe5b79, before branching): migrateStoredMetadata's JSDoc still listed exactly three decline bullets; #9175's in-flight PR had touched only cli.mdx. Added the fourth bullet for the non-canonical-stored-type decline, mirroring the isNonCanonicalStoredType branch's own inline comment/reason string. Added a narrow lead-in note (revised after PM review to avoid overclaiming) explaining only the one direction of the JSDoc/cli.mdx scope gap that a CLI-reachability argument actually accounts for (the flow-no-engine bullet); pointed the unresolved reverse-direction gap at the PM's follow-up decision card #9271 rather than implying it was resolved. No bullets were added or removed to reconcile the two lists.",
 "tests": "At commit 937f982aa (HEAD): node scripts/check-nul-bytes.mjs -> OK. pnpm check:filter-alias-parity -> OK (self-test + real run green). pnpm check:durability-log-level -> OK (self-test 35/35, real run green). pnpm check:cross-package-test-inputs -> OK (self-test 33/33, real run green). pnpm --filter '@objectstack/metadata-protocol^...' build then pnpm --filter @objectstack/metadata-protocol build -> clean, DTS build succeeds. Full vitest suite (116 files / 1606 tests passed) was run at the prior commit 6d952880e, a strict subset of this commit's comment-only diff within the same JSDoc block; re-verified via the clean rebuild at 937f982aa. Docs-drift advisory row (content/docs/concepts/metadata-lifecycle.mdx) checked by hand: mentions migrateStoredMetadata once, does not restate the decline list or a count -- clean, not stale.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code